Ein zurückgekommenes Teil prüfen und über seine Verwendung entscheiden

Ein Steuergerät kommt zurück: Der Käufer schreibt, es passe nicht. Beim Auspacken zeigt sich ein beschädigter Stecker. Ob das Teil wieder in den Verkauf darf, aufgearbeitet werden muss oder verwertet wird, entscheidet nicht der Rücksendegrund des Käufers, sondern die Prüfung im Wareneingang.

Der Vertrag trennt deshalb drei Aussagen, die im Alltag gern in einem Feld landen: warum der Käufer zurückschickt, was die Prüfung ergibt und was mit dem Teil geschieht. Angenommen heisst nicht wieder verkäuflich — über die Verwendung wird mit einem eigenen Aufruf entschieden.

Was dieser Fall voraussetzt

• Ein Auftrag mit Positionen. Die Rücksendung verweist auf salesOrderId und die zurückgeschickten Positionen.
• Eine Prüfung durch jemanden, der das Teil kennt. Die Entscheidung über die Verwendung ist fachlich, nicht administrativ.
• Feste Gründe für Befund und Verwendung. reasonCode ist hier ein eigener Code in Kleinbuchstaben; ein Katalog im eigenen Betrieb hält ihn einheitlich.
• Eine erwartete Revision. Prüfung und Verwendung verlangen expectedRevision; die Rücksendung selbst trägt laut Vertrag keine Revision.

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. Die Rücksendung erfassen. POST /commerce/v1/returns nimmt salesOrderId, die Positionen, reasonCode mit not_as_described, damaged, incompatible, buyer_withdrawal oder other und optional receivedAt. Das ist der Grund des Käufers — noch kein Befund.
2. Die Ware prüfen. POST /commerce/v1/returns/{returnId}/review nimmt decision mit accept, reject, partial oder attention_required und je Position reviewedQuantity, finding und reasonCode. Die Antwort nennt decisionActorReference: Die Prüfung ist einem Akteur zugeordnet.
3. Die Verwendung festlegen. POST /commerce/v1/returns/{returnId}/disposition entscheidet je Position zwischen restock, repair, recycle, dispose und hold. hold ist ein eigener Wert von disposition; eine Wirkung auf Angebote beschreibt der Vertrag nicht.
4. Das Bestandsjournal lesen. GET /commerce/v1/inventory/ledger liefert je Buchung entryType, quantityDelta und balance. entryType kennt physical_set, safety_stock_set, reserved, released, consumed und expired; einen Bezug zur Verwendungsentscheidung beschreibt der Vertrag nicht.
5. Das Lagerstück nachführen. PUT /commerce/v1/stock-items/{stockItemId} setzt condition mit new, used oder refurbished und locationKey neu. Ändern sich nach Prüfung oder Aufarbeitung Zustand oder Lagerplatz, gehört die Änderung ins Lagerstück, nicht in eine Notiz.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: verwendung-ruecksendung-4711' \
  -d '{"lines":[{"lineId":"<lineId>","quantity":1,"disposition":"repair","reasonCode":"<reasonCode>"}],"expectedRevision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/returns/<returnId>/disposition'

Was am Ende vorliegt

Am Ende hat jedes zurückgekommene Teil einen entschiedenen Weg, eine zugeordnete Prüfung und einen nachgeführten Bestand. Für das Steuergerät mit dem beschädigten Stecker ist repair festgelegt.

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.