Suivi & position

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

string

requis

Identifiant de la mission (offer_id).

string

Date ISO 8601 (date-time, ex. 2026-07-01T08:00:00Z). Ne renvoie que les positions strictement postérieures à cette date. Idéal pour ne récupérer que les nouveaux points depuis votre dernier appel. Encodez le + d’un fuseau en %2B ; une valeur invalide renvoie 422 (errors: [{ "field": "since", "error": "invalid" }]).

integer

défaut:"100"

Nombre maximal de positions renvoyées. Valeur par défaut 100, maximum 500.

Cet endpoint n’est pas paginé par curseur : il n’accepte pas de paramètre cursor et ne renvoie pas de next_cursor. Pour lire la suite, rappelez-le avec since égal au ts de la dernière position reçue.

Réponse

La réponse est un objet contenant un tableau data de positions.

Position[]

Liste des positions relevées.

Afficher Position

number | null

Latitude.

number | null

Longitude.

string | null

Horodatage de la position (ISO 8601).

number | null

Vitesse instantanée, en kilomètres par heure.

number | null

Cap (direction) en degrés, de 0 à 360.

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..."

const BASE = "https://api.myexpressdriver.com/v1";
const API_KEY = process.env.MED_API_KEY; // med_live_...

const id = "-O9xAbCdEf";
const since = "2026-07-01T08:00:00Z";

const url = new URL(`${BASE}/transports/${id}/positions`);
url.searchParams.set("since", since);
url.searchParams.set("limit", "200");

const res = await fetch(url, {
  headers: { "X-Api-Key": API_KEY },
});

if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  throw new Error(`${problem.title} (${problem.status}): ${problem.detail ?? ""}`);
}

const { data } = await res.json();
console.log(`${data.length} position(s)`);
for (const p of data) {
  console.log(`${p.ts} — ${p.lat}, ${p.lng} — ${p.speed_kmh} km/h, cap ${p.heading_deg}°`);
}

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

string

requis

Identifiant de la mission (offer_id).

integer

défaut:"100"

Taille de page. Valeur par défaut 100, maximum 500.

Réponse

Waypoint[]

Liste des étapes planifiées.

Afficher Waypoint

string | null

Libellé de l’étape.

number | null

Latitude de l’étape.

number | null

Longitude de l’étape.

string | null

Heure d’arrivée estimée (ISO 8601).

string | null

Date de passage effectif à l’étape (null si pas encore franchie).

Exemple

curl -s -X GET \
  "https://api.myexpressdriver.com/v1/transports/-O9xAbCdEf/waypoints" \
  -H "X-Api-Key: med_live_a1b2c3d4e5f6..."

const BASE = "https://api.myexpressdriver.com/v1";
const API_KEY = process.env.MED_API_KEY; // med_live_...

const id = "-O9xAbCdEf";

const res = await fetch(`${BASE}/transports/${id}/waypoints`, {
  headers: { "X-Api-Key": API_KEY },
});

if (!res.ok) {
  const problem = await res.json();
  throw new Error(`${problem.title} (${problem.status})`);
}

const { data } = await res.json();
for (const wp of data) {
  const etat = wp.passed_at ? `franchie à ${wp.passed_at}` : `ETA ${wp.eta ?? "—"}`;
  console.log(`${wp.label ?? "(étape)"} — ${etat}`);
}

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.

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.

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.

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).

401 Unauthorized

Clé API manquante, invalide, révoquée ou expirée. Vérifiez l’en-tête X-Api-Key.

403 Forbidden

Scope transports:read absent de la clé. Demandez une clé disposant du bon scope.

404 Not Found

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.

Démarrage

Concepts fondamentaux

Guides

Webhooks

Vue d’ensemble

Positions GPS

Étapes planifiées

Authentification

Positions GPS du convoyeur

Paramètres

Réponse

Exemple

Étapes planifiées (waypoints)

Paramètres

Réponse

Exemple

Webhooks plutôt que polling

Gestion des erreurs

Étapes suivantes

Détail d'une mission

Webhooks

Journal d'événements

​Vue d’ensemble

Positions GPS

Étapes planifiées

​Authentification

​Positions GPS du convoyeur

​Paramètres

​Réponse

​Exemple

​Étapes planifiées (waypoints)

​Paramètres

​Réponse

​Exemple

​Webhooks plutôt que polling

​Gestion des erreurs

​Étapes suivantes

Détail d'une mission

Webhooks

Journal d'événements

Vue d’ensemble

Authentification

Positions GPS du convoyeur

Paramètres

Réponse

Exemple

Étapes planifiées (waypoints)

Paramètres

Réponse

Exemple

Webhooks plutôt que polling

Gestion des erreurs

Étapes suivantes