https://hopla.deliveryDe zéro à une page de suivi en trois appels
Les exemples utilisent deux variables shell. Définissez-les une fois :
API=https://hopla.delivery
KEY=hopla_dev_keyCréer une commande avec ses articles et ses colis
Un seul appel enregistre la commande, ses articles et ses colis. Si vous n’indiquez pas le transporteur, il est détecté à partir du numéro de suivi.
POST /v1/orders curl -X POST "$API/v1/orders" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: demo-2001" \ -d '{ "orderNumber": "HP-2001", "store": { "name": "Atelier Nord" }, "customer": { "name": "Camille Durand", "email": "camille.durand@example.com" }, "destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" }, "items": [ { "ref": "a", "title": "Linen overshirt", "variant": "Sand / M", "quantity": 1, "unitPriceCents": 8900, "imageUrl": "https://cdn.example/overshirt.jpg" } ], "shipments": [ { "trackingNumber": "6A20001118001", "carrier": "la-poste", "origin": { "city": "Lille", "country": "FR" }, "items": [ "a" ], "simulate": { "scenario": "domestic_home", "autoStart": true } } ] }'Ajouter une étape
Envoyez un code, un lieu et, si vous l’avez, le message d’origine du transporteur. Le statut du colis suit sa dernière étape.
POST /v1/shipments/:id/events curl -X POST "$API/v1/shipments/6A20001118001/events" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{ "substatus": "out_for_delivery", "location": { "place": "LYS" }, "message": "Votre colis est en cours de livraison.", "messageLang": "fr", "details": { "window": "14:00-18:00" } }'Ouvrir la page
La page de la commande et une page par colis sont en ligne aussitôt, en quatre langues. Il ne reste qu’à transmettre le lien à votre client.
Voir une page de commande de démonstration/fr/order/HP-1042
Authentification
Les points d’accès en écriture demandent une clé API dans l’en-tête Authorization. Les recherches sont publiques.
Authorization: Bearer hopla_dev_keyX-Api-Key est accepté également. Une clé absente ou erronée renvoie 401 unauthorized. La lecture des commandes et des colis renvoie des données personnelles : elle demande donc aussi la clé.
| Points d’accès publics | Description |
|---|---|
| GET /v1/track/:ref | Recherche un colis par numéro de suivi, ou une commande entière par numéro ou identifiant de commande. C’est la réponse à partir de laquelle chaque page de suivi est construite. |
| POST /v1/track/batch | Recherche jusqu’à 40 références en un appel. Chacune reçoit son propre résultat, trouvée ou non. |
| POST /v1/detect | Extrait les références d’un texte libre et classe les transporteurs possibles pour chacune. |
| GET /v1/carriers | L’annuaire des transporteurs, avec les motifs qui servent à reconnaître les numéros. |
| GET /v1/carriers/:slug | Un transporteur, par son identifiant. |
| GET /v1/statuses | Le modèle de statuts avec libellés et descriptions dans une langue, ou dans les quatre. |
| GET /v1/places | Les lieux auxquels une étape peut renvoyer : noms localisés, coordonnées et fuseaux horaires. |
| GET /health | État du service et nombre d’enregistrements. |
| GET /v1/simulator/scenarios | Les parcours que le simulateur sait jouer. |
Le modèle de statuts
Neuf statuts pour les filtres et les couleurs, 52 sous-statuts pour la formulation.
| Statut | Code | Signification |
|---|---|---|
| En préparation | pending | L’expéditeur a enregistré ce colis, mais le transporteur ne l’a pas encore pris en charge. |
| En transit | in_transit | Le colis est en cours d’acheminement vers sa destination. |
| En cours de livraison | out_for_delivery | Le colis est entre les mains du livreur et devrait être livré aujourd’hui. |
| À retirer | available_for_pickup | Le colis vous attend en point de retrait ou en consigne. Munissez-vous d’une pièce d’identité ou de votre code de retrait. |
| Livré | deliveredfinal | Le colis a été livré. |
| Tentative échouée | failed_attempt | Le livreur s’est présenté mais n’a pas pu remettre le colis. Une nouvelle tentative ou un retrait en point de retrait est généralement proposé. |
| Incident de livraison | exception | Un incident retarde ce colis. Consultez la dernière étape pour connaître la suite. |
| Retour à l’expéditeur | returned | Le colis repart, ou est déjà reparti, chez l’expéditeur. |
| Aucune mise à jour récente | expired | Le transporteur n’a rien signalé depuis longtemps. Contactez l’expéditeur si le colis n’est pas arrivé. |
À la boutique · 3 codes
order_placedCommande passée → pendingorder_processingEn cours de préparation → pendingorder_readyCommande prête → pending
Prise en charge · 5 codes
info_receivedÉtiquette créée → pendingawaiting_carrier_pickupEn attente d’enlèvement → pendingpicked_upPris en charge par le transporteur → in_transitdropped_offDéposé en point de collecte → in_transitaccepted_originArrivé au centre de départ → in_transit
En chemin · 4 codes
arrived_hubArrivé au centre de tri → in_transitsortedTri effectué → in_transitdeparted_hubParti du centre de tri → in_transitin_transitEn cours d’acheminement → in_transit
Export · 4 codes
export_hub_arrivedArrivé au centre d’export → in_transitexport_customsDédouanement à l’export → in_transitdeparted_origin_countryA quitté le pays d’expédition → in_transittransit_countryEn transit dans un pays tiers → in_transit
Douane et import · 7 codes
arrived_destination_countryArrivé dans le pays de destination → in_transitcustoms_processingEn cours de dédouanement → in_transitcustoms_clearedDédouanement terminé → in_transitcustoms_heldRetenu en douane → exceptioncustoms_duties_dueDroits et taxes à régler → exceptioncustoms_info_requiredInformations demandées par la douane → exceptionhanded_to_local_carrierRemis au transporteur local → in_transit
Dernier kilomètre · 8 codes
arrived_delivery_depotArrivé sur le site de livraison → in_transitout_for_deliveryEn cours de livraison → out_for_deliverydelivery_rescheduledLivraison reportée → in_transitdeliveredLivré → delivereddelivered_mailboxLivré en boîte aux lettres → delivereddelivered_signedLivré contre signature → delivereddelivered_third_partyRemis à un voisin ou à l’accueil → delivereddelivered_safe_placeDéposé à l’endroit convenu → delivered
Points de retrait · 4 codes
arrived_pickup_pointDisponible en point de retrait → available_for_pickuppickup_reminderRappel de retrait → available_for_pickuppicked_up_by_recipientColis retiré → deliveredpickup_expiredColis non réclamé → returned
Tentatives de livraison · 6 codes
attempt_absentDestinataire absent → failed_attemptattempt_closedÉtablissement fermé → failed_attemptaddress_issueProblème d’adresse → exceptionrecipient_refusedRefusé par le destinataire → exceptionrecipient_unreachableDestinataire injoignable → exceptionawaiting_recipient_actionEn attente du destinataire → exception
Incidents · 9 codes
delayedLivraison retardée → exceptionmisroutedErreur d’acheminement → exceptiondamagedColis endommagé → exceptionlostColis perdu → exceptionon_holdColis en attente → exceptionsecurity_checkColis en cours de contrôle → exceptionredirectedRéacheminé → in_transitcancelledExpédition annulée → exceptionno_updatesAucune mise à jour → expired
Retours · 2 codes
return_in_transitEn retour vers l’expéditeur → returnedreturn_deliveredRemis à l’expéditeur → returned
Référence
Chaque réponse est de la forme { "data": … }, avec meta pour les listes, ou { "error": … }. Les noms de champs sont en camelCase, les horodatages au format ISO 8601 avec décalage.
Commandes
POST/v1/ordersClé API
/v1/ordersClé APICrée une commande avec ses articles et ses colis en une seule transaction. Si un élément est invalide, rien n’est enregistré.
| Nom | Type | Description |
|---|---|---|
| Idempotency-Keyen-tête | string | Rend une nouvelle tentative sans risque : la même clé avec le même corps renvoie la première réponse. |
| orderNumbercorpsobligatoire | string | Votre propre numéro, de 1 à 40 caractères, unique. |
| storecorpsobligatoire | object | name est obligatoire ; url et supportEmail sont facultatifs. |
| customercorpsobligatoire | object | name est obligatoire. Les pages publiques l’affichent masqué. |
| destinationcorpsobligatoire | object | city et country sont obligatoires. Les lignes d’adresse n’apparaissent jamais sur les pages publiques. |
| itemscorpsobligatoire | Item[] | De 1 à 100 articles : title, quantity et, au choix, variant, unitPriceCents, imageUrl. ref relie un article à un colis. |
| shipmentscorps | Shipment[] | De 0 à 20 colis. Une commande peut être créée avant toute expédition. |
| localecorps | en | fr | zh | ru | La langue du client. |
curl -X POST "$API/v1/orders" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-2001" \
-d '{
"orderNumber": "HP-2001",
"store": { "name": "Atelier Nord" },
"customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
"destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" },
"items": [
{
"ref": "a",
"title": "Linen overshirt",
"variant": "Sand / M",
"quantity": 1,
"unitPriceCents": 8900,
"imageUrl": "https://cdn.example/overshirt.jpg"
}
],
"shipments": [
{
"trackingNumber": "6A20001118001",
"carrier": "la-poste",
"origin": { "city": "Lille", "country": "FR" },
"items": [ "a" ],
"simulate": { "scenario": "domestic_home", "autoStart": true }
}
]
}'const res = await fetch(`${API}/v1/orders`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'demo-2001' },
body: JSON.stringify({
"orderNumber": "HP-2001",
"store": { "name": "Atelier Nord" },
"customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
"destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" },
"items": [
{
"ref": "a",
"title": "Linen overshirt",
"variant": "Sand / M",
"quantity": 1,
"unitPriceCents": 8900,
"imageUrl": "https://cdn.example/overshirt.jpg"
}
],
"shipments": [
{
"trackingNumber": "6A20001118001",
"carrier": "la-poste",
"origin": { "city": "Lille", "country": "FR" },
"items": [ "a" ],
"simulate": { "scenario": "domestic_home", "autoStart": true }
}
]
}),
});
const { data } = await res.json();{
"data": {
"id": "ord_4h7k2m9x3pqa",
"orderNumber": "HP-2001",
"status": "pending",
"items": [ { "id": "itm_5c7n2w8h3dfa", "title": "Linen overshirt", "quantity": 1 } ],
"shipments": [ { "id": "shp_3v9x7b2m6kq4", "trackingNumber": "6A20001118001", "carrier": "la-poste", "status": "pending", "substatus": "info_received" } ]
},
"meta": { "trackUrl": "/v1/track/ord_4h7k2m9x3pqa", "publicPath": "/order/ord_4h7k2m9x3pqa" }
}GET/v1/ordersClé API
/v1/ordersClé APIListe les commandes, de la plus récente à la plus ancienne, avec filtres et pagination par curseur.
| Nom | Type | Description |
|---|---|---|
| qparamètre | string | Recherche dans le numéro de commande, le nom ou l’e-mail du client, ou un numéro de suivi. |
| statusparamètre | string | Un ou plusieurs codes de statut, séparés par des virgules. |
| demoparamètre | 0 | 1 | Uniquement les commandes de démonstration, ou uniquement les vôtres. |
| expandparamètre | shipments | events | Inclut les étapes de chaque colis. |
| limitparamètre | integer | Taille de la page. 20 par défaut, 100 au plus. |
| cursorparamètre | string | La valeur meta.nextCursor de la page précédente. |
curl "$API/v1/orders?status=exception,failed_attempt&limit=10" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/orders?status=exception,failed_attempt&limit=10`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": [ /* Order, Order, … */ ],
"meta": { "limit": 10, "nextCursor": null, "total": 3 }
}GET/v1/orders/:refClé API
/v1/orders/:refClé APIRenvoie une commande complète, données personnelles comprises.
| Nom | Type | Description |
|---|---|---|
| refcheminobligatoire | string | L’identifiant ou le numéro de la commande. |
| expandparamètre | events | Inclut les étapes de chaque colis. |
curl "$API/v1/orders/HP-1042?expand=events" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/orders/HP-1042?expand=events`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": {
"id": "ord_8k2m4x9p1qrt",
"orderNumber": "HP-1042",
"store": { "name": "Atelier Nord" },
"customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
"destination": { "line1": "12 rue de la République", "city": "Lyon", "postalCode": "69002", "country": "FR" },
"status": "in_transit",
"items": [ /* Item */ ],
"shipments": [ /* Shipment, with events */ ]
}
}PATCH/v1/orders/:refClé API
/v1/orders/:refClé APIMet à jour une commande : étapes de préparation, message pour le client, articles. Le numéro de commande ne change jamais.
| Nom | Type | Description |
|---|---|---|
| refcheminobligatoire | string | L’identifiant ou le numéro de la commande. |
| processingAt · readyAt · cancelledAtcorps | ISO 8601 | Quand la boutique a commencé la préparation, terminé l’emballage, ou annulé. |
| noticecorps | string | null | Un court message de la boutique, affiché sur la page de la commande. |
| itemscorps | { add, update, remove } | Articles à ajouter, modifier ou retirer. |
curl -X PATCH "$API/v1/orders/HP-2001" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"processingAt": "2026-11-18T11:00:00+01:00",
"notice": "Packed with care — ships tomorrow."
}'const res = await fetch(`${API}/v1/orders/HP-2001`, {
method: 'PATCH',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"processingAt": "2026-11-18T11:00:00+01:00",
"notice": "Packed with care — ships tomorrow."
}),
});
const { data } = await res.json();{ "data": { /* the full order */ } }DELETE/v1/orders/:refClé API
/v1/orders/:refClé APISupprime une commande avec ses colis, ses articles et ses étapes.
| Nom | Type | Description |
|---|---|---|
| refcheminobligatoire | string | L’identifiant ou le numéro de la commande. |
curl -X DELETE "$API/v1/orders/HP-2001" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/orders/HP-2001`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${KEY}` },
});
// res.status === 204HTTP/1.1 204 No ContentÉtapes
POST/v1/shipments/:id/eventsClé API
/v1/shipments/:id/eventsClé APIAjoute une étape, ou jusqu’à 50 dans un tableau events. Les étapes peuvent arriver dans n’importe quel ordre : le statut est toujours celui de la plus récente.
| Nom | Type | Description |
|---|---|---|
| idcheminobligatoire | string | L’identifiant du colis ou son numéro de suivi. |
| substatuscorpsobligatoire | string | Ce qui s’est passé, sous la forme d’un code du modèle de statuts. |
| occurredAtcorps | ISO 8601 | Quand cela s’est passé, avec le décalage horaire local. Par défaut : maintenant. |
| locationcorps | { place } | { city, country, … } | Un code de lieu, ou des champs libres avec coordonnées facultatives. |
| message · messageLangcorps | string | Le texte d’origine du transporteur et sa langue. Renvoyé tel quel. |
| detailscorps | object | Compléments pour certains codes : signedBy, window, deadline, reason. |
| externalIdcorps | string | Votre propre identifiant pour l’étape : envoyée deux fois, elle n’est enregistrée qu’une fois. |
curl -X POST "$API/v1/shipments/6A20001118001/events" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"substatus": "out_for_delivery",
"location": { "place": "LYS" },
"message": "Votre colis est en cours de livraison.",
"messageLang": "fr",
"details": { "window": "14:00-18:00" }
}'const res = await fetch(`${API}/v1/shipments/6A20001118001/events`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"substatus": "out_for_delivery",
"location": { "place": "LYS" },
"message": "Votre colis est en cours de livraison.",
"messageLang": "fr",
"details": { "window": "14:00-18:00" }
}),
});
const { data } = await res.json();{
"data": {
"created": [ { "id": "evt_9t4r6y1n8zc2", "status": "out_for_delivery", "substatus": "out_for_delivery", "occurredAt": "2026-11-18T09:12:00+01:00" } ],
"duplicates": [],
"shipment": { "id": "shp_3v9x7b2m6kq4", "status": "out_for_delivery", "substatus": "out_for_delivery", "lastEventAt": "2026-11-18T09:12:00+01:00" }
}
}DELETE/v1/shipments/:id/events/:eventIdClé API
/v1/shipments/:id/events/:eventIdClé APISupprime une étape erronée. Le statut est recalculé.
| Nom | Type | Description |
|---|---|---|
| idcheminobligatoire | string | L’identifiant du colis ou son numéro de suivi. |
| eventIdcheminobligatoire | string | L’étape à supprimer. |
curl -X DELETE "$API/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${KEY}` },
});
// res.status === 204HTTP/1.1 204 No ContentColis
POST/v1/shipmentsClé API
/v1/shipmentsClé APICrée un colis seul ou le rattache à une commande existante. Seul le numéro de suivi est obligatoire.
| Nom | Type | Description |
|---|---|---|
| Idempotency-Keyen-tête | string | Rend une nouvelle tentative sans risque : la même clé avec le même corps renvoie la première réponse. |
| trackingNumbercorpsobligatoire | string | Enregistré en majuscules, sans espaces. Unique. |
| carriercorps | slug | Facultatif quand la forme du numéro désigne un seul transporteur. |
| lastMilecorps | { trackingNumber, carrier } | Le transporteur qui prend le relais dans le pays de destination, et son numéro. |
| origin · destinationcorps | object | Ville et pays, ou code de lieu. La destination reprend par défaut celle de la commande. |
| deliveryTypecorps | home | pickup_point | locker | mailbox | L’endroit où le colis est remis. |
| etacorps | { from, to, window, source } | Livraison prévue : une date ou une plage, et qui l’annonce. |
| orderId · orderNumbercorps | string | Rattache le colis à une commande existante. |
| simulatecorps | { scenario, autoStart } | Associe un scénario du simulateur ; autoStart joue aussitôt sa première étape. |
curl -X POST "$API/v1/shipments" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"trackingNumber": "1Z999AA10123456784",
"label": "Desk lamp",
"origin": { "city": "Chicago", "country": "US" },
"destination": { "city": "Austin", "region": "TX", "country": "US" },
"simulate": { "scenario": "us_domestic" }
}'const res = await fetch(`${API}/v1/shipments`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"trackingNumber": "1Z999AA10123456784",
"label": "Desk lamp",
"origin": { "city": "Chicago", "country": "US" },
"destination": { "city": "Austin", "region": "TX", "country": "US" },
"simulate": { "scenario": "us_domestic" }
}),
});
const { data } = await res.json();{
"data": {
"id": "shp_7d2k9m4x1qpa",
"orderId": null,
"trackingNumber": "1Z999AA10123456784",
"carrier": "ups",
"status": "pending",
"substatus": "info_received",
"simulation": { "scenario": "us_domestic", "step": 1, "remaining": 8 },
"events": [ /* one automatic "label created" checkpoint */ ]
}
}GET/v1/shipmentsClé API
/v1/shipmentsClé APIListe les colis, du plus récent au plus ancien, avec filtres et pagination par curseur.
| Nom | Type | Description |
|---|---|---|
| qparamètre | string | Recherche dans le numéro de suivi, le libellé ou le numéro de commande. |
| status · substatus · carrierparamètre | string | Filtre par statut, sous-statut ou transporteur. |
| expandparamètre | events | Inclut les étapes de chaque colis. |
| limitparamètre | integer | Taille de la page. 20 par défaut, 100 au plus. |
| cursorparamètre | string | La valeur meta.nextCursor de la page précédente. |
curl "$API/v1/shipments?status=in_transit&carrier=china-post" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments?status=in_transit&carrier=china-post`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": [ /* Shipment, Shipment, … */ ],
"meta": { "limit": 20, "nextCursor": null, "total": 2 }
}GET/v1/shipments/:idClé API
/v1/shipments/:idClé APIRenvoie un colis avec toutes ses étapes, la plus récente en premier. Le numéro de suivi peut remplacer l’identifiant.
| Nom | Type | Description |
|---|---|---|
| idcheminobligatoire | string | L’identifiant du colis ou son numéro de suivi. |
curl "$API/v1/shipments/6A20001118001" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments/6A20001118001`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": {
"id": "shp_3v9x7b2m6kq4",
"trackingNumber": "6A20001118001",
"carrier": "la-poste",
"status": "in_transit",
"substatus": "arrived_hub",
"eta": { "from": "2026-11-21", "to": "2026-11-22", "window": null, "source": "store" },
"simulation": { "scenario": "domestic_home", "step": 3, "remaining": 4 },
"events": [ /* Event, newest first */ ]
}
}PATCH/v1/shipments/:idClé API
/v1/shipments/:idClé APIModifie l’estimation, le transporteur, le dernier kilomètre, le point de retrait ou le scénario du simulateur. Le statut ne change que par les étapes.
| Nom | Type | Description |
|---|---|---|
| idcheminobligatoire | string | L’identifiant du colis ou son numéro de suivi. |
| etacorps | object | null | Livraison prévue : une date ou une plage, et qui l’annonce. |
| carrier · lastMilecorps | slug · object | Le transporteur qui prend le relais dans le pays de destination, et son numéro. |
| simulatecorps | { scenario } | null | Associe un scénario du simulateur ; autoStart joue aussitôt sa première étape. |
curl -X PATCH "$API/v1/shipments/6A20001118001" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"eta": { "from": "2026-11-20", "to": "2026-11-21", "source": "carrier" }
}'const res = await fetch(`${API}/v1/shipments/6A20001118001`, {
method: 'PATCH',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"eta": { "from": "2026-11-20", "to": "2026-11-21", "source": "carrier" }
}),
});
const { data } = await res.json();{ "data": { /* the shipment */ } }DELETE/v1/shipments/:idClé API
/v1/shipments/:idClé APISupprime un colis et ses étapes.
| Nom | Type | Description |
|---|---|---|
| idcheminobligatoire | string | L’identifiant du colis ou son numéro de suivi. |
curl -X DELETE "$API/v1/shipments/6A20001118001" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments/6A20001118001`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${KEY}` },
});
// res.status === 204HTTP/1.1 204 No ContentSuivi (public)
GET/v1/track/:refPublic
/v1/track/:refPublicRecherche un colis par numéro de suivi, ou une commande entière par numéro ou identifiant de commande. C’est la réponse à partir de laquelle chaque page de suivi est construite.
| Nom | Type | Description |
|---|---|---|
| refcheminobligatoire | string | Un numéro de suivi, un numéro de dernier kilomètre, un numéro de commande, un identifiant de commande ou de colis. |
| langparamètre | en | fr | zh | ru | Langue des libellés, des descriptions et des noms de lieux. Par défaut en. |
| eventsparamètre | all | latest | latest ne renvoie que la dernière étape de chaque colis (pour les listes). |
| verifyparamètre | string | E-mail du client ou code postal, quand le serveur demande de confirmer les recherches de commande. |
curl "$API/v1/track/LV202611181CN?lang=fr"const res = await fetch(`${API}/v1/track/LV202611181CN?lang=fr`);
const { data } = await res.json();{
"data": {
"kind": "shipment",
"query": "LV202611181CN",
"lang": "fr",
"shipment": {
"trackingNumber": "LV202611181CN",
"status": { "code": "in_transit", "label": "En transit", "tone": "info" },
"substatus": { "code": "arrived_hub", "label": "Arrivé au centre de tri" },
"eta": { "from": "2026-11-19", "to": "2026-11-19", "source": "carrier" },
"milestones": [ /* key, label, state, at */ ],
"progress": { "percent": 68, "from": "import", "to": "out_for_delivery", "legFraction": 0.4, "direction": "forward", "halted": false },
"events": [ /* newest first */ ]
},
"siblings": [ /* the other parcels of the same order */ ]
}
}GET /v1/track/LV202611181CN?lang=fr&events=latestPOST/v1/track/batchPublic
/v1/track/batchPublicRecherche jusqu’à 40 références en un appel. Chacune reçoit son propre résultat, trouvée ou non.
| Nom | Type | Description |
|---|---|---|
| refscorpsobligatoire | string[] | De 1 à 40 références. Les doublons sont fusionnés. |
| langcorps | en | fr | zh | ru | Langue des libellés, des descriptions et des noms de lieux. Par défaut en. |
| eventscorps | latest | all | latest ne renvoie que la dernière étape de chaque colis (pour les listes). |
curl -X POST "$API/v1/track/batch" \
-H "Content-Type: application/json" \
-d '{
"refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
"lang": "en"
}'const res = await fetch(`${API}/v1/track/batch`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
"lang": "en"
}),
});
const { data } = await res.json();{
"data": {
"lang": "en",
"results": [
{ "query": "LV202611181CN", "found": true, "kind": "shipment", "shipment": { /* … */ } },
{ "query": "HP-1042", "found": true, "kind": "order", "order": { /* … */ } },
{ "query": "ABC", "found": false, "notFound": { "kind": "unknown", "plausible": false, "candidates": [] } }
],
"counts": { "total": 4, "found": 3, "notFound": 1, "byStatus": { "in_transit": 2, "out_for_delivery": 1, "pending": 1 } }
}
}Transporteurs et détection
POST/v1/detectPublic
/v1/detectPublicExtrait les références d’un texte libre et classe les transporteurs possibles pour chacune.
| Nom | Type | Description |
|---|---|---|
| inputcorpsobligatoire | string | Texte libre, 5 000 caractères au plus. |
| langcorps | en | fr | zh | ru | Langue des libellés, des descriptions et des noms de lieux. Par défaut en. |
curl -X POST "$API/v1/detect" \
-H "Content-Type: application/json" \
-d '{
"input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
}'const res = await fetch(`${API}/v1/detect`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
}),
});
const { data } = await res.json();{
"data": {
"items": [
{ "raw": "1ZVAD0DEMO00000001", "normalized": "1ZVAD0DEMO00000001", "kind": "tracking", "known": true, "checkDigit": "na",
"candidates": [ { "carrier": { "slug": "ups", "displayName": "UPS" }, "confidence": 1, "reason": "known" } ] },
{ "raw": "rr123456785gb", "normalized": "RR123456785GB", "kind": "tracking", "known": false, "checkDigit": "ok",
"candidates": [ { "carrier": { "slug": "royal-mail", "displayName": "Royal Mail" }, "confidence": 0.9, "reason": "s10_country" } ] },
{ "raw": "HP-1042", "normalized": "HP-1042", "kind": "order", "known": true, "checkDigit": "na", "candidates": [] }
],
"duplicatesRemoved": 0
}
}GET/v1/carriersPublic
/v1/carriersPublicL’annuaire des transporteurs, avec les motifs qui servent à reconnaître les numéros.
| Nom | Type | Description |
|---|---|---|
| qparamètre | string | Recherche dans le nom, le nom local ou l’identifiant. |
| countryparamètre | ISO 3166-1 alpha-2 | Code pays à deux lettres. |
| kindparamètre | postal | express | ecommerce | regional | Type de transporteur. |
| popularparamètre | 1 | Uniquement les transporteurs affichés en premier. |
| langparamètre | en | fr | zh | ru | Langue des libellés, des descriptions et des noms de lieux. Par défaut en. |
curl "$API/v1/carriers?popular=1&lang=ru"const res = await fetch(`${API}/v1/carriers?popular=1&lang=ru`);
const { data } = await res.json();{
"data": [
{ "slug": "cdek", "name": "CDEK", "nameLocal": "СДЭК", "displayName": "СДЭК", "country": "RU", "countryName": "Россия", "kind": "express",
"monogram": "СД", "color": "#1AB248", "logoUrl": null, "website": "https://www.cdek.ru",
"patterns": [ { "regex": "^\\d{10,11}$", "weight": 0.4 } ], "example": "1500042017", "popularRank": 11 }
],
"meta": { "total": 12 }
}GET /v1/carriers?popular=1&lang=frGET/v1/carriers/:slugPublic
/v1/carriers/:slugPublicUn transporteur, par son identifiant.
| Nom | Type | Description |
|---|---|---|
| slugcheminobligatoire | string | L’identifiant du transporteur, par exemple la-poste. |
| langparamètre | en | fr | zh | ru | Langue des libellés, des descriptions et des noms de lieux. Par défaut en. |
curl "$API/v1/carriers/la-poste"const res = await fetch(`${API}/v1/carriers/la-poste`);
const { data } = await res.json();{ "data": { "slug": "la-poste", "name": "La Poste (Colissimo)", "country": "FR", "kind": "postal", "example": "6A12345678901", "patterns": [ /* … */ ] } }GET /v1/carriers/la-poste?lang=frGET/v1/statusesPublic
/v1/statusesPublicLe modèle de statuts avec libellés et descriptions dans une langue, ou dans les quatre.
| Nom | Type | Description |
|---|---|---|
| langparamètre | en | fr | zh | ru | all | all renvoie les quatre langues côte à côte. |
curl "$API/v1/statuses?lang=zh"const res = await fetch(`${API}/v1/statuses?lang=zh`);
const { data } = await res.json();{
"data": {
"version": "1.0.0",
"lang": "zh",
"statuses": [ { "code": "in_transit", "label": "运输中", "description": "包裹正在运往目的地的途中。", "tone": "info", "terminal": false } ],
"substatuses": [ { "code": "arrived_hub", "status": "in_transit", "group": "hub", "severity": "info", "actor": "none", "label": "到达分拣中心" } ],
"milestones": [ { "key": "shipped", "label": "已发货", "crossBorderOnly": false } ],
"defaultSubstatus": { "in_transit": "in_transit", "delivered": "delivered" }
}
}GET /v1/statuses?lang=frGET/v1/placesPublic
/v1/placesPublicLes lieux auxquels une étape peut renvoyer : noms localisés, coordonnées et fuseaux horaires.
| Nom | Type | Description |
|---|---|---|
| countryparamètre | ISO 3166-1 alpha-2 | Code pays à deux lettres. |
| langparamètre | en | fr | zh | ru | Langue des libellés, des descriptions et des noms de lieux. Par défaut en. |
curl "$API/v1/places?lang=en&country=FR"const res = await fetch(`${API}/v1/places?lang=en&country=FR`);
const { data } = await res.json();{ "data": [ { "code": "LYS", "name": "Lyon", "region": null, "country": "FR", "countryName": "France", "lat": 45.76, "lon": 4.84, "tz": "Europe/Paris" } ] }GET /v1/places?lang=fr&country=FRGET/healthPublic
/healthPublicÉtat du service et nombre d’enregistrements.
curl "$API/health"const res = await fetch(`${API}/health`);
const { data } = await res.json();{ "data": { "status": "ok", "version": "1.0.0", "time": "2026-11-18T10:00:00.000Z", "db": { "orders": 9, "shipments": 14, "events": 94 }, "simulator": { "auto": false, "intervalSeconds": 45 } } }GET /healthSimulateur
GET/v1/simulator/scenariosPublic
/v1/simulator/scenariosPublicLes parcours que le simulateur sait jouer.
curl "$API/v1/simulator/scenarios"const res = await fetch(`${API}/v1/simulator/scenarios`);
const { data } = await res.json();{
"data": [
{ "key": "cn_eu", "title": "China → EU, postal hand-off", "steps": 14, "ends": "delivered", "crossBorder": true,
"defaultCarrier": "china-post", "defaultLastMile": "la-poste", "defaultOrigin": "SZX", "defaultDestination": "LYS",
"stepsPreview": [ "info_received", "picked_up", "arrived_hub", "…" ] }
]
}GET /v1/simulator/scenariosPOST/v1/simulator/shipments/:id/advanceClé API
/v1/simulator/shipments/:id/advanceClé APIAjoute les prochaines étapes prévues d’un colis simulé.
| Nom | Type | Description |
|---|---|---|
| idcheminobligatoire | string | L’identifiant du colis ou son numéro de suivi. |
| stepscorps | 1–20 | Nombre d’étapes prévues à ajouter. 1 par défaut. |
| tocorps | substatus | "end" | Avance jusqu’à ce que ce code ait été émis, ou jusqu’à la fin. |
| atcorps | now | spaced | spaced antidate les étapes avec des écarts réalistes, la dernière tombant maintenant. |
curl -X POST "$API/v1/simulator/shipments/6A20001118001/advance" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{ "steps": 1 }'const res = await fetch(`${API}/v1/simulator/shipments/6A20001118001/advance`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ "steps": 1 }),
});
const { data } = await res.json();{
"data": {
"created": [ /* Event */ ],
"finished": false,
"shipment": { "id": "shp_3v9x7b2m6kq4", "status": "in_transit", "substatus": "arrived_delivery_depot",
"simulation": { "scenario": "domestic_home", "step": 5, "remaining": 2 } }
}
}POST/v1/simulator/resetClé API
/v1/simulator/resetClé APISupprime les commandes de démonstration et les recrée avec des dates récentes. Les commandes que vous avez créées sont conservées.
| Nom | Type | Description |
|---|---|---|
| allcorps | boolean | Supprime aussi les commandes créées à la main. |
curl -X POST "$API/v1/simulator/reset" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/simulator/reset`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{ "data": { "orders": 9, "shipments": 14, "events": 94 } }Erreurs
Toutes les erreurs ont la même enveloppe : un code stable, un message destiné aux développeurs et, quand c’est utile, details.
| HTTP | Code | Quand |
|---|---|---|
| 400 | bad_request | Le JSON est mal formé ou le type de contenu est incorrect. |
| 401 | unauthorized | La clé API est absente ou erronée. |
| 403 | verification_required | Le serveur demande de confirmer une recherche de commande et verify est absent ou erroné. |
| 404 | not_found | Identifiant ou référence inconnus. Pour les recherches, details indique à quoi ressemble le numéro. |
| 409 | order_exists | Ce numéro de commande est déjà pris. details.existingId désigne la commande. |
| 409 | tracking_exists | Ce numéro de suivi est déjà enregistré. |
| 409 | idempotency_conflict | La même clé d’idempotence est arrivée avec un corps différent. |
| 413 | too_many | Plus de 40 références, 50 étapes ou 100 articles dans un même appel. |
| 422 | validation_error | Le corps n’a pas passé la validation. details donne chaque chemin et son problème. |
| 429 | rate_limited | Trop d’appels publics depuis une même adresse. Attendez la durée indiquée par Retry-After. |
| 500 | internal | Tout le reste. Le message est générique ; la cause figure dans le journal du serveur. |
{
"error": {
"code": "validation_error",
"message": "Request body is invalid.",
"details": [ { "path": "items[0].quantity", "message": "Must be an integer ≥ 1" } ]
}
}Idempotence
- Envoyez un en-tête
Idempotency-Keyde 100 caractères au plus quand vous créez une commande ou un colis. - La première réponse réussie est conservée 24 h et rejouée pour la même clé et le même corps, avec l’en-tête
Idempotent-Replay: true. - La même clé avec un corps différent renvoie
409 idempotency_conflict. - Même sans cet en-tête, un numéro de commande est unique : l’envoyer de nouveau renvoie
409 order_exists.
Idempotency-Key: demo-2001Langues
?lang=en|fr|zh|ru change les libellés, les descriptions, les noms de lieux et de pays. Les messages bruts des transporteurs sont renvoyés tels quels.
curl "$API/v1/track/LV202611181CN?lang=fr"
curl "$API/v1/track/LV202611181CN?lang=zh"
curl "$API/v1/track/LV202611181CN?lang=ru"Données de démonstration
Quatorze colis de démonstration couvrent tous les statuts. Un simulateur les fait avancer : la colonne Statut indique donc où se trouve chacun à l’instant.
| Numéro de suivi | Transporteur | Trajet | Statut |
|---|---|---|---|
| LV 2026 1118 1CN | Shenzhen → Lyon | En transit | |
| LP 0042 0000 0000 17 | Shenzhen → Lyon | En préparation | |
| 1ZVA D0DE MO00 0000 01 | Chicago → Austin | En cours de livraison | |
| 6A10 0000 00011 | Lille → Bordeaux | Livré | |
| XW 1234 5678 5FR | Paris → Marseille | Tentative échouée | |
| 24680135 | Nantes → Toulouse | À retirer | |
| RV 1042 0001 9CN | Yiwu → Kazan | Incident de livraison | |
| 1500 0420 17 | Moscou → Novossibirsk | En transit | |
| YT 2611 1800 0000 0042 | YunExpress | Yiwu → Portland | Livré |
| 7700 1111 8888 | New York → Denver | Incident de livraison | |
| 4810 0020 26 | Hong Kong → Londres | Retour à l’expéditeur | |
| SF 1000 0000 02026 | Shenzhen → Hangzhou | Livré | |
| H00V AD00 0000 0001 | Evri | Manchester → Londres | Aucune mise à jour récente |
| 2500 0000 0020 26 | Paris → Lille | En préparation |