Ein Händler setzt Preise mit einem Aufschlag auf den Einkauf und stellt am Jahresende fest, dass eine Warengruppe nichts verdient hat. Der Grund steht in den Kanalgebühren, die niemand je nachgerechnet hat. Der Aufschlag war richtig — er war nur auf die falsche Basis gerechnet.
Die fünf Zweige beantworten vier verschiedene Fragen an dasselbe Verkaufskonto. Sie hängen nicht voneinander ab, und man braucht nicht alle — aber wer Preise setzt, ohne Gebühren nachzurechnen, rechnet auf einer Basis, die er nicht kennt.
| Fläche | Rollen |
|---|---|
| Commerce | Teilehandel, Softwarehaus, Plattform und Marktplatz |
Was dieser Fall voraussetzt
- Ein Nettoziel, das Sie erreichen wollen. Mit
targetNetrechnet die Preisregel zurück; ein fester Aufschlag garantiert laut Vertrag keinen Zielerlös. - Bereitschaft, Gebührenzeilen zu lesen. Ein Beleg, den niemand prüft, ist eine Rechnung, die man bezahlt.
- Zwei Prüfpunkte für den Abgleich. Quelle und Ziel brauchen je einen Stand;
sourceCheckpointundtargetCheckpointsind Pflichtfelder des Abgleichs. - Ein Empfänger für Ereignisse, wenn Sie nicht pollen wollen. Ein Abonnement ohne erreichbaren Empfänger stellt nichts zu.
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.
| Stufe | Aufruf | Was danach vorliegt |
|---|---|---|
| Preisregel anlegen | POST /commerce/v1/pricing-policies | targetNet rechnet vom Zielerlös zurück; includeChannelFees und includeServiceFees steuern die Gebühren |
| Gebührenbeleg prüfen | GET /commerce/v1/fee-statements | Je Zeile basis, feeBasisPoints und feeAmount — nachrechenbar statt geglaubt |
| Abgleich fahren | POST /commerce/v1/reconciliations | sourceCheckpoint gegen targetCheckpoint, dazu discrepancies mit severity |
| Ereignisse abonnieren | POST /commerce/v1/webhook-subscriptions | Signierte Zustellung, damit nicht im Takt gepollt werden muss |
| Strom nachlesen | GET /commerce/v1/events | Ereignisse mit streamId und sequence, per stabiler Cursor-Paginierung abrufbar |
Warum jede Stufe nötig ist
- Die Preisregel anlegen.
POST /commerce/v1/pricing-policieskennt neben einem festen Aufschlag auchtargetNet: Sie nennen das Netto, das übrig bleiben soll, und die Regel rechnet zurück — mit Kanalgebühren, Dienstgebühren und Rabatten, je nachdem, was Sie einbeziehen. Das ist der Unterschied zwischen Umsatz und Ertrag. - Den Gebührenbeleg prüfen.
GET /commerce/v1/fee-statementsliefert je Zeilebasis,feeBasisPointsundfeeAmount, dazu bei Korrekturen den Verweis auf die berichtigte Zeile. Damit lässt sich eine Gebühr nachrechnen statt sie zu glauben. - Den Abgleich fahren.
POST /commerce/v1/reconciliationsvergleichtsourceCheckpointmittargetCheckpointund liefertcounts,integritymit Prüfsummen für Quelle und Ziel unddiscrepanciesmitseverity. Die entscheidende Zahl istcriticalRemaining, die Zahl der verbliebenen kritischen Abweichungen; der Abgleich ist im Vertrag noch nicht aktiviert. - Ereignisse abonnieren.
POST /commerce/v1/webhook-subscriptionsrichtet eine signierte Zustellung ein. Wer stattdessen im Takt pollt, erzeugt Last und merkt eine Lücke trotzdem erst spät. - Den Strom nachlesen.
GET /commerce/v1/eventsgibt Ereignisse mitstreamIdundsequence. Abgerufen wird mit stabiler Cursor-Paginierung (cursor,limit).
curl -X POST \
-H 'X-Api-Key: <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: preisregel-netto-2026-09' \
-d '{"strategy":"target_net","scope":{"catalogItemIds":["<catalogItemId>"]},"targetNet":{"target":{"amountMinor":4500,"currency":"EUR"},"calculationBasis":"item_price","includeChannelFees":true,"includeServiceFees":true,"includeDiscounts":false},"revision":"<revision>"}' \
'https://commerce-preview.invalid/commerce/v1/pricing-policies'Was am Ende vorliegt
Am Ende können Sie jede Gebührenzeile nachrechnen, lassen Angebotspreise mit targetNet aus einem Zielerlös und den einbezogenen Gebühren ableiten und lesen nach einem Abgleich an criticalRemaining ab, wie viele kritische Abweichungen zwischen Quelle und Ziel verblieben sind. Einkaufskosten kennt der Vertrag nicht; Ihre Marge ermitteln Sie mit Ihren eigenen Zahlen.
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.
Quellen und Rechtsgrundlagen
Häufige Fragen
Was ist der Unterschied zwischen Aufschlag und Nettoziel?
Der feste Aufschlag wendet ausschließlich den Satz aus fixedMarkupBasisPoints an und garantiert keinen Zielerlös; auf welche Basis er sich bezieht, legt der Vertrag nicht fest. Das Nettoziel rechnet rückwärts von dem, was übrig bleiben soll, und bezieht die Gebühren ein, die Sie einschließen.
Warum brauche ich einen Abgleich, wenn ich Ereignisse abonniere?
Weil eine Zustellung ausfallen kann. Das Abonnement hält Sie aktuell, der Abgleich stellt Abweichungen zwischen Quelle und Ziel fest — das sind zwei verschiedene Aufgaben.
Muss ich alle fünf Zweige benutzen?
Nein. Sie sind unabhängig. Wer Abweichungen zwischen Quelle und Ziel feststellen will, braucht den Abgleich; wer Preise automatisch setzen will, braucht die Regel.