Endpoints · Batch
Création en lot
Plusieurs bordereaux en un appel — avec succès partiel possible.
Crée plusieurs bordereaux : { "shippings": [...] }, tableau non vide. 200 tous créés · 207 succès partiel · 400 aucun créé · 403 blocage compte (lot entier refusé).
Un 207 n'est pas un échec. Les bordereaux créés sont réels et déjà dispatchés — ne rejouez pas le lot entier, vous dupliqueriez. Rejouez seulement les entrées listées dans errors, via leur index.
Convention inversée sur /batch
Dans errors[], le champ error est le message en prose et le champ code est le slug — l'inverse du reste de l'API. Chaque entrée vaut { index, error: "<prose>", code: "<SLUG>" | null }.
Branchez donc sur errors[].code. Un code écrit pour POST /shipping et recopié tel quel comparera un slug à une phrase française, et ne matchera jamais. Cette inversion est conservée volontairement : la corriger casserait les intégrations existantes.
code vaut null pour les refus qui n'ont pas de slug (créneau invalide, limite de crédit dépassée…).
Absence d'idempotence sur /batch
X-Idempotency-Key n'est pas lu par cet endpoint : l'en-tête est ignoré. Le filet qui protège POST /shipping du double-débit n'existe pas ici.
Conséquence : rejouer un lot de N bordereaux en crée N nouveaux, réels, dispatchés et facturés — il n'y a pas de rejeu à 200, pas de idempotent: true, aucun garde-fou.
Un timeout ou une réponse non vue sur /batch ne se rejoue pas à l'aveugle. Réconciliez d'abord (GET /shipping sur vos externalReference.orderId) et ne renvoyez que ce qui manque réellement. Si le double-débit vous est inacceptable, bouclez sur POST /shipping avec une clé par commande : c'est plus d'appels, mais c'est la seule voie protégée.