Eine Abweichung aus dem Abgleich klären und belegen

Der monatliche Abgleich meldet zwölf Abweichungen, drei davon kritisch: ein Auftrag, der im Kanal existiert und im eigenen System nicht, und zwei Bestände, die sich um ein Stück unterscheiden. Wer jetzt einfach die Kanalzahl übernimmt, hat die Abweichung beseitigt und die Ursache behalten.

Der Vertrag macht die Klärung deshalb zu einer eigenen Entscheidung je Abweichung: Quelle übernehmen, Ziel übernehmen oder den Unterschied ausdrücklich akzeptieren — jeweils mit Grund und zugeordnetem Akteur. Belegt ist die Klärung erst, wenn ein neuer Abgleich keine kritische Abweichung mehr findet.

Was dieser Fall voraussetzt

• Ein abgeschlossener Abgleich. Die Entscheidung bezieht sich auf eine Abweichung mit discrepancyId innerhalb eines Abgleichs.
• Eine Person mit Befugnis. Wer Quelle oder Ziel übernimmt, verändert Daten; das sollte nicht jeder dürfen.
• Begründungen, die jemand anderes versteht. reasonCode ist ein eigener Code; ein betrieblicher Katalog hält ihn lesbar.
• Den Willen zur Ursachensuche. Journal und Ereignisstrom lassen sich lesen; einen Bezug zwischen ihren Einträgen und einer Abweichung beschreibt der Vertrag nicht.

Der Ablauf

Die Tabelle nennt je Stufe den zuständigen Aufruf und das, was danach vorliegt. Die Begründung, warum die Stufe nicht übersprungen werden kann, steht darunter.

Warum jede Stufe nötig ist

1. Den Abgleich lesen. GET /commerce/v1/reconciliations/{reconciliationId} liefert counts mit matched, discrepant und criticalRemaining, integrity mit den Prüfsummen beider Seiten und discrepancies mit kind, resourceId, severity und state. Die kritischen zuerst: severity unterscheidet warning und critical; welche Wirkung eine kritische Abweichung hat, beschreibt der Vertrag nicht.
2. Entscheiden. POST /commerce/v1/reconciliations/{reconciliationId}/discrepancies/{discrepancyId}/resolution nimmt decision mit apply_source, apply_target oder accept_difference, dazu reasonCode und expectedRevision. Die Antwort nennt resultingState und decisionActorReference — die Entscheidung ist einem Akteur zugeordnet.
3. Den Bestand nachvollziehen. GET /commerce/v1/inventory/ledger zeigt je Buchung entryType, quantityDelta und balance. Jede Buchung trägt stockItemId; einen Bezug zu einer Abweichung beschreibt der Vertrag nicht.
4. Die Ereignisse nachlesen. GET /commerce/v1/events liefert Ereignisse mit streamId, sequence und correlationId. Dazu tragen sie type, resourceId und occurredAt; was eine Lücke in sequence bedeutet, beschreibt der Vertrag nicht.
5. Erneut abgleichen. POST /commerce/v1/reconciliations prüft denselben Zeitraum mit neuen Prüfpunkten. Belegt ist die Klärung, wenn criticalRemaining bei null steht; alles andere ist eine Behauptung.

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'

Was am Ende vorliegt

Am Ende ist jede Abweichung entschieden, begründet und einem Akteur zugeordnet, Journal und Ereignisstrom sind nachgelesen, und ein neuer Abgleich belegt, dass nichts Kritisches offen ist.

Wo das in der Dokumentation steht

Die verbindlichen Feldlisten, Fehlercodes und Beispielantworten stehen im OpenAPI-Vertrag dieser Fläche unter docs.tapinomahub.com (tapinoma-commerce). Alle Anwendungsfälle nach Fläche und Rolle geordnet: Übersicht der Anwendungsfälle.