Storno, Rücksendung und Erstattung als ein Vorgang

Ein Kunde widerruft, ein Teil kommt beschädigt zurück, ein anderes passt nicht. Drei verschiedene Vorgänge, die im Alltag oft in derselben Gutschrift verschwinden. Am Monatsende stimmt dann weder das Lager noch die Buchhaltung, und niemand kann sagen, welche Erstattung zu welcher Rücksendung gehörte.

Der Vertrag trennt die drei Vorgänge deshalb und verbindet sie über Kennungen: Die Erstattung verweist immer auf den Auftrag und, wenn returnId gesetzt ist, auf die Rücksendung. Damit lässt sich jede erfasste Erstattung einem Auftrag zuordnen und bei gesetzter Rücksendung auch dieser — rückwärts wie vorwärts.

Was dieser Fall voraussetzt

• Ein Auftrag mit Positionen. Storniert und zurückgenommen wird je Position und Menge, nicht pauschal; erstattet wird ein Betrag zum Auftrag.
• Ein Zeitpunkt des Eintreffens. Die angemeldete Rücksendung ist etwas anderes als die eingetroffene; den Eingang hält receivedAt fest. An dieses Feld knüpft der Vertrag die Erstattung nicht.
• Begründungen je Vorgang. Widerruf, Transportschaden und Fehlbestellung sind drei Gründe mit drei Folgen für das Lager.
• Eine Buchhaltung, die Korrekturbelege verarbeitet. Korrekturbelege stehen getrennt von der Rechnung und verweisen auf Rechnung und Auftrag; einen Verweis auf Erstattung oder Rücksendung enthalten sie 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. Vor dem Versand stornieren. POST /commerce/v1/cancellations nimmt salesOrderId, reasonCode und die Positionen mit Mengen. Solange nichts das Haus verlassen hat, ist das der günstigste Weg — es entsteht keine Rücksendung, die niemand bezahlen will.
2. Die Rücksendung erfassen. POST /commerce/v1/returns trägt receivedAt. Dieses Feld trennt die Ankündigung von der Tatsache. An dieses Feld knüpft der Vertrag die Erstattung nicht.
3. Erstatten. POST /commerce/v1/refunds nimmt salesOrderId, amount mit amountMinor und currency sowie reasonCode; returnId ist optional. Gehört die Erstattung zu einer Rücksendung, sollte diese Bindung über returnId gesetzt werden, denn der Vertrag erzwingt sie nicht: Eine Erstattung ohne Vorgang lässt sich später niemandem erklären.
4. Den Beleg ziehen. GET /commerce/v1/credit-notes listet Korrekturbelege, getrennt von der Rechnung; jeder verweist über invoiceId auf die Rechnung und über salesOrderId auf den Auftrag. Einen Verweis auf die Erstattung selbst sieht der Vertrag im Korrekturbeleg nicht vor; mit ihr teilt er nur den salesOrderId.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: erstattung-4711-ruecksendung-1' \
  -d '{"salesOrderId":"<salesOrderId>","returnId":"<returnId>","amount":{"amountMinor":8900,"currency":"EUR"},"reasonCode":"return"}' \
  'https://commerce-preview.invalid/commerce/v1/refunds'

Was am Ende vorliegt

Am Ende ist jede erfasste Erstattung über salesOrderId einem Auftrag zugeordnet, und jeder Korrekturbeleg verweist über invoiceId und salesOrderId auf Rechnung und Auftrag. Eine Erstattung, die mit returnId angelegt wurde, lässt sich zu ihrer Rücksendung zurückverfolgen.

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.