Dans un cas fictif, une commande contient un tee-shirt configurable et un sac simple. Le connecteur retrouve les deux références dans l’ERP, puis prépare la facturation Adobe Commerce avec leurs identifiants de lignes. Le sac apparaît sur la facture ; le tee-shirt manque, alors que sa variante avait bien été sélectionnée. Le symptôme ressemble à une perte de ligne pendant le transport, mais le connecteur a choisi l’identifiant enfant pour une opération qui attend celui du parent.
En pratique, identifier la référence vendue et identifier la ligne à facturer sont deux décisions différentes. Adobe documente ce cas pour les produits configurables : la demande de facture doit utiliser l’identifiant de ligne du parent concerné. Le middleware doit conserver la relation avec l’enfant vendu, plutôt que de remplacer partout le SKU ou l’identifiant par une seule valeur supposée universelle.
Pour un projet d’intégration API, cette distinction touche l’import ERP, la préparation et le rapprochement des documents. Dawap accompagne les raccordements Magento et Adobe Commerce vers les logiciels métier en qualifiant ces identités et les règles propres à chaque opération dans la version installée.
Pour qui : des variantes vendues qui manquent dans la facture API
Reconnaître une sélection incorrecte dans une commande mixte
Le diagnostic intéresse les équipes dont l’ERP ou le middleware prépare une facture Commerce à partir des lignes commandées. Une commande mixant simples et configurables fournit un bon témoin : les premières lignes peuvent fonctionner tandis que les secondes disparaissent du document attendu. Un succès sur le sac simple ne prouve donc pas que le mapping du tee-shirt est correct.
La base de connaissances Adobe signale aussi une absence de message d’erreur lorsque seuls les identifiants enfants sont utilisés dans le cas décrit. Le contrôle doit relire les lignes du document obtenu, pas seulement son existence ou le retour du client HTTP. Comptez les lignes métier effectivement rapprochées et les dossiers qui demandent une correction manuelle.
Distinguer les décisions du commerce, de la logistique et de la facturation
Le WMS a besoin de connaître la référence physique préparée. La demande de facture doit désigner la ligne source appropriée pour cette opération. Le service client veut retrouver le choix de taille et de couleur. Ces besoins peuvent partager une même vente tout en utilisant des identifiants différents ; la correspondance doit les relier explicitement.
Une ligne correctement identifiée n’est pas automatiquement facturable. Paiement, annulation, factures existantes et extensions peuvent conditionner l’opération. Le banc présenté plus loin prépare uniquement une sélection à recetter. Les décisions de facturation et de capture restent à vérifier dans le parcours réellement déployé et avec les personnes qui en possèdent les règles.
Anatomie d’une vente configurable : deux lignes liées, un choix vendu
Lire parent_item_id comme une relation entre lignes de commande
La documentation de la table sales_order_item décrit deux enregistrements lorsqu’un configurable est acheté : le parent configurable et l’enfant simple. La propriété parent_item_id de l’enfant pointe vers item_id du parent. Il s’agit d’une relation dans la commande, distincte de la relation entre deux produits du catalogue.
Conservez les deux enregistrements dans votre lecture de diagnostic. Un export filtré peut avoir supprimé le parent ou sa relation avant la réception. Le validateur contrôle le graphe fourni ; il ne prouve pas que l’adaptateur a transmis toutes les lignes et propriétés de la commande. Cette complétude doit faire partie de la recette. Éliminer les enfants dès l’import peut faire perdre la référence physique utile à l’ERP. Éliminer les parents peut retirer l’identité nécessaire à la demande de facture. La projection métier peut afficher une seule ligne, à condition de préserver les références sources qui expliquent sa construction.
Ne pas confondre product_id et item_id
La propriété product_id désigne le produit du catalogue ; item_id identifie l’enregistrement de ligne commandée. Un même produit configurable peut intervenir dans plusieurs choix de vente. Le connecteur doit donc travailler à partir de la commande et de ses relations, au lieu de reconstruire une ligne à partir du catalogue courant et du premier SKU correspondant.
Exemple concret fictif : le produit catalogue 80 intervient sur les parents 501 et 511 d’une même commande fictive 7000. Les enfants 502 et 512 décrivent respectivement les variantes M et L. Choisir le nombre 80 comme identifiant de ligne est refusé. Ce cas pédagogique ne constitue pas une trace de boutique ; il rend visibles les identités que le mapping doit différencier.
Utiliser le parent concerné dans les items de la demande de facture
Appliquer le cas documenté sans le généraliser aux autres types
La résolution Adobe indique d’envoyer, pour le configurable, l’identifiant de ligne du parent dans order_item_id, avec une quantité positive. Elle exclut l’identifiant enfant dans cette sélection. Pour un simple autonome, la ligne conserve sa propre identité. Une demande partielle doit donc classer les lignes au lieu de leur appliquer indistinctement la même transformation.
Cette règle ne définit pas tous les comportements d’un bundle, d’un produit virtuel ou d’une extension commerciale. Le validateur local refuse les types hors de son périmètre. Ce refus explicite évite de faire passer un type inconnu par la branche « simple » uniquement parce que sa structure JSON contient un SKU et une quantité.
Séparer ligne de facture et ligne d’origine de la commande
Lorsqu’on relit une facture, ses identifiants de document et de lignes appartiennent au document créé. Le tutoriel REST Adobe expose aussi order_item_id pour la filiation avec la commande. Ne remplacez pas cette propriété par entity_id, ni par un parent_id de facture dont le sens est différent.
Les exemples de réponse peuvent contenir plusieurs représentations des produits. Leur présence ne transforme pas chaque ligne de réponse en entrée admissible pour une nouvelle demande de facture. Le contrat de création et le contrat de lecture doivent être vérifiés séparément. Copier les identifiants trouvés dans un document existant ne suffit pas à préparer une autre opération correcte.
Retrouver le bon parent lorsque plusieurs variantes partagent le même modèle
Suivre la relation de la variante réellement sélectionnée
Si la facture partielle concerne la taille L de la fixture, la sélection de l’enfant 512 rejoint le parent 511. Elle ne rejoint pas le premier configurable de la commande, le parent 501. La base de connaissances Adobe précise ce point pour une commande comportant plusieurs variations : chaque variation concernée doit conserver son parent de ligne approprié.
Le mapping ERP peut garder ensemble installation source, commande, ligne enfant, ligne parent et référence métier. Le numéro de produit configurable ne suffit pas à remplacer cette filiation. Lorsque le commercial ou l’entrepôt désigne une ligne précise, le middleware doit pouvoir expliquer comment ce choix rejoint l’identifiant utilisé dans la sélection financière.
Refuser un rapprochement reposant seulement sur le SKU
Dans la fixture, parent et enfant portent le même libellé SKU pour illustrer une ambiguïté possible entre représentations. Une recherche globale par cette seule chaîne retourne plusieurs lignes et s’arrête. Le résultat doit être choisi avec la relation et l’identité de ligne attendues, sans trier les identifiants pour prendre arbitrairement le plus petit.
Le catalogue peut également avoir évolué depuis la vente. Une référence retirée, renommée ou remplacée ne permet pas de reconstruire le choix historique avec certitude. La commande source et sa correspondance ERP restent les pièces du rapprochement. Une réparation de référentiel doit conserver cette origine au lieu de substituer silencieusement la variante actuellement vendable.
Préparer une facture partielle sans compter deux fois parent et enfant
Construire une seule cible par décision de facturation
Une interface peut présenter les deux représentations et laisser remonter deux sélections qui rejoignent le même parent. Le banc refuse ce cas au lieu d’additionner leurs quantités. Le seuil d’arrêt est la première cible sélectionnée deux fois, même si la quantité totale semblerait encore admissible. Dédupliquer après addition serait trop tard : on aurait déjà transformé une sélection dupliquée en une demande portant sur deux unités.
Dans ce scénario fictif, pour le choix taille L et deux sacs, le fragment candidat suivant utilise les lignes 511 et 601. Il montre uniquement les items à recetter. Il ne fournit ni un client d’appel, ni une autorisation de facture, ni une consigne de capture de paiement. Aucun envoi vers Adobe Commerce n’est exécuté par l’exercice.
{
"items": [
{"order_item_id": 511, "qty": 1},
{"order_item_id": 601, "qty": 2}
]
}Qualifier les quantités disponibles auprès du parcours natif
Le programme reçoit des capacités fictives fournies séparément des lignes. Il ne calcule pas une éligibilité Adobe Commerce en soustrayant quelques compteurs. Dans votre installation, retrouvez les quantités encore admissibles avec le parcours natif et les règles de vos extensions. Une ancienne lecture peut être dépassée si une autre facture ou une annulation intervient entre-temps.
La politique locale accepte seulement des pièces entières positives. Elle refuse zéro, booléen, texte et quantité fractionnaire ; elle ne prétend pas définir toutes les quantités autorisées par Commerce. Un projet vendant des mesures ou utilisant d’autres conventions doit qualifier son propre contrat, puis ajouter les tests de frontière correspondants.
Conserver une filiation utile à l’ERP après création du document
Relier les preuves sans effacer la variante physique
Le registre de correspondance rapproche la ligne ERP et les identités Commerce retenues pour la vente et pour la facture. L’ERP peut afficher la variante physique, tandis que la référence d’opération conserve le parent utilisé. Cette dualité est normale dès lors qu’elle est explicable ; forcer toutes les colonnes à porter le même identifiant fait perdre de l’information.
Après la création autorisée d’un document dans votre environnement de recette, relisez ses lignes et rapprochez chacune de la sélection initiale. Une facture créée ne prouve pas que toutes les variantes souhaitées y figurent. La sortie attendue doit montrer document, ligne source, quantité retenue et correspondance ERP, sans produire un second import pour compléter un journal mal renseigné.
Préserver installation et commande dans les clés de suivi
Deux installations peuvent utiliser le même numéro interne de commande. La clé d’une opération ne doit donc pas se limiter à ce nombre, ni au SKU, ni au numéro visible par le client. Le banc inclut installation source et commande dans l’empreinte de sa sélection. Cette empreinte est un outil local de comparaison et ne constitue pas un mécanisme natif d’idempotence Adobe.
Le contrat d’échange doit également décider quel système crée la facture et lequel reçoit son résultat. Une facture ERP et un document Commerce ne deviennent pas la même pièce par simple égalité de montant. Préservez les autorités, les références et la journalisation nécessaires au rapprochement entre les deux systèmes, avec un responsable désigné pour les désaccords.
Traiter une réponse perdue sans créer une seconde facture
Relire le résultat avant de préparer un nouvel effet
Un timeout après émission laisse le résultat incertain. Le retry ne doit pas créer une nouvelle intention financière à partir des lignes encore affichées dans un ancien snapshot. Le runbook conserve le contexte envoyé et recherche le document éventuellement produit. La queue distingue une sélection refusée avant envoi d’un résultat distant qui reste à rapprocher.
Une notification ou un webhook peut signaler une évolution à relire ; il ne remplace pas la vérification du document et de ses lignes. L’observabilité doit relier la tentative, les identifiants demandés et les références constatées. Le repli suspend la nouvelle émission du dossier incertain, avec une sortie claire pour l’équipe chargée du rapprochement.
Tester le SDK et les chemins de batch réellement utilisés
Le client REST ou le SDK peut renommer, filtrer ou aplatir les objets lus. Vérifiez que le payload préparé conserve order_item_id et sa quantité sans remplacer l’identifiant par un code produit. La recette doit couvrir le batch planifié autant que l’écran manuel : corriger un seul adaptateur laisse l’autre chemin exposé à la même omission.
Le monitoring sépare lignes sélectionnées, cibles préparées, documents retrouvés et lignes rapprochées. Une synchronisation réussie de la commande vers l’ERP peut coexister avec une facture Commerce incomplète. Ces deux mesures ne doivent pas partager le même statut « terminé » si elles autorisent des décisions commerciales différentes.
Exercice local : 33 contrôles de filiation et de sélection
Exécuter le validateur sur une commande fictive
Téléchargez le banc de sélection des lignes configurables, puis exécutez-le avec Python 3.10 ou supérieur. Les données sont définies dans le fichier et la bibliothèque standard suffit. Le programme ne possède aucun token, ne charge aucune commande client et n’appelle aucune API Commerce ou ERP.
python3 order_lineage_inventory.py
PASS sold child resolves to its invoice parent
PASS second variant retains its own parent
PASS duplicate parent-child effect refused rather than summed
PASS candidate fingerprint separates source installations
CHECKS 33
Adobe Commerce requests: 0; invoices created: 0; payment captures: 0; ERP writes: 0.Le cas nominal sélectionne l’enfant L et le sac autonome. Les cibles préparées sont le parent de L et la ligne du sac. Les essais supplémentaires refusent notamment identifiant catalogue à la place d’une ligne, parent absent, relation sur une autre commande, type bundle non qualifié et double sélection parent-enfant. Chaque refus laisse la source inchangée.
Interpréter correctement l’empreinte de la candidate
Le programme trie les items avant de calculer leur empreinte : inverser l’ordre du tableau ne transforme pas la même sélection en opération différente. Changer commande, installation ou quantité modifie cette empreinte. Cela permet de comparer des candidates locales ; cela ne démontre ni la persistance d’un journal distribué ni une protection du serveur contre deux factures.
Le graphe pédagogique exige exactement un enfant vendu par ligne configurable. Une extension produisant une autre structure demande une nouvelle qualification. Le banc refuse ces structures au lieu de deviner leur sens. Il ne valide pas non plus taxes, remises, devise, capture, permissions ou disponibilité native : ces preuves appartiennent à la recette du parcours réel.
| Entrée fictive | Décision locale | Preuve à conserver |
|---|---|---|
| Enfant L | Parent L retenu | Lien 512 vers 511 |
| Simple seul | Ligne conservée | Identité 601 |
| Parent et enfant | Doublon refusé | Sélection d’origine |
| Produit catalogue | ID refusé | Ligne commandée |
| Autre commande | Graphe refusé | Snapshot complet |
Erreurs fréquentes : résoudre la facture en détruisant une autre correspondance
Remplacer partout l’enfant par le parent
Paradoxalement, une correction de facturation peut casser la préparation si elle remplace aussi la référence physique de l’ERP par celle du modèle configurable. Appliquez la transformation à l’opération qui en a besoin et gardez la filiation complète. L’enfant vendu reste utile même lorsque le parent porte la sélection de facture.
Le diagnostic des commandes WooCommerce absentes d’un export ERP traite une autre cause de représentation incomplète : le lecteur utilise une ancienne copie. Il aide à séparer identité métier et chemin technique, sans transposer les règles de stockage WooCommerce à Commerce.
Déclarer le rapprochement terminé dès qu’un objet est retourné
Un identifiant de document ne certifie pas le contenu attendu. Relisez les quantités et les liens de chaque variante sélectionnée. Ne réparez pas une omission en émettant immédiatement une autre facture : le premier résultat doit être compris et rapproché avant de déterminer ce qui reste réellement à traiter.
La lecture d’un remboursement BigCommerce rattaché à une autre commande montre un autre cas où une réponse reçue ne suffit pas à valider l’association attendue. Le contrôle commun est le rapprochement des identités ; les règles natives de remboursement et de facturation restent propres à chaque fournisseur.
Plan d’action : prouver une facture partielle avant d’élargir le raccordement
Rassembler la commande, la sélection et le document obtenu
Choisissez en recette une commande mixte avec deux variantes configurables et un simple autonome. Faites confirmer par le métier la variante et la quantité à traiter. Les entrées du diagnostic comprennent installation, commande, snapshot des lignes et sélection attendue ; sa sortie rapproche les cibles avec le document réellement obtenu. La responsabilité du mapping et celle de l’autorisation financière doivent être explicites.
Conservez les identifiants parent-enfant avant toute modification du connecteur. Comparez ensuite le payload actuellement émis et les lignes du document retrouvé. Si la relation manque dans votre export, corrigez d’abord cette dépendance : déduire le parent depuis le catalogue actuel fournirait une preuve différente de la ligne source de la vente.
Éprouver les refus et organiser la reprise des dossiers existants
La recette vérifie une sélection d’enfant, une sélection explicite de parent, un simple autonome et une facture partielle limitée à la seconde variante. Ajoutez parent introuvable, quantité nulle, double sélection et réponse perdue. Le seuil de validation est l’accord entre les lignes attendues et celles effectivement rapprochées, avec une absence de nouvelle émission pour le dossier incertain.
Pour l’historique, classez séparément documents absents, documents incomplets et résultats non rapprochés. Leur résolution dépend des effets déjà produits. Le responsable de la reprise conserve la journalisation et l’arbitrage de chaque dossier. Le correctif technique empêche une nouvelle mauvaise sélection ; il ne résout pas à lui seul les écarts commerciaux déjà présents.
- D’abord vérifier la complétude des lignes et leur filiation dans la commande source.
- Ensuite préparer une cible unique pour chaque variante choisie et refuser le doublon parent-enfant.
- Puis relire les lignes du document créé dans le parcours de recette autorisé.
- À bloquer : une nouvelle émission tant que le résultat de la première reste incertain.
Sources Adobe et limites de la démonstration
Vérifier les contrats de ligne, de création et de lecture
Consultées le 15 octobre 2026 : la résolution de l’omission des configurables dans une facture REST, mise à jour le 18 août 2026, et la description de sales_order_item, mise à jour le 8 octobre 2026. La première décrit le choix du parent ; la seconde explique la relation entre lignes.
Le tutoriel de création et de lecture d’une facture expose les objets du document. L’interface OrderItem du tag 2.4.8 complète la vérification des identités de ligne. Aucun de ces liens ne prouve que vos extensions ont conservé le comportement décrit.
Séparer résultat local et validation du parcours client
Les trente-trois contrôles exécutés portent sur une commande et des capacités fictives. Aucune facture, capture de paiement ou écriture ERP n’a été créée. La preuve native doit encore porter sur l’environnement autorisé, son état réel et les droits du connecteur. Le fragment items ne constitue pas une intégration de facturation prête à déployer.
Mesurez ensuite les variantes sélectionnées mais non rapprochées, les dossiers incertains et le temps de recherche entre Commerce et ERP. Ces indicateurs donnent une visibilité sur la charge support et les documents bloqués. Ils permettent de vérifier la résolution de l’omission initiale, au-delà du nombre de demandes HTTP exécutées sans exception.
Conclusion : conserver la variante vendue et sélectionner la bonne ligne à facturer
Un produit configurable impose de relier plusieurs identités sans les confondre. Pour le cas de facturation documenté par Adobe, retrouvez le parent de la variante concernée et préparez la sélection avec son identifiant de ligne. Préservez en parallèle l’enfant vendu, la commande et la correspondance ERP nécessaires à l’explication de la vente.
Le banc local vérifie cette filiation et refuse les sélections ambiguës. L’accompagnement Magento et Adobe Commerce vers ERP permet de confronter ensuite ces décisions au parcours natif, aux quantités admissibles et aux documents effectivement produits dans votre installation.
Dawap peut reprendre le mapping des lignes, adapter le middleware et bâtir la recette des factures partielles avec votre équipe et votre intégrateur ERP. Notre accompagnement en intégration API relie le correctif aux dossiers à rapprocher, à la procédure de réponse perdue et aux preuves que le support doit retrouver après déploiement.
