Kasse: Bestellungen per Schnittstelle
In der Choicera-Kasse bezahlt der Kunde Produkte mehrerer Marken auf einmal. Deinen Teil der Bestellung übergeben wir bezahlt an dich. Hat dein Shop keine Schnittstelle, die wir direkt nutzen können, baust du die Endpunkte auf dieser Seite. Ohne sie kommt jede Bestellung als E-Mail mit Links zum Stornieren und zum Melden des Versands.
Was zu tun ist
- Baue den Endpunkt
POST /orders, der unsere Bestellung in deinem Shop anlegt, und nenn uns Basis-URL und Token. Fertig, wenn eine Testbestellung von uns in deinem Shop steht und eine zweite Zustellung derselben Bestellung keine zweite anlegt. - Melde Versand mit Sendungsnummer und jeden Storno an unseren Endpunkt, signiert mit dem Schlüssel, den du von uns bekommst. Fertig, wenn unsere Testadresse deine Meldungen mit HTTP 200 annimmt und die Testbestellung bei uns als versendet steht.
- Lies die E-Mails an deine Bestelladresse weiter mit. Rücksendungen, Kundenanfragen und Hinweise zur Zahlung kommen nur dort. Fertig, wenn uns eine Bestelladresse vorliegt, die jemand liest.
Ablauf einer Bestellung
- Bezahlt Der Kunde bezahlt in der Choicera-Kasse. Das Geld läuft über einen lizenzierten Zahlungsdienstleister und wird an dich ausgezahlt. Bei der Übergabe ist der Betrag reserviert. Du forderst beim Kunden keine Zahlung an; deine Rechnung trägt keine Bankverbindung, sondern den Vermerk „bezahlt über die Choicera-Kasse“.
- Übergeben
Wir senden die Bestellung an
POST /orders, du antwortest mit 201 und deiner Bestellnummer. - Stornofrist
Bis 23:59 Uhr am zweiten Arbeitstag nach der Übergabe kannst du stornieren, ohne dass wir einziehen. Der
Übergabetag zählt nicht mit, Feiertage an deinem Sitz auch nicht. Das genaue Ende steht in der
Bestellung als
acceptDeadline. Storniert wird nur aus einem der vier Gründe. - Angenommen
Ohne Storno gilt die Bestellung nach Fristende als angenommen, und wir ziehen den Betrag ein. Die
Meldung
acceptedoder eine Versandmeldung ist ebenfalls eine Annahme; dann ziehen wir sofort ein. Bei Karten ziehen wir spätestens vor Ablauf der Reservierung ein, auch wenn die Frist noch läuft. - Versendet Deine Versandmeldung mit Sendungsnummer geht als Nachricht an den Kunden, mit Link zur Sendungsverfolgung. Melde den Versand spätestens vier Wochen nach der Annahme; danach ist die Bestellung bei uns abgeschlossen.
Bestellung annehmen
POST https://{deine-basis-url}/orders
Authorization: Bearer {dein-token}
Idempotency-Key: {kennung-der-zustellung}
Content-Type: application/json
Basis-URL und Token kommen von dir, nur über HTTPS mit gültigem Zertifikat. Weiterleitungen folgen wir nicht. Vollständig als Datei: checkout-orders.openapi.yaml (OpenAPI 3.1).
Felder der Bestellung
| Feld | Bedeutung |
|---|---|
publicRef | Bestellnummer von Choicera, etwa C7K2M9QX4TA. Eindeutiger Schlüssel; speichere sie an deiner Bestellung, alle Rückmeldungen nennen sie. |
orderedAt | Zeitpunkt der Bestellung, ISO 8601 in UTC |
currency | immer EUR |
test | true bei Bestellungen aus unserer Testumgebung: anlegen, kennzeichnen, nicht versenden |
orderTag | Kennung, die du bei uns hinterlegt hast, etwa eine Berater-Kennung, sonst null |
customer | Vorname, Nachname, E-Mail und marketingAllowed: ob dein Vertrag mit uns dir Werbung an diesen Kunden erlaubt. Die E-Mail ist null, wenn dein Vertrag keine Kontaktdaten vorsieht; braucht dein Shop eine, nimm eine Platzhalteradresse und sende nichts an sie. |
shippingAddress, billingAddress | Straße und Hausnummer getrennt, Zusatz, PLZ, Ort, Land DE oder AT. Ohne Firma und Packstation. Fehlt der Name, gilt der Name aus customer. billingAddress ist null, wenn sie der Lieferadresse entspricht. |
lines | Positionen mit lineId, variantId aus deinen Produktdaten, title, variantTitle, Menge, Stückpreis, Rabatt der Position, Zeilensumme und vatRatePercent |
goodsCents, discountCents, shippingCents, totalCents | Ware vor Rabatt, Rabatt, Versand und Gesamtbetrag, brutto in Cent. totalCents = goodsCents - discountCents + shippingCents. |
vatBreakdown | Je Steuersatz der Versandanteil, der Gesamtbetrag und die enthaltene Mehrwertsteuer. Den Versand verteilen wir nach dem Warenwert. Für deine Rechnung übernehmen. |
paymentMethod | applePay, googlePay, card, klarna, sepaDebit oder paypal, nur für die Rechnung. Bei klarna zahlt der Kunde an Klarna; fordere in keinem Fall eine Zahlung beim Kunden an. |
acceptDeadline | Ende der Stornofrist, ISO 8601 in UTC, gerechnet ab diesem Aufruf |
variantId ist immer gesetzt und der Wert, den du je Variante in deinen
Produktdaten lieferst; welches Feld das ist, nennen wir dir beim Anschluss. Im JSON-Feed ist es
variants[].sku oder variants[].id, bei OXID-Produktseiten die Artikel-ID
aid. Lege die Bestellung mit genau diesen Preisen an, ohne neu zu rechnen.
Der Stückpreis nach Rabatt geht nicht immer in ganzen Cent auf; maßgeblich ist die Zeilensumme.
Antwort
| Antwort | Bedeutung |
|---|---|
| 201 | Angelegt und gespeichert, Body {"brandOrderRef": "SW-10042"} mit deiner Bestellnummer, höchstens 64 Zeichen |
| 200 | Zu dieser publicRef gibt es schon eine Bestellung. Gleicher Antwort-Body wie beim ersten Mal. |
| 503 | Die Anlage derselben publicRef läuft noch. Mit Retry-After, nie 409. |
| 4xx | Nur, wenn der Body kein JSON ist, publicRef fehlt oder der Token nicht stimmt. Endgültig außer 408, 425 und 429: Wir schicken die Bestellung dann als E-Mail. Nach 401 oder 403 kommen alle weiteren Bestellungen als E-Mail, bis du uns einen neuen Token nennst. |
Fachliche Gründe sind kein 4xx. Nimm die Bestellung an und storniere sie per
Rückmeldung: Preis weicht ab mit price_mismatch, Artikel unbekannt oder nicht lieferbar
mit out_of_stock, Land nicht bedient mit country_not_served. Lege je
publicRef höchstens eine Bestellung an, auch wenn ein neuer Versuch einen neuen
Idempotency-Key trägt. Wiederholungen tragen denselben Body, nur
acceptDeadline kann sich ändern: Beantwortest du eine Wiederholung mit 200, übernimm
acceptDeadline aus ihr.
Rückmeldung an Choicera
POST https://choicera.com/api/checkout/brand-feedback/v1
X-Choicera-Brand: {deine-markenkennung}
X-Choicera-Timestamp: {sekunden-seit-1970}
X-Choicera-Signature: {hmac-hex}
Content-Type: application/json
{"eventId": "sw-ship-10042", "publicRef": "C7K2M9QX4TA", "type": "shipped",
"shipment": {"trackingNumber": "00340434161234567890", "carrier": "dhl"}}
Jede Meldung hat eine eventId, die bei dir eindeutig ist, etwa eine UUID. Sendest
du dieselbe eventId noch einmal, ändert sich nichts, und du bekommst die Antwort des
ersten Mals; das gilt nach 200 und 409. Nach einem anderen Fehler schickst du die korrigierte
Meldung mit derselben eventId. Meldungen zu einer Bestellung sendest du nacheinander
und wartest jeweils mindestens 30 Sekunden auf die Antwort, weil wir mit einer Annahme sofort
einziehen. Rückmeldungen gelten für jede deiner Kassenbestellungen, auch für eine, die als E-Mail
kam. Vollständig als Datei:
checkout-feedback.openapi.yaml (OpenAPI 3.1).
Meldungen
type | Wann und womit |
|---|---|
accepted | Du nimmst vor Fristende an. Optional, ohne Storno gilt die Bestellung nach der Frist ohnehin als angenommen. |
shipped | Die Ware ist unterwegs, gilt zugleich als Annahme. Dazu shipment mit trackingNumber, carrier und optional trackingUrl. |
delivered | Zugestellt, falls du es erfährst. Ohne vorherige Versandmeldung zugleich Versandmeldung und Annahme. |
cancelled | Du stornierst die ganze Bestellung oder einzelne Positionen, vor der ersten Versandmeldung. Dazu cancellation mit reason und lines: "all" oder je Position lineId und remainingQuantity. |
Storno-Gründe
reason | Bedeutung |
|---|---|
price_mismatch | Preis weicht von deinem Shop ab |
out_of_stock | nicht lieferbar |
country_not_served | Lieferland wird nicht bedient |
fraud_suspected | Verdacht auf Betrug |
Eine Bestellung, eine Sendung. Kannst du nicht alles liefern, storniere zuerst die fehlenden
Positionen und melde dann den Versand. remainingQuantity ist die Menge der Position,
die du noch lieferst; 0 storniert sie ganz. Eine Wiederholung derselben Angabe ändert nichts. Nach
der ersten Versandmeldung ist kein Storno mehr möglich; Rücksendungen laufen über uns. Ein Storno
nach dem Einzug geht noch bis zur Versandmeldung, dann erstatten wir dem Kunden den Betrag.
Beim Teil-Storno verteilen wir den Rabatt einer Position anteilig auf die übrigen Stücke, der Versand bleibt. Die Antwort nennt dann je Position Menge, Rabatt und Zeilensumme und den neuen Gesamtbetrag; übernimm sie für deine Rechnung.
Schick die Sendungsnummer gleich mit shipped: Die Versandnachricht an den Kunden
geht nur einmal raus. Ohne Sendungsverfolgung lässt du shipment weg. Bei mehreren
Paketen nennst du die erste Nummer. Eine korrigierte Nummer meldest du als weiteres
shipped mit neuer eventId; sie ersetzt die alte und steht nur noch im
Bestellstatus. Sendungsnummer höchstens 64 Zeichen aus Buchstaben, Ziffern, Leerzeichen und
Bindestrich. Versanddienste für carrier: dhl, dpd,
hermes, gls, ups, post_at, sonst
other. Fehlt trackingUrl (nur https), bauen wir den Link zur
Sendungsverfolgung selbst.
Antwort
| Antwort | Bedeutung |
|---|---|
| 200 | {"eventId": "...", "result": "applied"} übernommen, oder "unchanged", der Stand war schon so |
| 400 | Body nicht lesbar, Pflichtfeld fehlt oder Wert außerhalb des Formats |
| 401 | Signatur falsch, Markenkennung unbekannt oder Zeitstempel mehr als fünf Minuten neben unserer Uhr |
| 404 | Zu dieser publicRef gibt es bei dir keine Kassenbestellung |
| 409 | Passt nicht zum Stand, etwa ein Storno nach der Versandmeldung. Die Bestellung bleibt, wie sie ist; state nennt den Stand. |
| 429, 503 | Gerade nicht möglich, etwa kurz nach der Übergabe. Nach Retry-After erneut senden. |
Signatur
Den Schlüssel bekommst du beim Anschluss von uns, er gilt nur für deine Marke. Signiert wird mit
HMAC-SHA256 die Zeichenkette aus dem Zeitstempel genau wie im Header, einem Punkt und dem
unveränderten Body. Der Schlüssel sind die UTF-8-Bytes der Zeichenkette, die du bekommst. Das
Ergebnis geht als Hex in Kleinbuchstaben in X-Choicera-Signature. Der Zeitstempel
sind die Sekunden seit 1970 in UTC. Das ist ein anderes Verfahren als beim
Bestell-Webhook in Schritt 3.
ts=$(date +%s)
body='{"eventId":"sw-accept-10042","publicRef":"C7K2M9QX4TA","type":"accepted"}'
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$SCHLUESSEL" | sed 's/^.* //')
curl -sS https://choicera.com/api/checkout/brand-feedback/v1 \
-H 'Content-Type: application/json' -H 'X-Choicera-Brand: deine-markenkennung' \
-H "X-Choicera-Timestamp: $ts" -H "X-Choicera-Signature: $sig" --data "$body"
# PHP
$sig = hash_hmac('sha256', $ts . '.' . $body, $schluessel);
Zum Prüfen deiner Umsetzung: Schlüssel beispiel-schluessel-nur-fuer-tests,
Zeitstempel 1794231600 und genau der Body aus dem Skript oben, ohne Leerzeichen und
Zeilenumbruch, ergeben
207b0a26924107fe70e74d47472e0a214881ba2e08452fad20dafd5c8c722a94. Signiere genau die
Bytes, die du sendest, in UTF-8 und ohne Komprimierung.
Fehler und Wiederholungen
| Fall | Regel |
|---|---|
| Wir an dich, wiederholt | 5xx, 408, 425, 429, keine Antwort binnen 10 Sekunden, Netzfehler, andere 2xx als 200 und 201, eine Antwort ohne brandOrderRef. Im Abstand weniger Minuten bis zu zwei Stunden, danach kommt die Bestellung als E-Mail. |
| Wir an dich, endgültig | Andere 4xx und Weiterleitungen. Die Bestellung kommt sofort als E-Mail, mit dem Fehlercode. |
| Du an uns, wiederholen | 5xx, 503, 429, Netzfehler, Zeitüberschreitung. Mit wachsendem Abstand, mindestens 24 Stunden lang, mit derselben eventId. Eine 401 verwirfst du nie: Uhr oder Schlüssel richten, neu signieren, erneut senden. |
| Du an uns, endgültig | 400, 404, 409, 413, 415. Meldung prüfen; eine korrigierte Meldung geht nach 400, 404, 413 und 415 mit derselben eventId. |
Kommt eine Bestellung als E-Mail, weil dein Endpunkt nicht antwortete, prüfe anhand der
publicRef, ob sie schon in deinem Shop steht, bevor du sie anlegst.
Bestand
Vor der Zahlung prüfen wir, ob alles lieferbar ist. Grundlage ist der Bestand aus deinen Produktdaten, die wir einmal am Tag lesen. Für einen aktuellen Stand kannst du zusätzlich eine Abfrage bauen:
GET https://{deine-basis-url}/stock?variantIds=D3-120,MAG-1001
Authorization: Bearer {dein-token}
{"items": [{"variantId": "D3-120", "available": true},
{"variantId": "MAG-1001", "available": false}]}
available heißt: mindestens ein Stück lieferbar. Wir fragen kurz vor der Zahlung die
Artikel im Warenkorb ab, höchstens 50 auf einmal und nie Kennungen mit Komma, und warten höchstens
drei Sekunden. Antworte deshalb aus dem Lagerbestand, ohne langsame Abfragen.
Kommt keine Antwort oder fehlt ein Artikel darin, gilt der Stand aus den Produktdaten.
Was per E-Mail kommt
Auch mit Schnittstelle bekommst du diese E-Mails an deine Bestelladresse:
- die Bestellung selbst, wenn dein Endpunkt sie nicht annimmt
- die Erinnerung einen Tag vor Fristende, solange du weder angenommen noch storniert hast
- „bitte nicht versenden“, wenn der Einzug scheitert, und „jetzt versenden“, wenn er doch noch gelingt
- „wird nicht ausgeführt“, wenn der Einzug endgültig scheitert, und eine Rückbelastung mit der Bitte, den Versand anzuhalten
- Kundenanfragen und Rücksendungen. Etikett verschickt und Ware eingegangen bestätigst du über die Links darin, wir erinnern an die Fristen.
Erstattungen an den Kunden laufen immer über uns.
Schlüssel und Tests
Den Token für POST /orders stellst du aus, den Signatur-Schlüssel für die
Rückmeldung bekommst du von uns. Beide tauschen wir über einen Weg aus, den wir beim Anschluss
festlegen, nie per E-Mail im Klartext. Für einen Wechsel nimmst du alten und neuen Token eine Zeit
lang beide an und sagst uns Bescheid; einen neuen Signatur-Schlüssel nehmen wir 14 Tage lang neben
dem alten an. Ist ein Schlüssel nach außen gelangt, tauschen wir ihn sofort.
Vor dem Start senden wir Testbestellungen mit "test": true, gern an eine eigene
Test-Basis-URL mit eigenem Token, damit dein Lagerbestand unberührt bleibt. Für deine
Rückmeldungen zu Testbestellungen nennen wir dir eine Testadresse und einen Testschlüssel; dort
fließt kein Geld, und unsere echte Adresse antwortet auf sie mit 404. Wir schalten die Anbindung
für deine Marke frei, bevor die erste echte Bestellung kommt.
OXID-Shops
OXID hat im Kern keine Schnittstelle für Bestellungen. Die offiziellen GraphQL-Module legen Bestellungen nur so an, wie ein Kunde im Shop bestellt, mit den Preisen deines Shops und ohne Zugang für einen Dienst wie uns. Für OXID-Shops sind deshalb die Endpunkte auf dieser Seite der Weg. Hast du eine andere Schnittstelle, die Bestellungen mit vorgegebenen Preisen annimmt, sprich uns an.
Bei Fragen zur Anbindung: Partner-Kontakt. Unbekannte Felder und neue Werte in Aufzählungen nimmst du an; neue Felder und Werte kommen ohne Versionssprung, neue Pflichtfelder nur mit einer neuen Version.
