API Waren von Drittanbietern

Die API dient der Übertragung von Bestellinformationen zwischen der Discount Machine und dem System des Geschäftspartners. Die API erfordert die Implementierung einer bidirektionalen Kommunikation: Das Discount Machine-System ruft die API des Partners auf, und der Partner ruft die Discount Machine-API auf.

Über die Partner-API exportierte Bestellungen können in der Zlavomat-Partnerschnittstelle nicht mehr bearbeitet, sondern nur noch angezeigt werden. Exportierte Bestellungen können nun ausschließlich über die API bearbeitet werden.

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

API-Zugänglichkeit

Sie können auf die API im Reiter „Einstellungen“ Ihrer Partnerschnittstelle zugreifen. Um Daten abzurufen, müssen Sie die Stamm-URL des Partnerteils der API für die Verwendung in der Richtung Zlavomat → Partner eingeben, z. B.

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

Die Zugangsdaten werden nur beim Zugriff auf die API angezeigt, bewahren Sie diese daher sicher auf.

Sobald die API verfügbar ist, beginnt das System, neu erstellte Bestellungen dorthin zu exportieren.

Erster Datenexport

Um bestehende Bestellungen zum Zeitpunkt der Bereitstellung der API zu übernehmen, besteht die Möglichkeit, einen einmaligen Export nach CSV in der Partnerschnittstelle zu nutzen.

Wenn Sie bereits bestehende Bestellungen (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 „Mit markierten Bestellungen über die API arbeiten“ im Menü „Massenaktionen mit Bestellungen“.

Beschreibung gängiger HTTP-Antworten

• 200 OK – die Anfrage erfolgreich bearbeitet wurde
• 204 No Content – die Anfrage wurde erfolgreich bearbeitet, die Antwort hat keinen Inhalt
• 400 Bad Request – die Anfrage ist ungültig – möglicherweise fehlen Parameter oder sie sind ungültig im Vergleich zur Spezifikation
• 403 Forbidden – Client-Autorisierung fehlgeschlagen
• 404 Not Found – Endpunkt oder angeforderte Daten nicht gefunden
• 405 Method Not Allowed – Der Endpunkt unterstützt diese HTTP-Protokollmethode nicht
• 422 Unprocessable Entity – erwarteter Fehler bei der Verarbeitung der Anfrage (siehe Abschnitt Fehlerzustände )
• 500 Internal Server Error – Auf der Serverseite ist ein Fehler aufgetreten
• 502 Bad Gateway – Auf der Serverseite ist ein Fehler aufgetreten
• 503 Service Unavailable – Der Server befindet sich im Wartungsmodus (möglicherweise läuft gerade die Bereitstellung einer neuen Version oder es ist eine geplante Ausfallzeit im Gange)
• 504 Gateway Timeout – Auf der Serverseite ist ein Fehler aufgetreten

HTTP 5×x-Antworten müssen nicht das JSON-Format verwenden.

Im Falle von Fehlern4xx In der ausgehenden Anfrage liegt ein Fehler vor, der vor einem erneuten Versuch behoben werden muss.

Fehler5xx Serverfehler anzeigen und die Anfrage kann ohne Änderung wiederholt werden. Im Falle von503 Der Anrufer sollte den Antwortheader respektierenRetry-After und wiederholen Sie den nächsten Versuch erst nach Ablauf der im Header angegebenen Zeit.

Bestellstatus

Die Bestellung befindet sich immer in einem der folgenden Status:

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

Eine Bestellung muss nicht unbedingt alle Status durchlaufen, um erfolgreich ausgeliefert zu werden. Vom Status „Neue bezahlte Bestellung“ kann man direkt zu „Unterwegs“ / „Bereit zur persönlichen Abholung“ und dann zu „An den Kunden geliefert – Kundenbestätigung steht aus“. Die Verwendung aller Status führt jedoch zu einer besseren Kundeninformation über den Bestellverlauf und wird daher empfohlen.

Fehlerzustände

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

Probe:

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Datentypen

Die Datentypen einzelner 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 erforderliche Zeichenfolge. Sofern nicht anders angegeben, ist der numerische Wert immer eine erforderliche Ganzzahl.

Kommunikations-Rabattautomat ⇒ Partner

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

Die erforderliche API-Stamm-URL wird vom Partner weitergegeben und sollte in der Form

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

Autorisierung von Anfragen

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

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

Testschnittstelle

Der Rabattautomat bietet die Möglichkeit, die API auf Partnerseite aufzurufen und die Antwort anzuzeigen. Die vom Partner bei der Bereitstellung der API angegebene Stamm-URL ist angehängt an-test , daher wird die API im Rahmen des Tests beispielsweise aufgerufen unter

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

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

Das Testen der Partner-API erfolgt mithilfe von POST-Anfragen an die folgenden Adressen:

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Neue Bestellung

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

   – Massenaktualisierung der voraussichtlichen Versanddaten

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

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

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

   – Änderung des Bestellstatus auf „Bereit zur persönlichen Abholung“

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Lieferbestätigung

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Ablehnung der Annahme

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Stornieren

Teil der URL<orderId> durch eine beliebige Bestellnummer ersetzen, Anfragen an die Partner-API werden mit dieser Bestellnummer gestellt.

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

Beim Testen eines Partner-API-Aufrufs sendet das System einen HeaderX-PartnerApiSecret wie im Livebetrieb.

Die mit einer neuen Bestellung übermittelten Daten haben Testcharakter und werden zufällig generiert.

Beim Senden einer Auftragsstornierung muss das JSON-Feld in den POST-Anforderungstext aufgenommen werden.items (im gleichen Format, wie es die API sendet), welches die Testschnittstelle validiert und in der gleichen Form an die Partner-API weiterleitet.

Neue Bestellung

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

Bestellungen sind immer einzigartigzlavomatId Wenn ein Duplikat in der API eintrifftzlavomatId , sollte die Partner-API die Anfrage ignorieren (die erste Anfrage von Zľavomat wurde als erfolglos ausgewertet und daher wiederholen wir sie) und ebenfalls mit HTTP 204 antworten.

created ist ein Datum im ISO 8601-Format, d. h.YYYY-MM-DD'T'HH:mm:ss­+zz:zz .

productId enthält die Aktions-ID, variantId ID der gekauften Variante.

OptionalinternalId bezeichnet die interne ID, die beim Anlegen der Aktionsvariante in der Partnerschnittstelle vergeben wird. Sie dient der Identifizierung des Produkts im Partnersystem.

InbillingAddress (Rechnungsadresse) nur der Name (erforderlich)name ) des Kunden.

InshippingAddress (Lieferadresse) ist ein optionales Unternehmen (company ). Im Falle einer Lieferung an die AdresseshippingAddress enthält die Adresse des Kunden, bei Selbstabholung die Adresse der Filiale, in der der Kunde die Ware abholt.

Schlüsseldelivery .type kann Werte annehmenaddress (Lieferung an Adresse) oderpickup (persönliche Sammlung).delivery .name enthält den Namen des Transports oder den Namen der Operation.

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

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

POST /order/$slevomatId

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "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–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$slevomatId

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "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–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Massenaktualisierung der voraussichtlichen Versanddaten

Wenn der Dealmanager auf Anfrage des Partners die Versanddaten ausgewählter Bestellungen in großen Mengen verschiebt, informiert das System die Partner-API über diese Aktualisierung.

Die übermittelten Daten umfassen ein Feld mit der Bestellnummer und einem neuen voraussichtlichen Versanddatum.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Stornieren

Stornierungen können sowohl auf Zlavomat-Seite als auch auf dem Partnersystem erstellt werden. Dieser Endpunkt übernimmt die Erstellung von Stornierungen auf Zlavomat-Seite und deren Übertragung an das Partnersystem.

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

Einzelne Artikel können auch teilweise storniert werden (zB 1 Stück von zwei).

Stornierungshinweis (note ) 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 eine Bestellung als „An Kunden geliefert“ markiert haben, bitten wir den Kunden um eine Bestätigung, dass er die Bestellung tatsächlich erhalten hat. Wenn eine Bestellung als erhalten markiert ist, wird dieser Endpunkt aufgerufen.

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

{}

Ablehnung der Annahme

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

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

Ändern des Bestellstatus auf „Bereit zur persönlichen Abholung“

Dieser Endpunkt wird aufgerufen, wenn der vorherige Status "Vorbereitung für persönliche Abholung" aufautoMarkRea­dyForPickuptrue und auf der Zlavomat-Seite wurde die Bestellung automatisch in den Status "Bereit zur persönlichen Abholung" versetzt

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

{}

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

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

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

{}

Kommunikationspartner ⇒ Rabattautomat

Dieser Teil der API ist auf der Zľavomat-Seite implementiert und wird vom Partnersystem aufgerufen.

Die API-Stamm-URL lautet

https://www.zlavomat.sk/zbozi-api/v1

PHP-Bibliothek

Zur Implementierung dieser API-Seite können Sie eine vorgefertigte PHP-Bibliothek verwenden. Die Bibliothek erfordert derzeit PHP Version 5.4 oder höher und setzt die Verwendung des Composer-Tools voraus.

Die Anweisungen und der Quellcode der Bibliothek befinden sich auf GitHub .

Autorisierung von Anfragen

Wenn die API aktiviert ist, erhält der Partnerpartner_token Undapi_secret , das zum Beweisen beim Aufruf der Zlavomat-API verwendet wird.

Diese Parameter werden in Headern übergebenX-PartnerToken UndX-ApiSecret .

Testschnittstelle

Die Stamm-URL der Testschnittstelle lautet

https://www.zlavomat.sk/zbozi-api/v1-test

Es können darauf alle Aktionen aufgerufen werden wie auf der anderen Oberfläche.

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

Die Testschnittstelle funktioniert jedoch nicht mit echten Bestellungen. Sie überprüft nicht, ob die Bestellung zwischen den richtigen Status wechselt und ob sie Artikel mit den angegebenen IDs enthält. Nach erfolgreicher Autorisierung und Validierung des Anfrageformulars antwortet die Testschnittstelle immer mit einem Erfolgscode von 200 oder 204.

Erstellen einer Stornierung

Erstellen Sie Bestellstorno-Artikel in einer vorgegebenen Menge. Soll die gesamte Bestellung storniert werden, werden alle Artikel mit der entsprechenden Menge aufgelistet.

Einzelne Artikel können auch teilweise storniert werden (zB 1 Stück von zwei).

Stornierungshinweis (note ) ist optional.

POST /order/$slevomatId/cancel

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

Ändern des Bestellstatus auf „In Bearbeitung“

POST /order/$slevomatId/mark-pending

{}

Ändern des Bestellstatus auf „Unterwegs“

Bei der Bestellung ist der ParameterautoMarkDelivered Legen Sie fest, ob der Status nach der eingestellten Transportdauer („Zeit vom Versand bis zur Zustellung“) automatisch auf „Beim Kunden geliefert – Kundenbestätigung steht aus“ wechseln 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" }

Ändern des Bestellstatus auf „Vorbereitung zur persönlichen Abholung“

Bei der Bestellung ist der ParameterautoMarkReady­ForPickup Legen Sie fest, ob nach Ablauf der Zeit zwischen Versand und Zustellung für einen bestimmten Abholstellentyp der Status automatisch auf „Bereit zur persönlichen Abholung“ wechseln soll.

Bei der Bestellung ist der ParameterautoMarkDelivered Legen Sie fest, ob der Status nach der festgelegten Anzahl von Tagen zur Abholung an einem bestimmten Abholpunkttyp automatisch von „Bereit zur persönlichen Abholung“ auf „An den Kunden geliefert – Kundenbestätigung steht aus“ wechseln soll.

ParameterkombinationautoMarkReady­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/mark-getting-ready-for-pickup

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

Antwort 200

{ "expectedDeli­veryDate": "2021–09–06" }

Ändern des Bestellstatus auf „Bereit zur persönlichen Abholung“

Bei der Bestellung ist der ParameterautoMarkDelivered Legen Sie fest, ob der Status nach der festgelegten Anzahl von Tagen bis zur Abholung für einen bestimmten Abholpunkttyp automatisch auf „Beim Kunden zugestellt – Kundenbestätigung steht aus“ wechseln soll.

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

{ "autoMarkDeli­vered": true }

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

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

{}

Änderung der Lieferadresse

Eine Änderung der Lieferadresse ist nur bei Lieferung an die Adresse möglich (d.h. der Ort der Abholung kann nicht geändert werden).

Alle Schlüssel außercompany sind obligatorisch.

Gültige Werte für den Schlüsselstate 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" }