Le rapprochement mensuel signale douze écarts, dont trois critiques : une commande présente dans le canal mais absente de votre système, et deux stocks différant d’une pièce. Reprendre simplement le chiffre du canal supprime l’écart et garde la cause.
Le contrat fait donc de la résolution une décision propre à chaque écart : retenir la source, retenir la cible ou accepter expressément la différence — avec motif et acteur imputé. La résolution n’est prouvée que lorsqu’un nouveau rapprochement ne trouve plus d’écart critique.
| Surface | Rôles |
|---|---|
| Commerce | Commerce de pièces, Éditeur de logiciels, Plateforme et marketplace |
Ce que ce cas suppose
- Un rapprochement achevé. La décision porte sur un écart avec
discrepancyIdau sein d’un rapprochement. - Une personne habilitée. Retenir source ou cible modifie des données ; tout le monde ne devrait pas pouvoir le faire.
- Des motifs compréhensibles par autrui.
reasonCodeest votre propre code ; un catalogue interne le rend lisible. - La volonté de chercher la cause. Journal et flux d’événements sont consultables ; le contrat ne décrit aucun lien entre leurs entrées et un écart.
Le déroulement
Le tableau indique pour chaque étape l’appel compétent et ce qui existe ensuite. La justification de l’étape figure en dessous.
| Étape | Appel | Ce qui existe ensuite |
|---|---|---|
| Lire le rapprochement | GET /commerce/v1/reconciliations/{reconciliationId} | discrepancies avec kind, severity et resourceId ; et criticalRemaining |
| Décider | POST /commerce/v1/reconciliations/{reconciliationId}/discrepancies/{discrepancyId}/resolution | apply_source, apply_target ou accept_difference, chacun avec reasonCode |
| Retracer le stock | GET /commerce/v1/inventory/ledger | entryType, quantityDelta et balance par écriture |
| Relire les événements | GET /commerce/v1/events | événements avec streamId, sequence et correlationId |
| Rapprocher de nouveau | POST /commerce/v1/reconciliations | la même période avec de nouveaux points de contrôle — criticalRemaining est le chiffre qui compte |
Pourquoi chaque étape est nécessaire
- Lire le rapprochement.
GET /commerce/v1/reconciliations/{reconciliationId}renvoiecountsavecmatched,discrepantetcriticalRemaining,integrityavec les sommes de contrôle des deux côtés etdiscrepanciesaveckind,resourceId,severityetstate. Les critiques d’abord :severitydistinguewarningetcritical; le contrat ne décrit pas l’effet d’un écart critique. - Décider.
POST /commerce/v1/reconciliations/{reconciliationId}/discrepancies/{discrepancyId}/resolutionprenddecisionavecapply_source,apply_targetouaccept_difference, ainsi quereasonCodeetexpectedRevision. La réponse indiqueresultingStateetdecisionActorReference— la décision est imputée à un acteur. - Retracer le stock.
GET /commerce/v1/inventory/ledgermontre par écritureentryType,quantityDeltaetbalance. Chaque écriture portestockItemId; le contrat ne décrit aucun lien avec un écart. - Relire les événements.
GET /commerce/v1/eventsrenvoie les événements avecstreamId,sequenceetcorrelationId. Ils portent aussitype,resourceIdetoccurredAt; le contrat ne décrit pas ce que signifie un trou danssequence. - Rapprocher de nouveau.
POST /commerce/v1/reconciliationscontrôle la même période avec de nouveaux points de contrôle. La résolution est prouvée quandcriticalRemainingest à zéro ; le reste est une affirmation.
curl -X POST \
-H 'X-Api-Key: <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: abweichung-2026-08-0003' \
-d '{"decision":"apply_source","reasonCode":"<reasonCode>","note":"Buchung im Kanal war korrekt, Zustellung fehlte.","expectedRevision":"<revision>"}' \
'https://commerce-preview.invalid/commerce/v1/reconciliations/<reconciliationId>/discrepancies/<discrepancyId>/resolution'Ce que l’on obtient
Au final, chaque écart est tranché, motivé et imputé à un acteur, le journal et le flux d’événements ont été relus, et un nouveau rapprochement prouve qu’aucun point critique n’est ouvert.
Où cela figure dans la documentation
Les listes de champs contractuelles, les codes d’erreur et les réponses d’exemple se trouvent dans le contrat OpenAPI de cette surface, à l’adresse docs.tapinomahub.com (tapinoma-commerce). Tous les cas d’usage classés par surface et par rôle : aperçu des cas d’usage.
Sources et références juridiques
Questions fréquentes
Quelle différence entre apply_source et apply_target ?
Avec apply_source, l’état de la source s’applique ; avec apply_target, celui de la cible. Les points de contrôle du rapprochement fixent quel côté est source ou cible.
Puis-je simplement accepter un écart ?
Oui, avec accept_difference — mais toujours avec un motif. La décision porte une decisionActorReference et reste traçable ensuite.
Quand la résolution est-elle achevée ?
Quand un nouveau rapprochement sur la même période ne trouve plus d’écart critique, c’est-à-dire quand criticalRemaining vaut zéro.