Die API dient der Übertragung von Auftragsinformationen zwischen Slevomat und dem System des Handelspartners. Die API erfordert die Implementierung einer bidirektionalen Kommunikation – das Slevomat-System ruft die API des Partners auf und der Partner ruft die API von Slevomat auf.
Aufträge, die an die Partner-API exportiert werden, können in der Slevomat-Partneroberfläche nicht mehr manipuliert, sondern nur noch angesehen werden. Die Manipulation von exportierten Aufträgen kann nur noch über die API erfolgen.
Alle Anfragen müssen über HTTPS gestellt werden und alle Daten liegen im JSON-Format vor.
API-Zugang
Sie können die API-Zugangsdaten über die Registerkarte "Einstellungen" in Ihrer Partneroberfläche aufrufen. Um die Daten zu erhalten, müssen Sie die Root-URL des Partnerteils der API für die Verwendung in der Richtung Slevomat → Partner angeben, z. B.
https://example.com/slevomat-zbozi-api Die Zugangsdaten werden nur einmal beim Zugriff auf die API angezeigt, bitte speichern Sie sie sorgfältig.
Sobald der Zugriff auf die API erfolgt ist, beginnt das System, neu erstellte Aufträge dorthin zu exportieren.
Erster Datenexport
Um bestehende Aufträge zum Zeitpunkt des API-Zugangs zu übertragen, können Sie in der Partnerschnittstelle einen einmaligen Export nach CSV nutzen.
Wenn Sie bestehende Aufträge (die vor der Bereitstellung der API erstellt wurden) in Ihrem eigenen System haben und mit diesen über die API arbeiten möchten, verwenden Sie die Funktion "Arbeit mit markierten Aufträgen über API beginnen" im Menü "Massenaktionen mit Aufträgen".
Beschreibung der üblichen HTTP-Antworten
-
200 OK– die Anfrage wurde erfolgreich bearbeitet -
204 No Content– die Anfrage wurde bearbeitet, die Antwort hat keinen Inhalt -
400 Bad Request– die Anfrage ist ungültig – es fehlen möglicherweise Parameter oder sie sind ungültig gegenüber der Spezifikation -
403 Forbidden– Client-Autorisierung fehlgeschlagen -
404 Not Found– Endpunkt oder erforderliche Daten nicht gefunden -
405 Method Not Allowed– der Endpunkt unterstützt diese HTTP-Methode nicht -
422 Unprocessable Entity– erwarteter Fehler bei der Verarbeitung der Anfrage (siehe Abschnitt Fehlerbedingungen) -
500 Internal Server Error– auf der Serverseite ist ein Fehler aufgetreten -
502 Bad Gateway– ein Server-seitiger Fehler ist aufgetreten -
503 Service Unavailable– der Server befindet sich im Wartungsmodus (neue Version wird möglicherweise gerade bereitgestellt oder es ist eine Ausfallzeit geplant) -
504 Gateway Timeout– ein serverseitiger Fehler ist aufgetreten
HTTP 5×x-Antworten dürfen kein JSON-Format verwenden.
Im Falle von 4xx -Fehlern ist die ausgehende Anfrage fehlerhaft und muss korrigiert werden, bevor sie erneut versucht wird.
Fehler 5xx deuten auf Serverfehler hin, und die Anfrage kann ohne Änderung erneut versucht werden. Im Falle von 503 sollte der Aufrufer die Kopfzeile der Antwort Retry-After beachten und den Versuch erst nach Ablauf der in der Kopfzeile angegebenen Zeit wiederholen.
Status der Bestellung
Ein Auftrag befindet sich immer in einem der folgenden Zustände:
| Wert des Status | Beschreibung |
| 1 | Neue bezahlte Bestellung |
| 2 | Betreut |
| 3 | Unterwegs (nur Bestellungen mit Versand) |
| 4 | Vorbereitung der persönlichen Abholung – z. B. Transport zu einer Filiale |
| 5 | Bereit zur persönlichen Abholung |
| 6 | An den Kunden geliefert – Kundenbestätigung steht noch aus |
| 7 | Geliefert und vom Kunden bestätigt |
| 8 | Kunde weigerte sich, den Erhalt der Bestellung zu bestätigen |
| 9 | Annullierte Bestellung |
Der Kunde wird über jede Änderung des Status per E‑Mail informiert.
Die Bestellung muss nicht zwangsläufig alle Status durchlaufen, um erfolgreich ausgeliefert zu werden, von "Neue Bestellung bezahlt" kann man direkt zu "Auf dem Weg" / "Bereit zur persönlichen Abholung" und dann zu "An den Kunden ausgeliefert – Kundenbestätigung erwartet" übergehen. Die Verwendung aller Status führt jedoch zu einer besseren Kundeninformation über den Fortgang der Bestellung und wird empfohlen.
Fehlerzustände
Bei 4×x-HTTP-Codes enthält die Antwort immer den Schlüssel status (siehe nachstehendes Codebuch) und das Feld messages mit Textbeschreibungen der Fehler.
| Statuswert | Beschreibung |
| 1 | Ungültige Anfrage – fehlende oder ungültige Werte |
| 2 | Ungültige Anmeldedaten |
| 3 | Nicht vorhandener Auftrag |
| 4 | Nicht existierende Auftragsposition |
| 5 | Übergang eines Auftrags in einen nicht genehmigten Zustand |
| 6 | Ungültige Stornierung – Stornierung von mehr Positionen als vorhanden |
| 7 | Sonstiger Fehler |
| 8 | Der Auftrag wurde noch nicht an die Partner-API exportiert – er kann nicht über die API manipuliert werden |
| 9 | Um den Status "Ware an den Kunden geliefert" automatisch zu setzen, müssen Sie die Sendung automatisch auf "Ware zur Abholung bereit" setzen lassen. |
Beispiel:
{ "status": 3, "messages": [ "Order #1234 was not found." ] }Datentypen
Die Datentypen der einzelnen Schlüssel in Anfragen und Antworten werden immer für bestimmte Endpunkte beschrieben. Sofern nicht anders angegeben, ist der Wert in Anführungszeichen "" immer eine obligatorische Zeichenkette. Sofern nicht anders angegeben, ist der numerische Wert immer eine obligatorische Ganzzahl.
Kommunikation Slevomat ⇒ Partner
Dieser Teil der API ist auf der Partnerseite implementiert und wird von Slevomat aufgerufen.
Die benötigte API-Root-URL wird vom Partner zur Verfügung gestellt und sollte die folgende Form haben
https://www.example.com/slevomat-zbozi-api/v1Autorisierung anfordern
Wenn die API aktiviert ist, erhält der Partner partner_api_secret, was beweist, dass die eingehenden Anfragen tatsächlich von Slevomat stammen.
Dieser Parameter wird im HTTP-Header X-PartnerApiSecret übergeben.
Test-Schnittstelle
Slevomat enthält Funktionen, um die API auf der Partnerseite aufzurufen und die Antwort einzusehen. Die vom Partner bei der Bereitstellung der API angegebene Root-URL wird an -test angehängt, so dass beim Testen die API z. B. unter folgender Adresse aufgerufen wird
https://example.com/slevomat-zbozi-api-testaufgerufen wird, um eine Vermischung von Testdaten mit Live-Bestellungen zu vermeiden.
Das Testen der Partner-API erfolgt über POST-Anfragen an die folgenden Adressen:
-
- Neue Bestellunghttps://www.slevomat.cz/test-zbozi-partner-api/v1/new-order -
- Massenaktualisierung der voraussichtlichen Versanddatenhttps://www.slevomat.cz/test-zbozi-partner-api/v1/update-shipping-dates -
- Ändern Sie den Auftragsstatus in "An den Kunden geliefert – Kundenbestätigung steht noch aus".https://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered -
- Bestellstatus ändern in "Bereit zur persönlichen Abholung".https://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup -
- Bestätigung der Lieferunghttps://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery -
- Verweigerung der Annahmehttps://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery -
- Annullierunghttps://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/cancel
Ersetzen Sie den Teil <orderId> der URL durch eine beliebige Auftragsnummer, Anfragen an die Partner-API werden mit dieser Auftragsnummer gestellt.
Anfragen an diese Testschnittstelle müssen mit den Headern X-PartnerToken und X-ApiSecret autorisiert werden.
Bei einem Testaufruf an die Partner-API sendet das System wie im Echtbetrieb den Header X-PartnerApiSecret.
Die mit einer neuen Bestellung gesendeten Daten sind Testdaten und werden zufällig generiert.
Wenn Sie eine Bestellungsstornierung senden, müssen Sie das Feld items in den POST-Body der Anfrage in JSON (im gleichen Format wie von der API gesendet) aufnehmen, das von der Testschnittstelle validiert und in der gleichen Form an die Partner-API weitergeleitet wird.
Neue Bestellung
Die Anfrage enthält die Daten des neu angelegten Auftrags.
Aufträge haben immer eine eindeutige slevomatId. Erhält die API ein Duplikat slevomatId, sollte die Anfrage von der Partner-API ignoriert werden (die erste Anfrage wurde von Slevomat als erfolglos bewertet und daher wiederholt) und die Antwort sollte ebenfalls HTTP 204 lauten.
created ist das Datum im ISO 8601 Format, d.h. YYYY-MM-DD'T'HH:mm:ss+zz:zz.
productId enthält die Ereignis-ID, variantId die ID der gekauften Variante.
Die optionale internalId gibt die interne ID an, die für die Aktionsvariante bei ihrer Erstellung in der Partnerschnittstelle eingegeben wurde. Sie dient zur Identifizierung des Produkts im System des Partners.
In billingAddress (Rechnungsadresse) ist nur der Kundenname (name) obligatorisch.
Bei shippingAddress (Lieferadresse) ist die Angabe des Unternehmens (company) fakultativ. Bei Lieferung an shippingAddress enthält sie die Anschrift des Kunden, bei persönlicher Abholung die Anschrift der Einrichtung, in der der Kunde die Waren abholt.
Der Schlüssel delivery.type kann den Wert address (Lieferung an Adresse) oder pickup (persönliche Abholung) annehmen. delivery.name enthält den Namen der Beförderung oder den Namen der Niederlassung.
delivery.expectedShippingDate (voraussichtliches Versanddatum) und delivery.expectedDeliveryDate (voraussichtliches Lieferdatum) sind Daten im Format YYYY-MM-DD.
Der Schlüssel weight enthält das Gewicht der Bestellung in Kilogramm. Wenn wir nicht das Gewicht aller Artikel in der Bestellung kennen, nimmt er den Wert null an.
POST /bestellung/$slevomatId
{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShippingDate": "2021–08–27", "expectedDeliveryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }POST /Bestellung/$slevomatId
{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShippingDate": "2021–09–02", "expectedDeliveryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }Massenaktualisierung der erwarteten Versanddaten
Wenn der Geschäftsmanager auf Wunsch des Partners die Versandtermine ausgewählter Bestellungen in großen Mengen verschiebt, informiert das System die Partner-API über diese Aktualisierung.
Die gesendeten Daten enthalten das Feld für die Auftrags-ID und das neue erwartete Versanddatum.
POST /update-shipping-dates
{ "expectedShippingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }Stornierung
Stornierungen können sowohl auf der Slevomat-Seite als auch auf dem Partnersystem erstellt werden. Dieser Endpunkt wickelt die Erstellung der Stornierung auf der Slevomat-Seite und ihre Übertragung an das System des Partners ab.
Er erstellt eine Stornierung von Auftragspositionen in der angegebenen Menge. Wenn der gesamte Auftrag storniert werden soll, werden alle Positionen mit der entsprechenden Menge aufgelistet.
Einzelne Positionen können auch teilweise storniert werden (z. B. 1 von 2).
Ein Stornovermerk (note) ist optional.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }Bestätigung der Lieferung
Nachdem Sie die Bestellung als "An den Kunden geliefert" markiert haben, bitten wir den Kunden um eine Bestätigung, dass er die Bestellung tatsächlich erhalten hat. Wenn die Bestellung als eingegangen markiert ist, wird dieser Endpunkt aufgerufen.
POST /order/$slevomatId/confirm-delivery
{}Verweigerung der Annahme
POST /order/$slevomatId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }
Änderung des Auftragsstatus in "Bereit zur persönlichen Abholung"
Dieser Endpunkt wird aufgerufen, wenn der previous Status "Bereit zur persönlichen Abholung" mit autoMarkReadyForPickuptrue gesetzt wurde und der Auftrag auf der Slevomat-Seite automatisch auf "Bereit zur persönlichen Abholung" umgestellt wurde.
POST /order/$slevomatId/delivery-ready-for-pickup
{}Ändern Sie den Status der Bestellung auf "An den Kunden ausgeliefert – Kundenbestätigung erwartet".
Dieser Endpunkt wird aufgerufen, wenn der previous Status "Unterwegs", "Bereit zur persönlichen Abholung" oder "Bereit zur persönlichen Abholung" mit autoMarkDeliveredtrue gesetzt wurde und der Auftrag auf der Slevomat-Seite automatisch in den Status "An Kunde ausgeliefert – wartet auf Kundenbestätigung" umgeschaltet wurde.
POST /order/$slevomatId/mark-delivered
{}Kommunikationspartner ⇒ Slevomat
Dieser Teil der API ist auf der Slevomat-Seite implementiert und wird vom Partnersystem aufgerufen.
Die Root-URL der API lautet
https://www.slevomat.cz/zbozi-api/v1PHP-Bibliothek
Um diese Seite der API zu implementieren, können Sie die vorbereitete PHP-Bibliothek verwenden. Die Bibliothek erfordert derzeit PHP 5.4 oder höher und erfordert die Verwendung von Composer.
Anweisungen zur Verwendung der Bibliothek und der Quellcode sind auf GitHub zu finden.
Autorisierung anfordern
Wenn die API aktiviert ist, erhält der Partner partner_token und api_secret, mit denen er sich beim Aufruf der Slevomat API authentifizieren kann.
Diese Parameter werden in den Headern X-PartnerToken und X-ApiSecret übergeben.
Test-Schnittstelle
Die Stamm-URL der Testschnittstelle lautet
https://www.slevomat.cz/zbozi-api/v1-testAuf ihr können alle Aktionen wie auf der Live-Oberfläche aufgerufen werden.
Die Testschnittstelle prüft die Autorisierung von Anfragen (Korrektheit des Partner-Tokens und des API-Geheimnisses) und die Gültigkeit der eingehenden Anfragekörper (JSON). In diesen Punkten verhält sie sich identisch zur Live-API.
Die Testschnittstelle arbeitet jedoch nicht mit tatsächlichen Aufträgen. Sie prüft also nicht, ob ein Auftrag zwischen den richtigen Zuständen wechselt und ob er Positionen mit den angegebenen IDs enthält. Sobald die Autorisierung und die Formularvalidierung der Anfrage bestanden sind, gibt die Testschnittstelle immer einen Erfolgscode von 200 oder 204 aus.
Erstellen einer Stornierung
Erzeugt eine Stornierung von Auftragspositionen in der angegebenen Menge. Wenn der Auftrag komplett storniert werden soll, werden alle Positionen mit der entsprechenden Menge aufgelistet.
Einzelne Positionen können auch teilweise storniert werden (z. B. 1 von 2).
Ein Stornovermerk (note) ist optional.
POST /bestellung/$slevomatId/cancel
{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }Auftragsstatus auf "Pending" ändern
POST /bestellung/$slevomatId/mark-pending
{}Bestellstatus in "Unterwegs" ändern
Für eine Bestellung kann über den Parameter autoMarkDelivered festgelegt werden, ob sie nach einer festgelegten Versandzeit ("Zeit von der Lieferung bis zur Auslieferung") automatisch in den Status "An den Kunden geliefert – Kundenbestätigung erwartet" wechseln soll.
Die Antwort enthält ein aktualisiertes voraussichtliches Lieferdatum.
POST /bestellung/$slevomatId/mark-en-route
{ "autoMarkDelivered": true }Antwort 200
{ "expectedDeliveryDate": "2021–08–25" }Bestellstatus auf "Bereit zur persönlichen Abholung" ändern
Mit dem Parameter autoMarkReadyForPickup können Sie festlegen, ob der Auftrag nach Ablauf der Zeit vom Versand bis zur Zustellung für eine bestimmte Art von Annahmestelle automatisch in den Status "Bereit zur persönlichen Abholung" umgeschaltet werden soll.
Für einen Auftrag kann über den Parameter autoMarkDelivered festgelegt werden, ob er nach einer bestimmten Anzahl von Tagen für die Abholung bei einer bestimmten Art von Annahmestelle automatisch vom Status "Bereit zur persönlichen Abholung" in den Status "An Kunde geliefert – wartet auf Kundenbestätigung" wechseln soll.
Die Kombination der Parameter autoMarkReadyForPickup false und autoMarkDelivered true ist nicht zulässig. In diesem Fall wird der Fehlercode 9 zurückgegeben.
Die Antwort enthält ein aktualisiertes voraussichtliches Lieferdatum.
POST /bestellung/$slevomatId/mark-bereit-zur-abholung
{ "autoMarkReadyForPickup": true, "autoMarkDelivered": true }Antwort 200
{ "expectedDeliveryDate": "2021–08–25" }
Bestellstatus auf "Bereit zur persönlichen Abholung" ändern
Mit dem Parameter autoMarkDelivered kann festgelegt werden, ob der Auftrag nach einer bestimmten Anzahl von Tagen für die Abholung bei einer bestimmten Art von Abholstelle automatisch in den Status "Ausgeliefert an Kunde – wartet auf Kundenbestätigung" versetzt werden soll.
POST /order/$slevomatId/mark-ready-for-pickup
{ "autoMarkDelivered": true }Den Auftragsstatus in "An den Kunden geliefert – auf Kundenbestätigung wartend" ändern
POST /order/$slevomatId/mark-delivered
{}Lieferadresse ändern
Die Lieferadresse kann nur für die Lieferung an eine Adresse geändert werden (d.h. der Ort der persönlichen Abholung kann nicht geändert werden).
Alle Schlüssel außer company sind erforderlich.
Gültige Werte für den Schlüssel state sind cz (Tschechische Republik) und sk (Slowakei).
POST /order/$slevomatId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }
03. 02. 2016
09. 11. 2015
20. 10. 2015
13. 10. 2015
24. 9. 2015
23. 9. 2015
18. 9. 2015
17. 9. 2015
10. 9. 2015
7. 9. 2015
1. 9. 2015
17. 8. 2015
2. August 2015: erste Version |