Une fois une mission attribuée, vous pouvez en suivre la progression géographique : la position GPS du convoyeur en route, ainsi que les étapes planifiées (waypoints) avec leur heure d’arrivée estimée. Ce guide couvre les deux endpoints de suivi et la bonne façon de les consommer.
RGPD — données minimisées. Les endpoints de suivi n’exposent que des coordonnées et des horodatages. Aucune donnée d’identité du convoyeur (nom complet, téléphone, e-mail) n’est renvoyée par ces endpoints. Le suivi géographique est une donnée de localisation rattachée à l’exécution du contrat de transport.

​
Vue d’ensemble

Positions GPS

GET /transports/{id}/positions — la trace du convoyeur (latitude, longitude, vitesse, cap, horodatage), filtrable par date avec since.

Étapes planifiées

GET /transports/{id}/waypoints — les étapes du trajet avec leur ETA et la date de passage.
Préférez les webhooks (événements tracking) au polling intensif. Configurez un endpoint webhook pour être notifié des changements d’état, et ne sollicitez les positions que lorsque c’est réellement nécessaire (par exemple à la réception d’un événement, ou à un intervalle raisonnable côté affichage). Voir la section Webhooks plutôt que polling.

​
Authentification

Toutes les requêtes de suivi utilisent l’en-tête X-Api-Key et requièrent le scope transports:read. 
X-Api-Key: med_live_a1b2c3d4e5f6...
Une mission qui n’appartient pas au groupe de votre clé renvoie 404 Not Found (jamais 403), afin de ne pas révéler son existence.

​
Positions GPS du convoyeur

GET /transports/{id}/positions
Renvoie la liste des positions GPS relevées pour la mission, de la plus ancienne à la plus récente dans la fenêtre demandée.

​
Paramètres

​
id
string
requis
Identifiant de la mission (offer_id).
​
since
string
Date ISO 8601 (date-time). Ne renvoie que les positions postérieures à cette date. Idéal pour ne récupérer que les nouveaux points depuis votre dernier appel.
​
limit
integer
défaut:"100"
Taille de page. Valeur par défaut 100, maximum 500.
​
cursor
string
Curseur opaque de pagination renvoyé par la page précédente.

​
Réponse

La réponse est un objet contenant un tableau data de positions.
​
data
Position[]
Liste des positions relevées.

​
Exemple

curl -s -X GET \
  "https://api.myexpressdriver.com/v1/transports/-O9xAbCdEf/positions?since=2026-07-01T08:00:00Z&limit=200" \
  -H "X-Api-Key: med_live_a1b2c3d4e5f6..."
Réponse 200
{
  "data": [
    {
      "lat": 48.8566,
      "lng": 2.3522,
      "ts": "2026-07-01T08:14:32Z",
      "speed_kmh": 0,
      "heading_deg": 0
    },
    {
      "lat": 48.7264,
      "lng": 2.6571,
      "ts": "2026-07-01T08:42:10Z",
      "speed_kmh": 118,
      "heading_deg": 142
    }
  ]
}
Cet endpoint renvoie un objet { "data": [...] } borné par limit, sans champ next_cursor. Pour ne récupérer que les nouveaux points entre deux appels, mémorisez le dernier ts reçu et repassez-le dans le paramètre since.

​
Étapes planifiées (waypoints)

GET /transports/{id}/waypoints
Renvoie les étapes planifiées du trajet, avec leur heure d’arrivée estimée (ETA) et, le cas échéant, la date à laquelle elles ont été franchies.

​
Paramètres

​
id
string
requis
Identifiant de la mission (offer_id).
​
limit
integer
défaut:"100"
Taille de page. Valeur par défaut 100, maximum 500.

​
Réponse

​
data
Waypoint[]
Liste des étapes planifiées.

​
Exemple

curl -s -X GET \
  "https://api.myexpressdriver.com/v1/transports/-O9xAbCdEf/waypoints" \
  -H "X-Api-Key: med_live_a1b2c3d4e5f6..."
Réponse 200
{
  "data": [
    {
      "label": "Enlèvement",
      "lat": 48.8566,
      "lng": 2.3522,
      "eta": "2026-07-01T08:00:00Z",
      "passed_at": "2026-07-01T08:14:32Z"
    },
    {
      "label": "Livraison",
      "lat": 45.7640,
      "lng": 4.8357,
      "eta": "2026-07-01T13:30:00Z",
      "passed_at": null
    }
  ]
}

​
Webhooks plutôt que polling

Interroger les positions en boucle serrée (polling intensif) consomme votre quota de débit pour, la plupart du temps, ne rien apprendre de nouveau. Le modèle recommandé est événementiel : laissez l’API vous notifier des changements, et ne consultez les positions qu’au bon moment.
1

Configurez un endpoint webhook

Depuis votre profil client, déclarez une URL HTTPS qui recevra les événements de votre groupe. Conservez le signing secret montré une seule fois pour vérifier les signatures.
2

Réagissez aux événements de progression

Les événements de cycle de vie (transport.status_changed, transport.assigned, transport.collected, transport.completed, transport.incident) vous indiquent quand l’état de la mission évolue. C’est le bon déclencheur pour rafraîchir le suivi.
3

Récupérez les positions au besoin

À réception d’un événement pertinent, appelez GET /transports/{id}/positions?since=<dernier ts> pour ne charger que les nouveaux points. Pour un affichage carte en direct, gardez un intervalle de rafraîchissement raisonnable plutôt qu’une boucle agressive.
Le débit est limité par IP, par clé et globalement. Un dépassement renvoie 429 Too Many Requests avec un en-tête Retry-After (en secondes). Implémentez un back-off et respectez Retry-After : un polling trop fréquent vous fera atteindre la limite sans bénéfice.
Bonne pratique : un suivi pull-on-demand piloté par webhooks reste à jour tout en restant sous les limites de débit, contrairement à un polling fixe toutes les quelques secondes.

​
Gestion des erreurs

Les erreurs suivent la RFC 9457 (Content-Type: application/problem+json).
Clé API manquante, invalide, révoquée ou expirée. Vérifiez l’en-tête X-Api-Key.
Scope transports:read absent de la clé. Demandez une clé disposant du bon scope.
Mission introuvable, ou hors du groupe rattaché à votre clé. Vérifiez l’id.
Exemple d'erreur 404
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Transport not found."
}
Branchez votre logique sur le champ status (et title), pas sur le texte de detail, qui peut évoluer.

​
Étapes suivantes

Détail d'une mission

Statut public, prix, dates et résumé des documents d’une mission.

Webhooks

Recevez les événements en temps réel et vérifiez la signature HMAC.

Journal d'événements

Réconciliez les événements manqués via GET /events.