Aller au contenu

L’API Hopla

Créez des commandes, rattachez des colis, ajoutez des étapes de suivi. Tout ce qu’affiche une page de suivi Hopla vient de ces points d’accès.

URL de basehttps://hopla.delivery
JSON/v1Bearer

De zéro à une page de suivi en trois appels

Les exemples utilisent deux variables shell. Définissez-les une fois :

shell
API=https://hopla.delivery
KEY=hopla_dev_key
  1. Cré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 }
          }
        ]
      }'
  2. 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" }
      }'
  3. 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.

header
Authorization: Bearer hopla_dev_key

X-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
Points d’accès publicsDescription
GET /v1/track/:refRecherche 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/batchRecherche jusqu’à 40 références en un appel. Chacune reçoit son propre résultat, trouvée ou non.
POST /v1/detectExtrait les références d’un texte libre et classe les transporteurs possibles pour chacune.
GET /v1/carriersL’annuaire des transporteurs, avec les motifs qui servent à reconnaître les numéros.
GET /v1/carriers/:slugUn transporteur, par son identifiant.
GET /v1/statusesLe modèle de statuts avec libellés et descriptions dans une langue, ou dans les quatre.
GET /v1/placesLes 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/scenariosLes 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.

StatutCodeSignification
En préparationpendingL’expéditeur a enregistré ce colis, mais le transporteur ne l’a pas encore pris en charge.
En transitin_transitLe colis est en cours d’acheminement vers sa destination.
En cours de livraisonout_for_deliveryLe colis est entre les mains du livreur et devrait être livré aujourd’hui.
À retireravailable_for_pickupLe 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édeliveredfinalLe colis a été livré.
Tentative échouéefailed_attemptLe 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 livraisonexceptionUn incident retarde ce colis. Consultez la dernière étape pour connaître la suite.
Retour à l’expéditeurreturnedLe colis repart, ou est déjà reparti, chez l’expéditeur.
Aucune mise à jour récenteexpiredLe 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 → pending
  • order_processingEn cours de préparation → pending
  • order_readyCommande prête → pending
Prise en charge · 5 codes
  • info_receivedÉtiquette créée → pending
  • awaiting_carrier_pickupEn attente d’enlèvement → pending
  • picked_upPris en charge par le transporteur → in_transit
  • dropped_offDéposé en point de collecte → in_transit
  • accepted_originArrivé au centre de départ → in_transit
En chemin · 4 codes
  • arrived_hubArrivé au centre de tri → in_transit
  • sortedTri effectué → in_transit
  • departed_hubParti du centre de tri → in_transit
  • in_transitEn cours d’acheminement → in_transit
Export · 4 codes
  • export_hub_arrivedArrivé au centre d’export → in_transit
  • export_customsDédouanement à l’export → in_transit
  • departed_origin_countryA quitté le pays d’expédition → in_transit
  • transit_countryEn transit dans un pays tiers → in_transit
Douane et import · 7 codes
  • arrived_destination_countryArrivé dans le pays de destination → in_transit
  • customs_processingEn cours de dédouanement → in_transit
  • customs_clearedDédouanement terminé → in_transit
  • customs_heldRetenu en douane → exception
  • customs_duties_dueDroits et taxes à régler → exception
  • customs_info_requiredInformations demandées par la douane → exception
  • handed_to_local_carrierRemis au transporteur local → in_transit
Dernier kilomètre · 8 codes
  • arrived_delivery_depotArrivé sur le site de livraison → in_transit
  • out_for_deliveryEn cours de livraison → out_for_delivery
  • delivery_rescheduledLivraison reportée → in_transit
  • deliveredLivré → delivered
  • delivered_mailboxLivré en boîte aux lettres → delivered
  • delivered_signedLivré contre signature → delivered
  • delivered_third_partyRemis à un voisin ou à l’accueil → delivered
  • delivered_safe_placeDéposé à l’endroit convenu → delivered
Points de retrait · 4 codes
  • arrived_pickup_pointDisponible en point de retrait → available_for_pickup
  • pickup_reminderRappel de retrait → available_for_pickup
  • picked_up_by_recipientColis retiré → delivered
  • pickup_expiredColis non réclamé → returned
Tentatives de livraison · 6 codes
  • attempt_absentDestinataire absent → failed_attempt
  • attempt_closedÉtablissement fermé → failed_attempt
  • address_issueProblème d’adresse → exception
  • recipient_refusedRefusé par le destinataire → exception
  • recipient_unreachableDestinataire injoignable → exception
  • awaiting_recipient_actionEn attente du destinataire → exception
Incidents · 9 codes
  • delayedLivraison retardée → exception
  • misroutedErreur d’acheminement → exception
  • damagedColis endommagé → exception
  • lostColis perdu → exception
  • on_holdColis en attente → exception
  • security_checkColis en cours de contrôle → exception
  • redirectedRéacheminé → in_transit
  • cancelledExpédition annulée → exception
  • no_updatesAucune mise à jour → expired
Retours · 2 codes
  • return_in_transitEn retour vers l’expéditeur → returned
  • return_deliveredRemis à l’expéditeur → returned
Envoyez des codes, pas des phrases : Hopla rédige la phrase dans la langue du lecteur.

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

Crée une commande avec ses articles et ses colis en une seule transaction. Si un élément est invalide, rien n’est enregistré.

NomTypeDescription
Idempotency-Keyen-têtestringRend une nouvelle tentative sans risque : la même clé avec le même corps renvoie la première réponse.
orderNumbercorpsobligatoirestringVotre propre numéro, de 1 à 40 caractères, unique.
storecorpsobligatoireobjectname est obligatoire ; url et supportEmail sont facultatifs.
customercorpsobligatoireobjectname est obligatoire. Les pages publiques l’affichent masqué.
destinationcorpsobligatoireobjectcity et country sont obligatoires. Les lignes d’adresse n’apparaissent jamais sur les pages publiques.
itemscorpsobligatoireItem[]De 1 à 100 articles : title, quantity et, au choix, variant, unitPriceCents, imageUrl. ref relie un article à un colis.
shipmentscorpsShipment[]De 0 à 20 colis. Une commande peut être créée avant toute expédition.
localecorpsen | fr | zh | ruLa langue du client.
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 }
      }
    ]
  }'

GET/v1/ordersClé API

Liste les commandes, de la plus récente à la plus ancienne, avec filtres et pagination par curseur.

NomTypeDescription
qparamètrestringRecherche dans le numéro de commande, le nom ou l’e-mail du client, ou un numéro de suivi.
statusparamètrestringUn ou plusieurs codes de statut, séparés par des virgules.
demoparamètre0 | 1Uniquement les commandes de démonstration, ou uniquement les vôtres.
expandparamètreshipments | eventsInclut les étapes de chaque colis.
limitparamètreintegerTaille de la page. 20 par défaut, 100 au plus.
cursorparamètrestringLa valeur meta.nextCursor de la page précédente.
GET /v1/orders
curl "$API/v1/orders?status=exception,failed_attempt&limit=10" \
  -H "Authorization: Bearer $KEY"

GET/v1/orders/:refClé API

Renvoie une commande complète, données personnelles comprises.

NomTypeDescription
refcheminobligatoirestringL’identifiant ou le numéro de la commande.
expandparamètreeventsInclut les étapes de chaque colis.
GET /v1/orders/:ref
curl "$API/v1/orders/HP-1042?expand=events" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/orders/:refClé API

Met à jour une commande : étapes de préparation, message pour le client, articles. Le numéro de commande ne change jamais.

NomTypeDescription
refcheminobligatoirestringL’identifiant ou le numéro de la commande.
processingAt · readyAt · cancelledAtcorpsISO 8601Quand la boutique a commencé la préparation, terminé l’emballage, ou annulé.
noticecorpsstring | nullUn court message de la boutique, affiché sur la page de la commande.
itemscorps{ add, update, remove }Articles à ajouter, modifier ou retirer.
PATCH /v1/orders/:ref
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."
  }'

DELETE/v1/orders/:refClé API

Supprime une commande avec ses colis, ses articles et ses étapes.

NomTypeDescription
refcheminobligatoirestringL’identifiant ou le numéro de la commande.
DELETE /v1/orders/:ref
curl -X DELETE "$API/v1/orders/HP-2001" \
  -H "Authorization: Bearer $KEY"

Étapes

POST/v1/shipments/:id/eventsClé API

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

NomTypeDescription
idcheminobligatoirestringL’identifiant du colis ou son numéro de suivi.
substatuscorpsobligatoirestringCe qui s’est passé, sous la forme d’un code du modèle de statuts.
occurredAtcorpsISO 8601Quand 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 · messageLangcorpsstringLe texte d’origine du transporteur et sa langue. Renvoyé tel quel.
detailscorpsobjectCompléments pour certains codes : signedBy, window, deadline, reason.
externalIdcorpsstringVotre propre identifiant pour l’étape : envoyée deux fois, elle n’est enregistrée qu’une fois.
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" }
  }'

DELETE/v1/shipments/:id/events/:eventIdClé API

Supprime une étape erronée. Le statut est recalculé.

NomTypeDescription
idcheminobligatoirestringL’identifiant du colis ou son numéro de suivi.
eventIdcheminobligatoirestringL’étape à supprimer.
DELETE /v1/shipments/:id/events/:eventId
curl -X DELETE "$API/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2" \
  -H "Authorization: Bearer $KEY"

Colis

POST/v1/shipmentsClé API

Crée un colis seul ou le rattache à une commande existante. Seul le numéro de suivi est obligatoire.

NomTypeDescription
Idempotency-Keyen-têtestringRend une nouvelle tentative sans risque : la même clé avec le même corps renvoie la première réponse.
trackingNumbercorpsobligatoirestringEnregistré en majuscules, sans espaces. Unique.
carriercorpsslugFacultatif 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 · destinationcorpsobjectVille et pays, ou code de lieu. La destination reprend par défaut celle de la commande.
deliveryTypecorpshome | pickup_point | locker | mailboxL’endroit où le colis est remis.
etacorps{ from, to, window, source }Livraison prévue : une date ou une plage, et qui l’annonce.
orderId · orderNumbercorpsstringRattache le colis à une commande existante.
simulatecorps{ scenario, autoStart }Associe un scénario du simulateur ; autoStart joue aussitôt sa première étape.
POST /v1/shipments
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" }
  }'

GET/v1/shipmentsClé API

Liste les colis, du plus récent au plus ancien, avec filtres et pagination par curseur.

NomTypeDescription
qparamètrestringRecherche dans le numéro de suivi, le libellé ou le numéro de commande.
status · substatus · carrierparamètrestringFiltre par statut, sous-statut ou transporteur.
expandparamètreeventsInclut les étapes de chaque colis.
limitparamètreintegerTaille de la page. 20 par défaut, 100 au plus.
cursorparamètrestringLa valeur meta.nextCursor de la page précédente.
GET /v1/shipments
curl "$API/v1/shipments?status=in_transit&carrier=china-post" \
  -H "Authorization: Bearer $KEY"

GET/v1/shipments/:idClé API

Renvoie un colis avec toutes ses étapes, la plus récente en premier. Le numéro de suivi peut remplacer l’identifiant.

NomTypeDescription
idcheminobligatoirestringL’identifiant du colis ou son numéro de suivi.
GET /v1/shipments/:id
curl "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/shipments/:idClé API

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

NomTypeDescription
idcheminobligatoirestringL’identifiant du colis ou son numéro de suivi.
etacorpsobject | nullLivraison prévue : une date ou une plage, et qui l’annonce.
carrier · lastMilecorpsslug · objectLe transporteur qui prend le relais dans le pays de destination, et son numéro.
simulatecorps{ scenario } | nullAssocie un scénario du simulateur ; autoStart joue aussitôt sa première étape.
PATCH /v1/shipments/:id
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" }
  }'

DELETE/v1/shipments/:idClé API

Supprime un colis et ses étapes.

NomTypeDescription
idcheminobligatoirestringL’identifiant du colis ou son numéro de suivi.
DELETE /v1/shipments/:id
curl -X DELETE "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY"

Suivi (public)

GET/v1/track/:refPublic

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.

NomTypeDescription
refcheminobligatoirestringUn numéro de suivi, un numéro de dernier kilomètre, un numéro de commande, un identifiant de commande ou de colis.
langparamètreen | fr | zh | ruLangue des libellés, des descriptions et des noms de lieux. Par défaut en.
eventsparamètreall | latestlatest ne renvoie que la dernière étape de chaque colis (pour les listes).
verifyparamètrestringE-mail du client ou code postal, quand le serveur demande de confirmer les recherches de commande.
GET /v1/track/:ref
curl "$API/v1/track/LV202611181CN?lang=fr"
GET /v1/track/LV202611181CN?lang=fr&events=latest

POST/v1/track/batchPublic

Recherche jusqu’à 40 références en un appel. Chacune reçoit son propre résultat, trouvée ou non.

NomTypeDescription
refscorpsobligatoirestring[]De 1 à 40 références. Les doublons sont fusionnés.
langcorpsen | fr | zh | ruLangue des libellés, des descriptions et des noms de lieux. Par défaut en.
eventscorpslatest | alllatest ne renvoie que la dernière étape de chaque colis (pour les listes).
POST /v1/track/batch
curl -X POST "$API/v1/track/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
    "lang": "en"
  }'

Transporteurs et détection

POST/v1/detectPublic

Extrait les références d’un texte libre et classe les transporteurs possibles pour chacune.

NomTypeDescription
inputcorpsobligatoirestringTexte libre, 5 000 caractères au plus.
langcorpsen | fr | zh | ruLangue des libellés, des descriptions et des noms de lieux. Par défaut en.
POST /v1/detect
curl -X POST "$API/v1/detect" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
  }'

GET/v1/carriersPublic

L’annuaire des transporteurs, avec les motifs qui servent à reconnaître les numéros.

NomTypeDescription
qparamètrestringRecherche dans le nom, le nom local ou l’identifiant.
countryparamètreISO 3166-1 alpha-2Code pays à deux lettres.
kindparamètrepostal | express | ecommerce | regionalType de transporteur.
popularparamètre1Uniquement les transporteurs affichés en premier.
langparamètreen | fr | zh | ruLangue des libellés, des descriptions et des noms de lieux. Par défaut en.
GET /v1/carriers
curl "$API/v1/carriers?popular=1&lang=ru"
GET /v1/carriers?popular=1&lang=fr

GET/v1/carriers/:slugPublic

Un transporteur, par son identifiant.

NomTypeDescription
slugcheminobligatoirestringL’identifiant du transporteur, par exemple la-poste.
langparamètreen | fr | zh | ruLangue des libellés, des descriptions et des noms de lieux. Par défaut en.
GET /v1/carriers/:slug
curl "$API/v1/carriers/la-poste"
GET /v1/carriers/la-poste?lang=fr

GET/v1/statusesPublic

Le modèle de statuts avec libellés et descriptions dans une langue, ou dans les quatre.

NomTypeDescription
langparamètreen | fr | zh | ru | allall renvoie les quatre langues côte à côte.
GET /v1/statuses
curl "$API/v1/statuses?lang=zh"
GET /v1/statuses?lang=fr

GET/v1/placesPublic

Les lieux auxquels une étape peut renvoyer : noms localisés, coordonnées et fuseaux horaires.

NomTypeDescription
countryparamètreISO 3166-1 alpha-2Code pays à deux lettres.
langparamètreen | fr | zh | ruLangue des libellés, des descriptions et des noms de lieux. Par défaut en.
GET /v1/places
curl "$API/v1/places?lang=en&country=FR"
GET /v1/places?lang=fr&country=FR

GET/healthPublic

État du service et nombre d’enregistrements.

GET /health
curl "$API/health"
GET /health

Simulateur

GET/v1/simulator/scenariosPublic

Les parcours que le simulateur sait jouer.

GET /v1/simulator/scenarios
curl "$API/v1/simulator/scenarios"
GET /v1/simulator/scenarios

POST/v1/simulator/shipments/:id/advanceClé API

Ajoute les prochaines étapes prévues d’un colis simulé.

NomTypeDescription
idcheminobligatoirestringL’identifiant du colis ou son numéro de suivi.
stepscorps1–20Nombre d’étapes prévues à ajouter. 1 par défaut.
tocorpssubstatus | "end"Avance jusqu’à ce que ce code ait été émis, ou jusqu’à la fin.
atcorpsnow | spacedspaced antidate les étapes avec des écarts réalistes, la dernière tombant maintenant.
POST /v1/simulator/shipments/:id/advance
curl -X POST "$API/v1/simulator/shipments/6A20001118001/advance" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "steps": 1 }'

POST/v1/simulator/resetClé API

Supprime les commandes de démonstration et les recrée avec des dates récentes. Les commandes que vous avez créées sont conservées.

NomTypeDescription
allcorpsbooleanSupprime aussi les commandes créées à la main.
POST /v1/simulator/reset
curl -X POST "$API/v1/simulator/reset" \
  -H "Authorization: Bearer $KEY"

Erreurs

Toutes les erreurs ont la même enveloppe : un code stable, un message destiné aux développeurs et, quand c’est utile, details.

HTTPCodeQuand
400bad_requestLe JSON est mal formé ou le type de contenu est incorrect.
401unauthorizedLa clé API est absente ou erronée.
403verification_requiredLe serveur demande de confirmer une recherche de commande et verify est absent ou erroné.
404not_foundIdentifiant ou référence inconnus. Pour les recherches, details indique à quoi ressemble le numéro.
409order_existsCe numéro de commande est déjà pris. details.existingId désigne la commande.
409tracking_existsCe numéro de suivi est déjà enregistré.
409idempotency_conflictLa même clé d’idempotence est arrivée avec un corps différent.
413too_manyPlus de 40 références, 50 étapes ou 100 articles dans un même appel.
422validation_errorLe corps n’a pas passé la validation. details donne chaque chemin et son problème.
429rate_limitedTrop d’appels publics depuis une même adresse. Attendez la durée indiquée par Retry-After.
500internalTout le reste. Le message est générique ; la cause figure dans le journal du serveur.
422
{
  "error": {
    "code": "validation_error",
    "message": "Request body is invalid.",
    "details": [ { "path": "items[0].quantity", "message": "Must be an integer ≥ 1" } ]
  }
}

Idempotence

  1. Envoyez un en-tête Idempotency-Key de 100 caractères au plus quand vous créez une commande ou un colis.
  2. 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.
  3. La même clé avec un corps différent renvoie 409 idempotency_conflict.
  4. Même sans cet en-tête, un numéro de commande est unique : l’envoyer de nouveau renvoie 409 order_exists.
header
Idempotency-Key: demo-2001

Langues

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

GET /v1/track/:ref
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 suiviTransporteurTrajetStatut
LV 2026 1118 1CNChina PostShenzhen → LyonEn transit
LP 0042 0000 0000 17CainiaoShenzhen → LyonEn préparation
1ZVA D0DE MO00 0000 01UPSChicago → AustinEn cours de livraison
6A10 0000 00011La Poste (Colissimo)Lille → BordeauxLivré
XW 1234 5678 5FRChronopostParis → MarseilleTentative échouée
24680135Mondial RelayNantes → ToulouseÀ retirer
RV 1042 0001 9CNChina PostYiwu → KazanIncident de livraison
1500 0420 17CDEKMoscou → NovossibirskEn transit
YT 2611 1800 0000 0042YunExpressYiwu → PortlandLivré
7700 1111 8888FedExNew York → DenverIncident de livraison
4810 0020 26DHL ExpressHong Kong → LondresRetour à l’expéditeur
SF 1000 0000 02026SF ExpressShenzhen → HangzhouLivré
H00V AD00 0000 0001EvriManchester → LondresAucune mise à jour récente
2500 0000 0020 26DPD FranceParis → LilleEn préparation