Dupliquer une mission

Vos flux récurrents — navettes parc ↔ concession, restitutions de fin de contrat, rotations entre agences — se ressemblent d’une semaine à l’autre. Plutôt que de reconstruire un POST /transports complet, dupliquez une mission existante : le serveur recopie le trajet, le véhicule, les contacts, les consignes et les documents que vous choisissez, puis crée une nouvelle mission aux dates que vous indiquez, tarifée sur votre grille du moment.

Aperçu sans engagement

POST /transports/{id}/duplicate/preview renvoie le prix et les documents recopiés, sans rien créer.

Création idempotente

POST /transports/{id}/duplicate crée la mission ; rejouable sans doublon avec Idempotency-Key.

Les deux routes sont scopées au groupe de votre clé : une mission qui n’est pas la vôtre renvoie 404. La création exige le scope transports:write.

Variables utilisées dans les exemples :

export BASE="https://api.myexpressdriver.com/v1"
export KEY="med_live_…"
export SOURCE="-O9xSourceKey"   # id de la mission à dupliquer (champ `id` de GET /transports)

Ce qui est recopié, ce qui ne l’est pas

Recopié depuis la source	Réinitialisé sur le duplicata
Trajet, adresses, contacts, consignes, véhicule, type de prestation	Dates (fournies par vous), statut, convoyeur
Options que vous conservez (`options`)	Facturation, paiements, PV et inspections
Documents que vous désignez (`documents.copy`), recopiés côté serveur	Suivi GPS, historique, incidents

Le prix n’est jamais recopié : il est recalculé sur la grille de votre groupe au moment de la duplication. Si l’enlèvement demandé est proche, la majoration express s’applique comme pour une création classique (price.express: true).

Une mission ne se duplique qu’une seule fois. Une seconde tentative sur la même source renvoie 409 Conflict avec code: "already_duplicated" et l’extension duplicated_to (identifiants de la mission déjà créée). Pour une troisième occurrence, dupliquez la mission créée, pas la source d’origine.

1. Obtenir un aperçu

L’aperçu applique exactement les mêmes contrôles que la création (dates, options, documents, règle « une seule fois ») mais n’a aucun effet de bord : ni mission, ni événement, ni idempotence.

curl -X POST "$BASE/transports/$SOURCE/duplicate/preview" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": {
      "enlevement-aller": { "date": "2026-09-22", "start_time": "08:00", "end_time": "12:00" },
      "livraison-aller":  { "date": "2026-09-23", "start_time": "14:00", "end_time": "18:00" }
    }
  }'

Réponse 200

{
  "id": null,
  "transport_id": null,
  "status": "scheduled",
  "price": { "amount_ht": 412, "currency": "EUR", "express": false },
  "return_trip": null,
  "duplicated_from": { "id": "-O9xSourceKey", "transport_id": "M-54300" },
  "documents": { "to_copy": 2 },
  "warnings": []
}

Les dates, jambe par jambe

dates est obligatoire et doit couvrir chaque jambe de la source : enlevement-aller, livraison-aller, et, si la source comporte un retour, enlevement-retour et livraison-retour. Chaque jambe porte un jour (YYYY-MM-DD, heure de Paris) et un créneau start_time / end_time (HH:mm). Pour une jambe sans créneau connu, envoyez need_appointment: true avec la date seule : la mission naît alors en attente de rendez-vous. Le serveur refuse (422) une date passée, des jambes désordonnées, un créneau inversé, et un enlèvement sous le délai minimal de commande — dans ce dernier cas la réponse porte code: "too_early" et min_date, première date acceptée.

Options et documents

options.aller / options.retour : soit un tableau des libellés des options de la source à conserver (tels qu’ils apparaissent sur la source ; absent = toutes conservées ; un libellé inconnu renvoie 422 unknown_option), soit un objet { "keep": [...], "add": [...] } pour ajouter des options au prix de votre grille dès la duplication. Chaque entrée de add porte option_key (clé du catalogue, cf. Options) et, selon l’option, ses obligations dans params : loueur + lien ou code PIN pour un PV dématérialisé, liste d’accessoires à vérifier. Une obligation manquante renvoie 422 requirements_not_met avec le champ précis (errors[].field = "options.aller.add.0.renter"). Un seul type de PV par jambe : ajouter un PV dématérialisé retire le PV papier conservé. Un créneau need_appointment ajoute d’office l’option « Prise de rendez-vous ».
documents.copy : identifiants Document.id (cf. GET /transports/{id}/documents) des documents de la source à recopier. Absent = tous les documents copiables (ceux que vous avez déposés vous-même ; les PV signés, inspections et pièces générées par MED ne sont jamais recopiés). 20 documents au plus par duplication.
documents.pending : clés des documents que vous déposerez juste après la création (POST /transports/{id}/documents), par exemple PV_PAPIER quand vous ajoutez l’option « PV papier » sans PV recopié — sans cette annonce ni PV copié, l’ajout est refusé (422 requirements_not_met, documents: ["PV_PAPIER"]).

"options": {
  "aller": {
    "keep": ["Lavage Extérieur - 19"],
    "add": [
      { "option_key": "Booster" },
      { "option_key": "PV_DEMATERIALISE", "params": { "renter": "ayvens", "link": "welcome.auto/session/42" } }
    ]
  },
  "retour": []
}

La réponse (aperçu comme création) rend options.aller / options.retour : les options finales de chaque jambe, clés {nom} - {prix} au prix appliqué.

2. Créer le duplicata

Même corps que l’aperçu. Ajoutez un en-tête Idempotency-Key : un rejeu (timeout, double envoi) renvoie la même réponse sans créer de seconde mission.

curl -X POST "$BASE/transports/$SOURCE/duplicate" \
  -H "X-Api-Key: $KEY" \
  -H "Idempotency-Key: 8c6f2a1e-dup-2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": {
      "enlevement-aller": { "date": "2026-09-22", "start_time": "08:00", "end_time": "12:00" },
      "livraison-aller":  { "date": "2026-09-23", "start_time": "14:00", "end_time": "18:00" }
    },
    "options": { "aller": ["PV papier - 10"], "retour": [] },
    "documents": { "copy": ["3f1c9a2e-7b44-4c1d-9e0a-5d2b8c6f1a23"] }
  }'

Réponse 201

{
  "id": "-OabcDEF123",
  "transport_id": "M-58121",
  "status": "scheduled",
  "price": { "amount_ht": 412, "currency": "EUR", "express": false },
  "return_trip": null,
  "duplicated_from": { "id": "-O9xSourceKey", "transport_id": "M-54300" },
  "documents": { "copied": 1, "failed": [] },
  "warnings": []
}

La nouvelle mission devient lisible via GET /transports/-OabcDEF123 dès que la synchronisation est faite, en général en moins de quelques secondes (son champ duplicated_from pointe vers la source) ; la source expose alors is_duplicated: true. Un 404 juste après le 201 signifie simplement que la synchronisation n’est pas encore passée : réessayez brièvement plutôt que de conclure à un échec.

documents.failed liste les fichiers qui n’ont pas pu être recopiés : la mission est créée malgré tout. Reposez-les avec POST /transports/{id}/documents.

3. Webhooks

Deux événements sont émis :

Événement	Sur	`data`
`transport.created`	la mission créée	`{ id, transport_id, price: { amount_ht }, duplicated_from }`
`transport.duplicated`	la mission source	`{ id, duplicated_to: { id, transport_id } }`

Le duplicata suit ensuite le cycle de vie habituel (transport.assigned, transport.collected, …). Voir le catalogue des événements.

4. Erreurs

Code	`code`	Cause
`403`	—	Scope `transports:write` absent, ou champ réservé aux administrateurs MED dans le corps
`404`	—	Source inexistante, archivée ou hors de votre groupe
`409`	`already_duplicated`	Source déjà dupliquée — `duplicated_to` donne la mission existante
`409`	—	`Idempotency-Key` rejouée avec un corps différent
`422`	`missing_dates`, `missing_leg`, `unknown_leg`, `invalid_date`, `invalid_time`, `date_incoherent`	Dates absentes, mal formées ou incohérentes
`422`	`too_early`	Enlèvement sous le délai minimal — `min_date` indique la première date possible
`422`	`unknown_option`, `document_not_selectable`	Option ou document qui n’appartient pas à la source
`422`	`too_many_documents`	Plus de 20 documents demandés dans `documents.copy`
`502`	`pricing_unavailable`	Moteur de tarification momentanément indisponible : rien n’est créé, réessayez
`502`	—	Le traitement n’a pas pu être confirmé (voir ci-dessous)

Timeout ou 502 après un appel de création : la copie des documents peut dépasser le délai du relai alors que la mission a bien été créée. Relisez la source (GET /transports/{id}) : si is_duplicated vaut true, retrouvez le duplicata via GET /events?type=transport.duplicated (data.duplicated_to). Rejouer l’appel avec la même Idempotency-Key est sans risque : la source ne peut pas être dupliquée deux fois.

Démarrage

Concepts fondamentaux

Guides

Webhooks

Aperçu sans engagement

Création idempotente

Ce qui est recopié, ce qui ne l’est pas

1. Obtenir un aperçu

Les dates, jambe par jambe

Options et documents

2. Créer le duplicata

3. Webhooks

4. Erreurs

Aperçu sans engagement

Création idempotente

​Ce qui est recopié, ce qui ne l’est pas

​1. Obtenir un aperçu

​Les dates, jambe par jambe

​Options et documents

​2. Créer le duplicata

​3. Webhooks

​4. Erreurs

Ce qui est recopié, ce qui ne l’est pas

1. Obtenir un aperçu

Les dates, jambe par jambe

Options et documents

2. Créer le duplicata

3. Webhooks

4. Erreurs