ShipBob : une réception terminée ne prouve pas le stock reçu

Le tableau de réception affiche « Completed ». Le connecteur ferme le dossier et ajoute à l’ERP les quantités annoncées au départ. Pourtant, un carton n’est jamais arrivé et quelques unités reçues n’ont pas été rangées. Le risque est immédiat : les achats pensent leur livraison complète, tandis que le commerce voit un stock que l’entrepôt ne peut pas forcément servir.

En pratique, le statut d’une réception ne remplace pas son rapprochement quantitatif. Il faut expliquer les unités attendues, reçues et rangées, puis appliquer une seule fois le mouvement ERP autorisé. Le marqueur de synchronisation distant intervient après cette preuve ; il ne suffit pas à protéger l’écriture si une réponse se perd entre les deux systèmes.

Cette coordination relève de l’intégration API entre logiciels métier. Elle demande notamment de qualifier les échanges WMS, OMS et stock avec le logisticien et votre installateur ERP : quel fait entre dans quel document, dans quelle unité, avec quelle reprise si l’un des accusés manque ?

Le point de départ est la documentation Receiving de ShipBob, mise à jour le 21 octobre 2026 et consultée le 24 octobre, pour le contrat 2026-07. Nous suivons une réception entièrement fictive de trois cartons, puis un programme SQLite reproductible. Il révèle quatre calculs trompeurs et éprouve les interruptions. Cette actualisation documentaire ne signifie pas que toutes les fonctions présentées viennent d’être lancées.

Pour qui : raccorder les arrivages du logisticien à l’ERP

Un dossier d’achat plutôt qu’un simple compteur de stock

Le sujet concerne une marque, un distributeur ou un éditeur qui doit expliquer une entrée fournisseur gérée chez ShipBob. Le WRO, ou Warehouse Receiving Order, identifie cet arrivage. Le rapprochement doit ensuite retrouver le compte logistique, le document ERP, les articles et le lieu concernés. Une référence de commande fournisseur facilite l’enquête, mais ne dispense pas d’une correspondance vérifiée avec l’identifiant externe de réception.

Commencez par le besoin de l’acheteur. Doit-il confirmer des unités reçues, enregistrer un écart fournisseur ou suivre le rangement ? Ces actes peuvent être séparés dans l’installation ERP. Si un connecteur natif couvre déjà les documents, les quantités et les reprises attendus, vérifiez-le avant d’ajouter un second flux. Le middleware sur mesure se justifie par les règles ou les interfaces manquantes, pas par le seul accès possible à une API.

Délimiter les décisions que le connecteur ne prend pas

L’entrepôt qualifie les faits physiques. Les achats décident de la suite du solde fournisseur. L’installateur ERP confirme les méthodes accessibles et le sens des documents. Le connecteur transporte des observations et applique le contrat convenu. Il ne peut pas inventer les unités manquantes pour obtenir une réception visuellement complète, ni accepter un litige commercial parce qu’un statut technique est devenu terminal.

Notre exemple retient des pièces entières, sans lots ni numéros de série, et une comptabilisation finale des unités rangées. Ce choix rend la démonstration contrôlable ; ce n’est pas une règle universelle de réception ERP. Une organisation qui enregistre d’abord l’arrivée au quai puis un transfert interne doit garder ses deux mouvements, avec leurs preuves et leurs identités, au lieu de reprendre directement la politique de ce pilote.

Pourquoi « Completed » ne ferme pas nécessairement l’écart fournisseur

Une fermeture opérationnelle peut conserver des manquants

La documentation officielle Receiving décrit notamment une clôture automatique : les cartons restés en attente peuvent être annulés, tandis que le WRO passe à Completed. Il précise aussi qu’un événement wro.box.stowed peut se produire plusieurs fois pour un carton. Le connecteur doit donc relire les quantités et les cartons, plutôt que traduire ces signaux en « tout a été reçu ».

Paradoxalement, fermer l’arrivage peut rendre plus visible un solde fournisseur toujours ouvert. Dans notre fiction, trente unités annoncées appartiennent au carton annulé. L’achat peut encore réclamer une décision sur ces unités. La bonne restitution montre les deux faits : le traitement de cet arrivage est terminé, mais sa quantité rangée reste inférieure à l’annonce initiale. Un statut vert unique ferait disparaître l’information qui intéresse le plus l’acheteur.

Traiter l’événement comme un signal de relecture

Nous proposons de déclencher une collecte de l’état courant à partir de la notification authentifiée. Le calcul ne reprend pas aveuglément son contenu historique comme un nouvel apport de stock. Si un événement ancien arrive après une notification de fin, cette relecture permet de repartir du dossier observé, avec ses détails, plutôt que de reconstruire une chronologie supposée depuis l’ordre de livraison des messages.

Les pages consultées ne décrivent pas toutes wro.updated avec la même précision : la documentation Receiving le limite aux modifications du marchand avant arrivée, tandis que le tableau général des webhooks évoque aussi un changement de statut. Cette différence interdit d’en faire le seul détecteur de progression sans qualification. Une collecte périodique (polling) et les lectures explicites du WRO restent nécessaires dans le contrat d’intégration retenu.

Lire les quantités au bon niveau, sans additionner deux fois le détail

Le WRO porte les agrégats, les cartons expliquent leur composition

La référence Get Warehouse Receiving Order expose inventory_quantities, avec les quantités attendues, reçues et rangées par article. L’endpoint GET /2026-07/receiving/{id} porte cette lecture. Le détail n’est pas une collection de cartons imbriquée à deviner dans cette réponse. L’adaptateur doit suivre le contrat réellement documenté, et vérifier les champs utiles plutôt que recopier un exemple de parcours simplifié.

L’opération Get Warehouse Receiving Order Boxes fournit les cartons, leurs box_items et leurs quantités. Nous rapprochons leur somme des agrégats du WRO. Nous n’ajoutons jamais cette somme aux agrégats : ce sont deux vues du même arrivage. Une opération de contrôle deviendrait sinon une seconde source de mouvement.

Conserver l’absence d’une donnée et la portée de sa collecte

Un zéro observé, une quantité absente et un carton non collecté ne signifient pas la même chose. Notre politique refuse une quantité manquante et un détail incomplet avant toute écriture. Elle conserve le compte et le centre associés à la réception. L’identité du compte provient du contexte d’intégration autorisé ; elle ne doit pas être choisie à partir d’une valeur non vérifiée envoyée dans une notification.

Deux lectures successives ne constituent pas automatiquement une photographie atomique. Si l’agrégat et les cartons divergent, le connecteur peut observer un traitement en cours ou un problème de collecte. Il doit reprendre les lectures ou ouvrir une exception selon la situation, sans inventer la quantité qui les ferait correspondre. Notre exercice utilise des réponses figées cohérentes ; il ne démontre aucune garantie de cohérence instantanée de l’API réelle.

Exemple concret : trois cartons, 150 unités annoncées, 114 rangées

Établir le corrigé avant le calcul automatique

Le compte fictif A suit le WRO 777, au centre 10. Les identifiants 501 et 502 représentent deux articles en pièces. Le carton 11 est terminé avec 60 unités annoncées, 58 reçues et 56 rangées de l’article 501. Le carton 12 contient 40 unités de 501, toutes rangées, et 20 unités de 502, dont 19 reçues et 18 rangées. Le carton 13, annulé, en annonçait 30 de 501 ; aucune n’est reçue.

Le contrat fictif autorise donc un mouvement de 96 unités pour 501 et de 18 pour 502. L’écart entre attendu et rangé vaut 36 ; celui entre reçu et rangé vaut 3. Ces nombres répondent à deux questions différentes. Ils ne permettent pas de déclarer automatiquement que trois unités sont cassées : une cause de qualité, de rangement ou de correction doit venir d’une observation supplémentaire attribuée à l’entrepôt.

Refuser les quatre raccourcis qui produisent un résultat plausible

Le programme compare le résultat attendu à quatre méthodes incorrectes appliquées à la fixture. Prendre l’annonce initiale donne 150 unités. Prendre le reçu donne 117. Ajouter les quantités du WRO à celles des cartons donne 228. Réappliquer les 114 unités parce que le marqueur distant est encore faux donne aussi 228. Deux causes très différentes peuvent donc produire le même total erroné ; le chiffre seul ne suffit pas au diagnostic.

Une équipe qui ne teste qu’un arrivage complet pourrait ne jamais voir le premier défaut : attendu, reçu et rangé y seraient identiques. Ajoutez volontairement un carton annulé et une différence entre reçu et rangé. Ces témoins obligent l’adaptateur à utiliser la bonne donnée. Les identifiants des deux articles évitent aussi qu’un total global correct masque une quantité affectée au mauvais produit.

Le mouvement de réception n’est pas le stock actuellement vendable

Ne pas remplacer un solde par la quantité d’un arrivage

Supposons que le journal fictif possède déjà dix unités de 501 et cinq de 502, sans autre mouvement pendant notre essai. Ajouter la réception autorisée porte ces soldes à 106 et 23. Les remplacer par 96 et 18 effacerait leur état antérieur. Cette arithmétique illustre une distinction de contrat : enregistrer un mouvement et remplacer une projection ne sont pas la même opération, même si les deux utilisent un champ nommé quantité.

Dans une exploitation réelle, des commandes, réservations, corrections et transferts peuvent intervenir pendant la réception. Notre addition ne calcule pas le disponible commercial. Elle ne remplace ni la logique de réservation ERP ni une lecture actuelle du stock logistique. Avant toute publication vers un canal de vente, identifiez le système qui fait autorité, le périmètre de dépôt et les exclusions qui appartiennent à votre politique.

Utiliser une lecture de stock pour une question de stock courant

La référence Get All Inventory Levels répond aux questions de niveaux courants et distingue notamment les quantités présentes, engagées ou vendables. Sa réponse paginée possède des liens de continuation. Elle ne se confond pas avec les quantités d’un WRO particulier. Choisissez donc l’opération en fonction de la question posée, avant de choisir le champ à afficher.

Un contrôle utile rapproche le mouvement de réception attendu et l’historique qui explique le solde, dans un périmètre comparable. Si la comparaison porte sur des horaires ou des lieux différents, l’écart peut être normal. Documentez cette différence avant d’imposer une correction. Forcer une égalité entre « reçu sur ce WRO » et « disponible maintenant » ferait revenir la divergence à la prochaine réservation.

Enregistrer une réception logique avant de confirmer sa synchronisation

Identifier le fait métier au-delà du numéro de notification

Le contrat des webhooks ShipBob décrit un identifiant de message conservé lors d’un renvoi. Cette identité aide à traiter la livraison technique. Notre politique ajoute une identité métier composée du compte et du WRO, car plusieurs événements différents peuvent mener à la même réception finale. Dédupliquer chaque message ne garantit pas, à lui seul, l’unicité du mouvement ERP.

Le journal local conserve l’empreinte normalisée des quantités et du détail ayant justifié l’effet. Le même WRO avec le même contenu est reconnu comme déjà appliqué. Le même WRO avec un contenu différent ouvre une correction à qualifier. Le connecteur ne doit ni appliquer silencieusement le total une seconde fois, ni ignorer une variation sous prétexte que l’identifiant de réception existe déjà.

Rendre indivisibles la preuve locale et les mouvements locaux

Dans le banc, l’entrée est une paire de réponses fictives qualifiée ; la sortie est un journal de réception, deux lignes de mouvement et une intention de marquage distant. Ces trois écritures partagent une transaction SQLite. La responsabilité du traitement est de valider tout l’ensemble ou de ne rien conserver. Une coupure avant validation laisse zéro mouvement ; une coupure après validation conserve la preuve qui permet la reprise sans ajout.

Cette atomicité est locale. Elle ne relie pas magiquement une base middleware à un ERP distant. Pour le projet réel, le contrat d’écriture ERP doit offrir une référence retrouvable et une stratégie d’idempotence ou de rapprochement adaptée. L’installateur confirme les dépendances, la journalisation et le repli. Si le résultat d’un appel reste inconnu, le retry doit rechercher l’effet précédent avant de demander une nouvelle réception.

ExternalSync : une étape de suivi, pas une transaction distribuée

Marquer seulement les dossiers dont l’effet est confirmé

L’opération Set ExternalSync flag for Wros accepte une liste d’identifiants et un booléen. Le marqueur permet au processus externe de signaler sa synchronisation. Son changement n’apporte pas une preuve indépendante du document ERP : cette preuve doit déjà être connue du connecteur. Limitez chaque demande aux dossiers dont l’effet a été confirmé selon votre contrat.

{
  "ids": [777],
  "is_external_sync": true
}

Ce corps utilise l’identifiant fictif de notre scénario ; aucun appel n’est exécuté par le programme. Si la réponse au marquage manque, le suivi local reste « à confirmer ». Le mouvement reste acquis dans notre journal. Une nouvelle collecte peut présenter encore la réception : le connecteur retrouve alors l’effet antérieur et poursuit le suivi du marquage, sans recréer les unités pour obtenir un nouveau cycle technique réussi.

Rechercher les dossiers oubliés sans confondre absence et réussite

La référence Get Multiple Warehouse Receiving Orders fournit les filtres nécessaires à la collecte, dont le statut et la synchronisation externe. La documentation Receiving illustre la recherche Statuses=Completed&ExternalSync=false. Le processus doit suivre la pagination du contrat choisi et conserver les échecs de lecture. Une réponse interrompue par un timeout garde la collecte ouverte : elle ne peut pas être remplacée par une liste vide. Seul le parcours complet des pages permet de conclure sur les réceptions à reprendre.

Un marqueur déjà vrai sans preuve locale pose une autre question : un ancien connecteur, une autre application ou une intervention a-t-il déjà traité ce WRO ? Le pilote refuse de créer un mouvement dans cette situation inconnue. La reprise demande l’historique et la correspondance ERP. Réinitialiser le marqueur pour faire réapparaître tous les dossiers pourrait rejouer des réceptions légitimes ; cette opération doit donc suivre une migration qualifiée.

Reproduire les 77 contrôles de réception et de reprise

Exécuter un laboratoire sans compte ShipBob

Le programme Python et SQLite de la réception fictive fonctionne avec la bibliothèque standard. Il crée uniquement des bases en mémoire. Les champs de son enveloppe locale, tels que account et boxes_complete, expriment des conditions du collecteur ; ils ne prétendent pas appartenir à un webhook ShipBob. Les réponses quantitatives reprennent les noms de champs des deux opérations de lecture.

python3 reception_shipbob.py
# Résultat attendu : status PASS, checks 77
# Réception : article 501 = 96 ; article 502 = 18

Le corrigé est fixé indépendamment à 96 et 18. Six ordres de notifications déclenchent chacun la lecture du même état final ; ils ne trient pas des payloads historiques pour inventer un ordre serveur. Six permutations des cartons et l’inversion des lignes conservent la même empreinte. Les essais vérifient également que deux comptes autorisés utilisant le même numéro de WRO gardent des journaux séparés.

Observer les coupures, les contradictions et les limites

Deux interruptions distinguent avant et après la validation SQL. Quinze entrées sont refusées, notamment une quantité absente, un mauvais compte, un carton répété, un détail incomplet ou un marqueur distant vrai sans journal local. Après chaque refus, le programme contrôle l’absence de mouvement et d’intention de marquage. Une correction cohérente des quantités, reçue après application, est également arrêtée pour décision plutôt que confondue avec un simple renvoi.

Le banc ne valide ni la signature des webhooks, ni l’API ShipBob, ni la concurrence entre deux workers, ni une écriture ERP réelle. Il simule aussi la réception ou la perte de l’accusé distant. Ses règles de refus sur les lots, les états ou les unités sont le périmètre conservateur de cette démonstration. Elles doivent être adaptées et éprouvées avant de les attribuer à une installation de production.

Erreurs fréquentes : masquer un problème en fermant le dossier

Une collecte incomplète peut ressembler à un carton annulé

Ne déduisez pas l’annulation d’un carton de son absence dans une réponse collectée. Notre carton 13 possède un état explicitement fourni. Si sa ligne disparaît de la fixture, les agrégats ne correspondent plus et le calcul est refusé. Ce contre-exemple protège contre un adaptateur qui transformerait une erreur de lecture en fait physique. La cause doit être retrouvée avant de fermer le dossier d’achat.

Un autre signal faible est un écart qui n’apparaît que lors d’un changement de connecteur. Les réceptions anciennes peuvent avoir été appliquées sans journal dans le nouveau système. Préparez une reprise de l’historique vérifiable et une frontière de bascule. Un marqueur distant ne porte pas toutes les décisions de l’ancien adaptateur ; sa valeur ne remplace pas le rapprochement des documents réellement créés.

Mesurer le coût de l’enquête sans annoncer une économie fictive

Pour une hypothèse de douze écarts demandant chacun quinze minutes de qualification, la charge représente 180 minutes, soit trois heures. Il s’agit d’un calcul illustratif, pas d’un gain client observé. Le coût réel inclut la recherche de réception, la confirmation auprès de l’entrepôt, la comparaison ERP et la décision fournisseur. Un dossier techniquement fermé mais commercialement contesté continue de consommer ce temps.

Le seuil d’alerte du pilote peut être toute différence inexpliquée entre agrégat et détail, ainsi que toute réception appliquée dont le marquage reste incertain au-delà du délai convenu. Ces deux alertes demandent des réponses différentes. La première bloque le calcul ; la seconde reprend une confirmation. Les réunir dans une file de « réceptions à refaire » encouragerait précisément le second mouvement que l’on cherche à éviter.

Plan d’action : ouvrir une réception traçable avant d’étendre le flux

Qualifier les quantités avec le logisticien et l’équipe ERP

Choisissez un compte ShipBob, un centre et une famille de produits dont l’unité est connue. Reconstituez un arrivage complet et un arrivage comportant un écart, avec les identifiants de WRO et les documents ERP correspondants. L’exploitation explique les quantités physiques ; les achats indiquent le traitement du solde ; l’installateur décrit l’écriture autorisée. Le livrable est une table de correspondance entre faits observés et actes ERP, pas seulement une liste d’URL accessibles.

Préparez ensuite la collecte en lecture seule. Vérifiez les champs des réponses WRO et cartons, la pagination des listes utilisées et le contexte du compte. Comparez les agrégats sans produire de mouvement. Enregistrez les différences et leurs causes, puis distinguez une donnée absente d’un zéro valide. Si les réponses ne permettent pas d’attribuer une quantité au bon article, à la bonne unité et au bon lieu, la décision d’écriture reste suspendue sur ce périmètre.

Éprouver l’effet ERP et la confirmation distante séparément

Dans l’environnement de recette convenu, appliquez une réception partielle selon le contrat installé et retrouvez son document. Provoquez un accusé perdu après l’effet, puis vérifiez que la reprise retrouve ce document sans le créer de nouveau. Testez séparément la confirmation ExternalSync et sa réponse manquante. Les preuves doivent couvrir les méthodes réellement utilisées ; la transaction SQLite de la démonstration ne peut pas servir de preuve d’atomicité entre votre ERP et le logisticien.

Ouvrez enfin un pilote dont le support peut arrêter les écritures sans perdre les observations entrantes. Fixez un seuil de délai pour les confirmations à reprendre et un responsable pour les écarts physiques. Faites traiter une réception déjà synchronisée mais absente du journal local, puis une correction après application. L’extension à d’autres centres attend une reprise expliquée, une collecte complète et des mouvements attribuables. Les lots, les séries et les réceptions progressives entrent ensuite dans des recettes propres, avec leurs règles de correspondance.

• Si l’agrégat et les cartons ne concordent pas, alors reprendre la collecte avant l’écriture.
• Si le mouvement ERP est confirmé mais pas le marqueur, alors reprendre la confirmation plutôt que la réception.
• Si le même WRO change après application, alors ouvrir un parcours de correction attribué.

Lectures complémentaires : adapter la preuve au système raccordé

Préserver le processus propre à votre ERP

Le dossier Odoo et 3PL : reprendre les réceptions partielles examine les unités, les lots, le reliquat et les étapes de réception. Il complète le contrat ShipBob en montrant les décisions qui appartiennent à l’installation ERP. Une réception finale côté logisticien ne suffit pas à choisir automatiquement les options de validation Odoo.

Pour EBP, le parcours connexion d’EBP à un WMS distingue les interfaces et les documents accessibles. Ne transposez pas les méthodes d’un ERP vers l’autre à partir d’un simple tableau de quantités. Le rapprochement peut rester commun dans son principe, alors que la création et la confirmation du document demandent un adaptateur différent.

Contrôler les frontières de lecture et les identités logistiques

Lorsque le prestataire transmet aussi des fichiers, le diagnostic CSV 3PL et colonnes quantité dupliquées montre comment une lecture apparemment réussie perd une valeur. Le résultat attendu doit être vérifié dès l’import, avant que le rapprochement n’utilise une donnée déjà altérée par le parseur.

Le dossier Amazon MCF : nouveau suivi, même colis traite une autre frontière : une référence de suivi qui évolue sans nouvelle expédition. Il complète le même besoin d’identité stable dans le middleware, tout en conservant les contrats propres à Amazon et ShipBob. Un identifiant qui change ne constitue pas à lui seul un nouvel effet métier.

Conclusion : une réception terminée doit rester explicable et rejouable

Le statut Completed ne remplace ni les quantités du WRO ni l’explication des cartons. Dans la fiction, 150 unités attendues conduisent à 117 reçues et 114 rangées. Le mouvement autorisé dépend du contrat ERP choisi. Le calcul ne doit additionner ni deux représentations du même arrivage, ni deux livraisons techniques de la même réception logique.

La reprise s’appuie ensuite sur une preuve durable de l’effet. Une confirmation distante manquante laisse une action de suivi, sans effacer le mouvement déjà obtenu. Les 77 contrôles rendent ces différences observables sur SQLite ; la qualification finale reste à mener sur les interfaces, les droits et les opérations réellement utilisés par votre organisation.

Un raccordement WMS, OMS et stock fondé sur des réceptions rapprochées donne au support les éléments pour retrouver l’arrivage, expliquer l’écart et reprendre la bonne étape avec le logisticien et l’équipe ERP.

Dawap accompagne vos projets d’intégration API et de middleware sur mesure pour construire ces correspondances, les éprouver sur un pilote et transmettre une exploitation où chaque unité ajoutée possède une origine vérifiable.