Drittanbieter-API

Die API wird verwendet, um Bestellinformationen zwischen Slevomat und dem System unseres Handelspartners zu übertragen. 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.

In die Partner-API exportierte Aufträge können in der Slevomat-Partnerschnittstelle nicht mehr bearbeitet, sondern nur noch angezeigt werden. Die Bearbeitung exportierter Aufträge kann nur noch über die API erfolgen.

Alle Anfragen müssen über HTTPS erfolgen und alle Daten sind im JSON-Format.

API-Zugriff

Sie können auf die API-Anmeldeinformationen über die Registerkarte „Einstellungen“ in Ihrer Partneroberfläche zugreifen. Um die Daten abzurufen, müssen Sie die Stamm-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 einmalig beim Zugriff auf die API angezeigt, bitte bewahren Sie diese sorgfältig auf.

Sobald auf die API zugegriffen wird, beginnt das System mit dem Exportieren neu erstellter Bestellungen dorthin.

Erster Datenexport

Um bereits bestehende Bestellungen direkt beim API-Zugriff zu übernehmen, steht Ihnen im Partnerinterface ein einmaliger Export nach CSV zur Verfügung.

Wenn Sie in Ihrem eigenen System über bestehende Bestellungen (die vor der Bereitstellung der API erstellt wurden) verfügen und mit diesen über die API arbeiten möchten, verwenden Sie die Funktion „Mit markierten Bestellungen über die API arbeiten“ im Menü „Massenaktionen mit Bestellungen“.

Beschreibung gängiger 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 nicht gü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 während der Anforderungsverarbeitung (siehe Abschnitt Fehlerbedingungen )
• 500 Internal Server Error – Auf der Serverseite ist ein Fehler aufgetreten
• 502 Bad Gateway – ein serverseitiger Fehler ist aufgetreten
• 503 Service Unavailable – Der Server befindet sich im Wartungsmodus (die Bereitstellung einer neuen Version ist möglicherweise im Gange oder es ist eine Ausfallzeit geplant)
• 504 Gateway Timeout – Es ist ein serverseitiger Fehler aufgetreten

HTTP 5×x-Antworten verwenden möglicherweise nicht das JSON-Format.

Im Fall von4xx Fehler, dann liegt ein Fehler in der ausgehenden Anfrage vor, der vor einem erneuten Versuch korrigiert werden muss.

Fehler5xx weisen auf Serverfehler hin und die Anfrage kann ohne Änderung wiederholt werden. Im Falle von503 sollte der Anrufer dieRetry-After Antwortheader und versuchen Sie es erst erneut, nachdem die im Header angegebene Zeit abgelaufen ist.

Bestellstatus

Eine Bestellung befindet sich immer in einem der folgenden Status:

Über eine Statusänderung wird der Kunde per E‑Mail informiert.

Die Bestellung muss für eine erfolgreiche Auslieferung nicht zwingend alle Status durchlaufen, von „Neue Bestellung bezahlt“ ist es möglich, direkt über „Ware versandt“/„Bereit zur persönlichen Abholung“ und dann über „Beim Kunden ausgeliefert – Kundenbestätigung steht aus“. Die Nutzung aller Status führt allerdings zu einer besseren Kundeninformation über den Bestellverlauf und ist zu empfehlen.

Fehlerzustände

Bei 4×x HTTP-Codes enthält die Antwort immer den Schlüsselstatus (siehe Codebuch unten) und das Feldmessages mit Textbeschreibungen der Fehler.

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"" ist immer eine obligatorische Zeichenfolge. Sofern nicht anders angegeben, ist der numerische Wert immer eine obligatorische Ganzzahl.

Kommunikation Slevomat ⇒ Partner

Dieser Teil der API wird auf der Partnerseite implementiert und von Slevomat aufgerufen.

Die erforderliche API-Stamm-URL wird vom Partner bereitgestellt und sollte das Format haben

 https://www.example.com/slevomat-zbozi-api/v1

Autorisierung anfordern

Wenn die API aktiviert ist, erhält der Partnerpartner_api_se­cret , was beweist, dass eingehende Anfragen tatsächlich von Slevomat stammen.

Dieser Parameter wird im HTTP-Header übergebenX-PartnerApiSecret .

Testschnittstelle

Slevomat enthält Funktionen zum Aufrufen der API auf der Partnerseite und zum Anzeigen der Antwort. Die vom Partner bei der Bereitstellung der API angegebene Stamm-URL wird angehängt an-test , so dass beim Testen die API beispielsweise aufgerufen wird

https://example­.com/slevomat-zbozi-api-test

um eine Vermischung von Testdaten mit Live-Bestellungen zu vermeiden.

Das Testen der Partner-API erfolgt über POST-Anfragen an die folgenden Adressen:

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order

   – Neue Bestellung

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 

   – Massenaktualisierung der voraussichtlichen Versanddaten

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

   – Bestellstatus auf „An Kunden geliefert – Kundenbestätigung steht aus“ ändern

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

   – Bestellstatus auf „Bereit zur persönlichen Abholung“ ändern

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 

   – Lieferbestätigung

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 

   – Annahmeverweigerung

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

   – Stornierung

Ersetze das<orderId> Teil der URL mit einer beliebigen Bestellnummer, werden Anfragen an die Partner-API mit dieser Bestellnummer gestellt.

Anfragen an diese Testschnittstelle müssen mit den Headern autorisiert werdenX-PartnerToken UndX-ApiSecret .

Bei einem Testaufruf an die Partner-API sendet das System dieX-PartnerApiSecret Header wie im Live-Betrieb.

Die bei einer Neubestellung übermittelten Daten sind Testdaten und werden zufällig generiert.

Im Falle einer Stornierung der Bestellung müssen Sie dieitems Feld im POST-Text der Anfrage in JSON (im selben Format, wie es von der API gesendet wurde), das die Testschnittstelle validiert und im selben Format an die Partner-API weiterleitet.

Neue Bestellung

Die Anfrage enthält die Daten der neu erstellten Bestellung.

Bestellungen haben immer eine eindeutigeslevomatId Wenn die API ein Duplikat erhältslevomatId , 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 ebenfallsHTTP 204 .

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 WahlinternalId gibt die interne ID an, die für die Aktionsvariante beim Anlegen in der Partnerschnittstelle eingegeben wird. Sie dient zur Identifizierung des Produkts im System des Partners.

InbillingAddress (Rechnungsadresse) nur der Kundenname (name ) ist obligatorisch.

InshippingAddress (Lieferadresse) das Unternehmen (company ) ist optional. Bei Lieferung anshippingAddress Sie enthält die Anschrift des Bestellers, bei Selbstabholung die Anschrift der Niederlassung, bei der der Besteller die Ware abholt.

Der Schlüsseldelivery .type kann den Wert annehmenaddress (Lieferung an Adresse) oderpickup (persönliche Sammlung).delivery .name enthält den Namen des Transportmittels bzw. den Namen der Einrichtung.

delivery .expec­tedShippingDa­te (voraussichtliches Versanddatum) unddelivery .expec­tedDeliveryDa­te (voraussichtlicher Liefertermin) sind Daten im FormatYYYY-MM-DD .

Der Schlüsselweight enthält das Gewicht der Bestellung in Kilogramm. Wenn wir das Gewicht aller Artikel in der Bestellung nicht kennen, wird der Wertnull .

POST /order/$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", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$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ě", "expectedShip­pingDate": "2021–09–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Massenaktualisierung der voraussichtlichen Versanddaten

Wenn der Deals Manager auf Anfrage des Partners die Versanddaten ausgewählter Bestellungen verschiebt, informiert das System die Partner-API über diese Aktualisierung.

Die gesendeten Daten enthalten das Bestell-ID-Feld und das neue voraussichtliche Versanddatum.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Stornierung

Stornierungen können sowohl auf der Slevomat-Seite als auch auf dem Partnersystem erstellt werden. Dieser Endpunkt übernimmt die Erstellung der Stornierung auf der Slevomat-Seite und deren Übertragung an das System des Partners.

Es wird eine Stornierung von Bestellpositionen in der angegebenen Menge erstellt. Soll die komplette Bestellung storniert werden, werden alle Positionen mit der entsprechenden Menge aufgelistet.

Einzelne Artikel können auch teilweise storniert werden (zB 1 von 2).

Ein Stornierungshinweis (note ) es ist optional.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Lieferbestätigung

Nachdem Sie die Bestellung als „An Kunden geliefert“ markiert haben, bitten wir den Kunden, den tatsächlichen Erhalt zu bestätigen. Wenn die Bestellung als erhalten markiert ist, wird dieser Endpunkt aufgerufen.

POST /order/$slevo­matId/confirm-delivery

{}

Annahmeverweigerung

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Bestellstatus auf „Bereit zur persönlichen Abholung“ ändern

Dieser Endpunkt wird aufgerufen, wenn der vorherige Status "Bereit zur persönlichen Abholung" gesetzt wurde mitautoMarkRea­dyForPickuptrue und die Bestellung wurde auf der Slevomat-Seite automatisch auf „Bereit zur persönlichen Abholung“ umgestellt.

POST /order/$slevo­matId/delivery-ready-for-pickup

{}

Ändern Sie den Bestellstatus auf „An Kunden geliefert – Kundenbestätigung steht aus“

Dieser Endpunkt wird aufgerufen, wenn der vorherige Status "Unterwegs", "Bereit zur persönlichen Abholung" oder "Bereit zur persönlichen Abholung" gesetzt wurde mitautoMarkDeli­veredtrue und die Bestellung wurde auf der Slevomat-Seite automatisch in den Status „An Kunden geliefert – warte auf Kundenbestätigung“ umgeschaltet.

POST /order/$slevo­matId/mark-delivered

{}

Kommunikationspartner ⇒ Slevomat

Dieser Teil der API ist auf der Slevomat-Seite implementiert und wird vom Partnersystem aufgerufen.

Die Stamm-URL der API lautet

 https://www.slevomat.cz/zbozi-api/v1

PHP-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 des Quellcodes finden Sie auf GitHub .

Autorisierung anfordern

Wenn die API aktiviert ist, erhält der Partnerpartner_token Undapi_secret , die zur Authentifizierung beim Aufruf der Slevomat-API verwendet werden.

Diese Parameter werden übergeben inX-PartnerToken UndX-ApiSecret Kopfzeilen.

Testschnittstelle

Die Stamm-URL der Testoberfläche lautet

https://www.slevomat.cz/zbozi-api/v1-test

Sämtliche Aktionen sind darauf, wie auch auf der Live-Oberfläche, aufrufbar.

Die Testschnittstelle prüft die Autorisierung von Anfragen (Korrektheit des Partner-Tokens und des API-Geheimnisses) und die Gültigkeit eingehender Anfragetexte (JSON). In dieser Hinsicht verhält sie sich identisch zur Live-API.

Die Testschnittstelle funktioniert jedoch nicht mit tatsächlichen Bestellungen. Sie überprüft daher nicht, ob eine Bestellung zwischen den richtigen Zuständen wechselt und ob sie Artikel mit den angegebenen IDs enthält. Sobald die Autorisierung und Formularüberprüfung der Anfrage erfolgreich ist, stimmt die Testschnittstelle immer mit einem Erfolgscode von 200 oder 204 überein.

Erstellen einer Stornierung

Erstellt eine Stornierung von Bestellpositionen in der angegebenen Menge. Soll die Bestellung komplett storniert werden, werden alle Positionen mit der entsprechenden Menge aufgelistet.

Einzelne Artikel können auch teilweise storniert werden (zB 1 von 2).

Ein Stornierungshinweis (note ) es ist optional.

POST /Bestellung/$slevomatId/Abbrechen

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Bestellstatus auf „Ausstehend“ ändern

POST /order/$slevomatId/als ausstehend markieren

{}

Bestellstatus auf „Ware versendet“ ändern

Bei einer Bestellung wird derautoMarkDelivered Über den Parameter kann festgelegt werden, ob nach einer einstellbaren Versandzeit („Zeit zwischen Versand und Zustellung“) automatisch in den Status „An Kunde geliefert – Bestätigung durch Kunde ausstehend“ gewechselt werden soll.

Die Antwort enthält einen aktualisierten voraussichtlichen Liefertermin.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

Antwort 200

{ "expectedDeli­veryDate": "2021–08–25" }

Bestellstatus auf „Bereit zur persönlichen Abholung“ ändern

Sie können den ParameterautoMarkReady­ForPickup legen Sie fest, ob die Bestellung nach Ablauf der Zeit zwischen Versand und Zustellung bei einem bestimmten Abholstellentyp automatisch in den Status „Bereit zur persönlichen Abholung“ versetzt werden soll.

Bei einer Bestellung wird derautoMarkDelivered Über den Parameter kann festgelegt werden, ob nach einer festgelegten Anzahl von Tagen zur Abholung an einer bestimmten Art von Abholstelle automatisch vom Status „Bereit zur persönlichen Abholung“ in den Status „Beim Kunden zugestellt – Kundenbestätigung steht aus“ gewechselt werden soll.

Die Kombination der ParameterautoMarkReady­ForPickup falsch undautoMarkDelivered true ist nicht zulässig. In diesem Fall wird der Fehlercode 9 zurückgegeben.

Die Antwort enthält einen aktualisierten voraussichtlichen Liefertermin.

POST /order/$slevomatId/Als-Abholbereit markieren

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Antwort 200

{ "expectedDeli­veryDate": "2021–08–25" }

Bestellstatus auf „Bereit zur persönlichen Abholung“ ändern

DerautoMarkDelivered Über den Parameter „Bestellung“ kann festgelegt werden, ob die Bestellung nach einer festgelegten Anzahl von Tagen zur Abholung an einer Abholstelle eines bestimmten Typs automatisch in den Status „Beim Kunden geliefert – Kundenbestätigung steht aus“ versetzt werden soll.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Ändern Sie den Bestellstatus auf „An Kunden geliefert – Kundenbestätigung steht aus“

POST /order/$slevo­matId/mark-delivered

{}

Ändere die Lieferadresse

Eine Änderung der Lieferadresse ist nur bei Lieferung an eine Adresse möglich (d.h. eine Änderung des Ortes der persönlichen Abholung ist nicht möglich).

Alle Tasten außercompany sind erforderlich.

Gültige Werte für diestate Schlüssel sindcz (Tschechische Republik) undsk (Slowakei).

POST /order/$slevo­matId/update-shipping-address

{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }

Änderungsprotokoll