Créer une mission

La création d’une mission est l’opération centrale de l’API Transport. Un seul appel POST /transports planifie un transport de véhicule, le rend visible côté convoyeurs, et déclenche l’événement webhook transport.created.

POST https://api.myexpressdriver.com/v1/transports

La mission créée porte le statut public scheduled : elle est planifiée et en attente d’attribution d’un convoyeur. Vous suivrez ensuite sa progression via les statuts assigned, in_transit, awaiting_documents, under_review puis completed.

Prérequis

Clé API

Une clé portant le scope transports:write, envoyée dans l’en-tête X-Api-Key: med_live_....

Adresses d'enlèvement et de livraison

Les champs pickup et delivery sont requis, chacun avec adresse, date, créneau (ou need_appointment: true) et contact complet (nom, téléphone, e-mail).

Facturation

Le bloc billing est requis, avec raison sociale, e-mail et adresse — même si vous désignez l’entité par entity_id.

Clé d'idempotence

Indispensable : un Idempotency-Key unique par mission, pour pouvoir réessayer sans jamais créer de doublon.

Les champs du corps de la requête

Le corps est un objet JSON. Sont requis : le véhicule (car, ou son alias vehicle) avec son immatriculation registration ; pickup et delivery, chacun avec address, date, contact (name, phone, mail) et le créneau start_time / end_time (sauf need_appointment: true) ; billing avec company_name, address et email. Tous les autres champs sont optionnels.

Ces exigences valent pour la création. L’estimation POST /pricing se contente des adresses (et du véhicule pour le gabarit).

Champs racine

string

Type de transport. Valeurs usuelles : livraison, restitution, conciergerie. En l’absence de valeur, le transport est traité comme une livraison standard.

boolean

défaut:"false"

Indique un transport sur plateau (camion porte-véhicule) plutôt qu’en roulant. Impacte la tarification.

boolean

défaut:"false"

Indique que le carburant est remboursé au convoyeur sur cette mission.

boolean

défaut:"false"

Véhicule circulant sous plaques W garage (immatriculation provisoire professionnelle).

string[]

Liste des clés d’options à appliquer à la mission (ex. lavage, plein de carburant). Les clés disponibles dépendent de la grille de votre groupe.

string

Note libre attachée à la mission (consignes particulières, référence interne).

`car` — le véhicule

object

requis

Caractéristiques du véhicule transporté.

Afficher propriétés de car

string

requis

Immatriculation du véhicule (ex. AB-123-CD). Absente : 422 avec errors[].field = car.registration.

boolean

défaut:"false"

Le véhicule est électrique : une majoration s’applique selon la distance. Quand l’immatriculation est reconnue, c’est l’énergie de la carte grise qui fait foi (électrique majoré ; hybride et thermique non majorés) ; ce champ sert de repli si la plaque est inconnue. Optionnel : absent, il vaut false (y compris pour le véhicule du retour).

Dans le contrat OpenAPI, l’objet véhicule est nommé vehicle et accepte aussi type, vin, brand et model. car est l’alias documenté côté guide ; les deux pointent vers le même objet véhicule. Préférez vehicle si vous générez votre client directement depuis l’OpenAPI.

`pickup` — point d’enlèvement

object

requis

Lieu, créneau et contact pour l’enlèvement du véhicule.

Afficher propriétés de pickup

string

requis

Adresse postale complète d’enlèvement.

string

requis

Jour d’enlèvement, au format ISO 8601 UTC avec millisecondes : YYYY-MM-DDTHH:MM:SS.sssZ (ex. 2026-11-03T00:00:00.000Z). Une date courte (2026-11-03) est refusée. Seul le jour est retenu : envoyez T00:00:00.000Z, l’heure vient du créneau. Un jour antérieur à aujourd’hui (jour civil de Paris) est refusé (error: "past") ; le jour même reste possible, avec majoration express.

string

Heure de début du créneau, heure de Paris (HH:MM). Requise sauf need_appointment: true.

string

Heure de fin du créneau, heure de Paris (HH:MM). Ne peut pas précéder start_time (sinon error: "before_start_time") ; une fin égale au début (heure précise) est acceptée, et 00:00 vaut fin de journée (créneau 22:00–00:00). Requise sauf need_appointment: true.

boolean

défaut:"false"

true = rendez-vous à prendre : date seule, sans créneau. Par défaut (false), le créneau start_time / end_time est obligatoire.

object

requis

Personne à contacter sur place.

Afficher propriétés de contact

string

requis

Nom du contact.

string

requis

Téléphone du contact : 10 à 15 chiffres, + initial facultatif, sans espace (ex. +33600000000).

string

requis

E-mail du contact (email accepté comme alias ; les alias avec +, comme jean+atelier@garage-demo.fr, sont acceptés).

`delivery` — point de livraison

object

requis

Lieu, créneau et contact pour la livraison du véhicule. Mêmes propriétés et mêmes exigences que pickup.

Afficher propriétés de delivery

string

requis

Adresse postale complète de livraison.

string

requis

Jour de livraison, même format que pickup.date (2026-11-03T00:00:00.000Z). Il ne peut pas précéder le jour d’enlèvement (error: "before_pickup") ; le même jour est permis.

string

Heure de début du créneau, heure de Paris (HH:MM). Requise sauf need_appointment: true.

string

Heure de fin du créneau, heure de Paris (HH:MM), pas avant start_time (00:00 = fin de journée). Requise sauf need_appointment: true.

boolean

défaut:"false"

true = rendez-vous à prendre : date seule, sans créneau.

object

requis

Personne à contacter sur place.

Afficher propriétés de contact

string

requis

Nom du contact.

string

requis

Téléphone du contact : 10 à 15 chiffres, + initial facultatif, sans espace.

string

requis

E-mail du contact (email accepté comme alias).

Chaque champ manquant, mal formé ou incohérent est signalé dans errors[] d’une réponse 422, avec son chemin : pickup.date, pickup.start_time, pickup.contact, pickup.contact.phone, delivery.contact.mail… Toutes les erreurs sont renvoyées en une fois. Les incohérences de calendrier portent un code court dans errors[].error : past (enlèvement avant aujourd’hui), before_pickup (livraison avant l’enlèvement), before_start_time (fin de créneau antérieure au début).

`billing` — facturation

object

requis

Informations de facturation de la mission. company_name, address et email sont toujours requis, même avec entity_id : s’il en manque un, la création est refusée en 422 et errors[] nomme chaque champ manquant (billing.company_name, billing.address, billing.email).

Afficher propriétés de billing

string

requis

Raison sociale de l’entité facturée.

string

requis

Adresse de facturation.

string

requis

E-mail de facturation (réception des documents comptables). Alias + acceptés.

string

Numéro SIRET (14 chiffres). Optionnel mais recommandé.

`return_trip` — aller-retour

boolean | string | object

Décrit la jambe retour. Omettez (ou false) pour un aller simple. Trois formes :

true → A→B→A : retour vers le lieu d’enlèvement de l’aller.
"adresse" (chaîne) → A→B→C : retour vers cette adresse de destination.
objet → forme complète (ci-dessous), pour préciser véhicule / contacts / horaires du retour.

En forme courte (true ou chaîne), le retour reprend le véhicule de l’aller, la date de livraison de l’aller et le contact de livraison de l’aller (à défaut, celui d’enlèvement), sans créneau : il est créé en attente de rendez-vous.

Afficher propriétés de return_trip (forme objet)

object

Véhicule de la jambe retour (registration, electric). Par défaut = celui de l’aller. À préciser si le véhicule retourné diffère (cas A→B→C fréquent) : registration est alors requise (errors[].field = returnTrip.car.registration), electric absent vaut false.

object

requis

Destination du retour. Seul point d’adresse à fournir pour le retour. address et date (même format que pickup.date) sont requis — la date n’est pas héritée en forme objet et ne peut pas précéder la livraison de l’aller (returnTrip.delivery.date, before_pickup) ; start_time / end_time aussi (fin pas avant le début), sauf need_appointment: true. contact est facultatif : absent, c’est le contact de livraison de l’aller qui est repris ; fourni, il doit être complet (name, phone, mail).

Le retour n’a pas d’adresse de départ à renseigner. Il part automatiquement du lieu de livraison de l’aller (le convoyeur repart de là où il vient de livrer). Vous ne précisez donc que la destination du retour (forme courte "adresse", ou return_trip.delivery) — jamais un point de départ.

Exemple — aller simple

curl -s -X POST "https://api.myexpressdriver.com/v1/transports" \
  -H "X-Api-Key: med_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "livraison",
    "plateau": false,
    "fuel_refunded": false,
    "wgarage": false,
    "car": {
      "registration": "AB-123-CD",
      "electric": false
    },
    "pickup": {
      "need_appointment": false,
      "date": "2026-11-03T00:00:00.000Z",
      "start_time": "08:00",
      "end_time": "12:00",
      "address": "10 Rue de Rivoli, 75004 Paris",
      "contact": {
        "name": "Jean Dupont",
        "phone": "+33600000000",
        "mail": "jean.dupont@garage-demo.fr"
      }
    },
    "delivery": {
      "need_appointment": true,
      "date": "2026-11-03T00:00:00.000Z",
      "start_time": "14:00",
      "end_time": "18:00",
      "address": "1 Place Bellecour, 69002 Lyon",
      "contact": {
        "name": "Marie Martin",
        "phone": "+33611111111",
        "mail": "marie.martin@concession-lyon.fr"
      }
    },
    "billing": {
      "company_name": "Garage Demo SARL",
      "address": "5 Avenue des Champs, 75008 Paris",
      "email": "compta@garage-demo.fr",
      "siret": "12345678901234"
    },
    "options": []
  }'

// Node.js >= 18 (fetch global) — npm i uuid
import { randomUUID } from "node:crypto";

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

const res = await fetch(`${BASE}/transports`, {
  method: "POST",
  headers: {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    type: "livraison",
    plateau: false,
    fuel_refunded: false,
    wgarage: false,
    car: {
      registration: "AB-123-CD",
      electric: false,
    },
    pickup: {
      need_appointment: false,
      date: "2026-11-03T00:00:00.000Z",
      start_time: "08:00",
      end_time: "12:00",
      address: "10 Rue de Rivoli, 75004 Paris",
      contact: {
        name: "Jean Dupont",
        phone: "+33600000000",
        mail: "jean.dupont@garage-demo.fr",
      },
    },
    delivery: {
      need_appointment: true,
      date: "2026-11-03T00:00:00.000Z",
      start_time: "14:00",
      end_time: "18:00",
      address: "1 Place Bellecour, 69002 Lyon",
      contact: {
        name: "Marie Martin",
        phone: "+33611111111",
        mail: "marie.martin@concession-lyon.fr",
      },
    },
    billing: {
      company_name: "Garage Demo SARL",
      address: "5 Avenue des Champs, 75008 Paris",
      email: "compta@garage-demo.fr",
      siret: "12345678901234",
    },
    options: [],
  }),
});

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

const transport = await res.json();
// transport_id vaut null ici (attribué juste après) ; price est une chaîne ("407.44").
console.log(transport.id, transport.status, Number(transport.price));

Exemple — aller-retour

Pour un aller-retour, ajoutez le bloc return_trip avec le véhicule et le point de livraison du retour.

curl -s -X POST "https://api.myexpressdriver.com/v1/transports" \
  -H "X-Api-Key: med_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "restitution",
    "plateau": false,
    "car": {
      "registration": "AB-123-CD",
      "electric": true
    },
    "pickup": {
      "need_appointment": false,
      "date": "2026-11-03T00:00:00.000Z",
      "start_time": "08:00",
      "end_time": "12:00",
      "address": "10 Rue de Rivoli, 75004 Paris",
      "contact": {
        "name": "Jean Dupont",
        "phone": "+33600000000",
        "mail": "jean.dupont@garage-demo.fr"
      }
    },
    "delivery": {
      "need_appointment": true,
      "date": "2026-11-03T00:00:00.000Z",
      "start_time": "14:00",
      "end_time": "18:00",
      "address": "1 Place Bellecour, 69002 Lyon",
      "contact": {
        "name": "Marie Martin",
        "phone": "+33611111111",
        "mail": "marie.martin@concession-lyon.fr"
      }
    },
    "billing": {
      "company_name": "Garage Demo SARL",
      "address": "5 Avenue des Champs, 75008 Paris",
      "email": "compta@garage-demo.fr",
      "siret": "12345678901234"
    },
    "options": [],
    "return_trip": {
      "car": {
        "registration": "AB-123-CD",
        "electric": true
      },
      "delivery": {
        "need_appointment": false,
        "date": "2026-11-05T00:00:00.000Z",
        "start_time": "09:00",
        "end_time": "13:00",
        "address": "10 Rue de Rivoli, 75004 Paris",
        "contact": {
          "name": "Jean Dupont",
          "phone": "+33600000000",
          "mail": "jean.dupont@garage-demo.fr"
        }
      }
    }
  }'

import { randomUUID } from "node:crypto";

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

const res = await fetch(`${BASE}/transports`, {
  method: "POST",
  headers: {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    type: "restitution",
    plateau: false,
    car: { registration: "AB-123-CD", electric: true },
    pickup: {
      need_appointment: false,
      date: "2026-11-03T00:00:00.000Z",
      start_time: "08:00",
      end_time: "12:00",
      address: "10 Rue de Rivoli, 75004 Paris",
      contact: {
        name: "Jean Dupont",
        phone: "+33600000000",
        mail: "jean.dupont@garage-demo.fr",
      },
    },
    delivery: {
      need_appointment: true,
      date: "2026-11-03T00:00:00.000Z",
      start_time: "14:00",
      end_time: "18:00",
      address: "1 Place Bellecour, 69002 Lyon",
      contact: {
        name: "Marie Martin",
        phone: "+33611111111",
        mail: "marie.martin@concession-lyon.fr",
      },
    },
    billing: {
      company_name: "Garage Demo SARL",
      address: "5 Avenue des Champs, 75008 Paris",
      email: "compta@garage-demo.fr",
      siret: "12345678901234",
    },
    options: [],
    return_trip: {
      car: { registration: "AB-123-CD", electric: true },
      delivery: {
        need_appointment: false,
        date: "2026-11-05T00:00:00.000Z",
        start_time: "09:00",
        end_time: "13:00",
        address: "10 Rue de Rivoli, 75004 Paris",
        contact: {
          name: "Jean Dupont",
          phone: "+33600000000",
          mail: "jean.dupont@garage-demo.fr",
        },
      },
    },
  }),
});

const transport = await res.json();
console.log(transport);

Réponse `201 Created`

En cas de succès, l’API renvoie 201 avec l’identifiant de la mission, son statut, le prix calculé et les adresses retenues.

{
  "id": "-O9xAbCdEf",
  "transport_id": null,
  "status": "scheduled",
  "price": "407.44",
  "billing":  { "entity_id": "7b1e2c34-5d6f-4a1b-9c8d-0e1f2a3b4c5d", "return_entity_id": null },
  "pickup":   { "address": "10 Rue de Rivoli, 75004 Paris, France", "lat": 48.8557, "lng": 2.3589, "place_id": "ChIJ7Qq9bF9u5kcRYJSMaMOCCwQ" },
  "delivery": { "address": "Place Bellecour, 69002 Lyon, France",   "lat": 45.7578, "lng": 4.8320, "place_id": "ChIJ65aN5w7q9EcR_HhwT2N0gJg" },
  "return_trip": null
}

string

Identifiant technique de la mission (offer_id). À utiliser dans tous les appels ultérieurs : GET /transports/{id}, suivi GPS, documents, etc.

string | null

Référence métier lisible de la mission (ex. M-54321). Vaut null dans cette réponse : elle est attribuée juste après la création. Lisez-la via GET /transports/{id}.

string

Statut public de la mission. À la création, vaut toujours scheduled.

string | null

Prix HT facturé pour l’aller, sous forme de chaîne décimale (ex. "407.44", ou "180" sans décimales), majorations comprises. Convertissez-la en nombre côté client. Le prix détaillé (price.amount_ht, price.surcharge_ht, price.currency) et celui du retour (return_trip.price) se lisent via GET /transports/{id}.

object | null

Entité(s) de facturation MED posée(s) sur la mission : entity_id (aller) et return_entity_id (retour, null sans trajet retour).

object

Adresse d’enlèvement résolue (géocodée) effectivement enregistrée : address normalisée, lat, lng, place_id. Contrôlez-la pour vérifier que le point retenu est bien celui visé.

object

Adresse de livraison résolue, même structure que pickup.

object | null

Pour un aller-retour : adresses résolues pickup (= livraison de l’aller) et delivery (destination du retour). null sur un aller simple.

Conservez l’id renvoyé : c’est lui qui identifie la mission pour le suivi, la modification des dates, les options et l’annulation.

Idempotence

La création de mission est l’opération la plus sensible aux doublons : un appel qui échoue côté réseau peut avoir réussi côté serveur. Pour vous protéger, envoyez systématiquement un en-tête Idempotency-Key (par exemple un UUID v4 que vous générez).

Idempotency-Key: 1f3c2b7a-9d4e-4a1b-8c2f-0e6d5a4b3c2d

Première requête

Exécutée normalement. La réponse est mise en cache et associée à la clé.

Même clé + même corps

La réponse en cache est rejouée à l’identique, avec l’en-tête Idempotent-Replayed: true. Une seule mission est créée.

Même clé + autre requête

L’API renvoie 409 Conflict avec code: idempotency_key_reused : la clé a déjà servi pour une requête différente (autre corps, autre route ou autre mission).

Échec 5xx ou 502 relay_timeout

Les réponses 5xx ne sont pas mises en cache : vous pouvez réessayer avec la même clé et le même corps. Un 502 avec code: relay_timeout signifie que la mission a pu être créée malgré l’erreur : le nouvel essai vous la renvoie (201 identique) au lieu d’en créer une seconde.

Issue inconnue (outcome_unknown: true)

Un 502, ou un 409 request_in_progress sans Retry-After, peut porter outcome_unknown: true : la création avait commencé quand l’erreur est survenue, et son issue est inconnue. Cette situation ne se résout pas par un nouvel essai. Ne renvoyez pas la commande : vérifiez d’abord par GET /transports (avec since, ou en cherchant votre référence de commande) si la mission existe, ou contactez le support.

Création encore en cours (409 request_in_progress)

Si vous réessayez pendant que la première création est encore en traitement, l’API répond 409 avec code: request_in_progress et un en-tête Retry-After (5 s). Rien n’est recréé : patientez puis réessayez avec la même clé. Sans Retry-After et avec outcome_unknown: true, voir ci-dessous.

Sans Idempotency-Key, un nouvel essai après un timeout ou un 502 peut créer un doublon (deux convoyages, deux facturations). Si vous avez déjà envoyé une création sans clé, vérifiez vos missions (GET /transports) avant de la renvoyer.

Utilisez une clé d’idempotence distincte par mission à créer. Les clés sont conservées 24 h.

Erreurs

Les erreurs suivent la RFC 9457 (Content-Type: application/problem+json).

Code	Cause	À faire
`401`	Clé API manquante, invalide ou révoquée	Vérifier l’en-tête `X-Api-Key`.
`403`	Scope `transports:write` absent	Demander une clé avec le bon scope.
`409`	`code: idempotency_key_reused`	Utiliser une nouvelle clé ou renvoyer exactement la même requête.
`409`	`code: request_in_progress`	Attendre `Retry-After`, puis même clé, même corps.
`409` / `502`	`outcome_unknown: true` (sans `Retry-After`)	Ne pas réessayer : vérifier via `GET /transports` avant toute nouvelle commande.
`422`	Validation : champ requis manquant	Lire `errors[]` (ex. `billing.email`, `car.registration`).
`422`	`code: billing_entity_required` / `billing_entity_not_allowed`	Préciser ou corriger l’entité de facturation.
`429`	Limite de débit atteinte	Back-off et respecter l’en-tête `Retry-After`.
`500`	Erreur interne	Transmettre la `reference` au support.
`502`	`code: relay_timeout` (la mission a pu être créée)	Réessayer avec la même `Idempotency-Key`.
`502`	`code: relay_unavailable`	Réessayer plus tard avec la même `Idempotency-Key` (une connexion coupée a pu laisser la création aboutir : la même clé évite le doublon).
`502`	`code: billing_lookup_unavailable` (entités de facturation momentanément inaccessibles)	Rejouer la même requête, même `Idempotency-Key` (rien n’a été créé).

Exemple de 422 lorsqu’un champ requis manque — detail résume, errors[] détaille champ par champ :

{
  "type": "about:blank",
  "title": "Create failed",
  "status": 422,
  "detail": "The request was rejected by validation. See errors for details.",
  "errors": [
    { "field": "billing.email", "error": "billing.email is required and must be a valid email" }
  ]
}

Branchez votre logique sur status et code, pas sur le texte de detail ni sur title, qui peuvent évoluer.

Étapes suivantes

Suivre une mission

Récupérer le détail, les positions GPS et l’ETA du convoyeur.

Modifier les dates

Ajuster les créneaux d’enlèvement et de livraison, par jambe.

Recevoir les événements

S’abonner aux webhooks signés (transport.created, transport.status_changed…).

Démarrage

Concepts fondamentaux

Guides

Webhooks

Prérequis

Clé API

Adresses d'enlèvement et de livraison

Facturation

Clé d'idempotence

Les champs du corps de la requête

Champs racine

`car` — le véhicule

`pickup` — point d’enlèvement

`delivery` — point de livraison

`billing` — facturation

`return_trip` — aller-retour

Exemple — aller simple

Exemple — aller-retour

Réponse `201 Created`

Idempotence

Erreurs

Étapes suivantes

Suivre une mission

Modifier les dates

Recevoir les événements

​Prérequis

Clé API

Adresses d'enlèvement et de livraison

Facturation

Clé d'idempotence

​Les champs du corps de la requête

​Champs racine

​car — le véhicule

​pickup — point d’enlèvement

​delivery — point de livraison

​billing — facturation

​return_trip — aller-retour

​Exemple — aller simple

​Exemple — aller-retour

​Réponse 201 Created

​Idempotence

​Erreurs

​Étapes suivantes

Suivre une mission

Modifier les dates

Recevoir les événements

Prérequis

Les champs du corps de la requête

Champs racine

`car` — le véhicule

`pickup` — point d’enlèvement

`delivery` — point de livraison

`billing` — facturation

`return_trip` — aller-retour

Exemple — aller simple

Exemple — aller-retour

Réponse `201 Created`

Idempotence

Erreurs

Étapes suivantes