API Waren von Drittanbietern

Die API dient der Übertragung von Bestellinformationen zwischen Discountomat und dem System des Handelspartners. Die API erfordert die Implementierung einer zweiseitigen Kommunikation – die API des Partners wird vom Discount-System aufgerufen und der Partner ruft die API Discount.

Bei Aufträgen, die in die Partner-API exportiert werden, ist es nicht mehr möglich in der Schnittstelle des Partners manipuliert werden, sondern nur noch eingesehen werden. Die Manipulation von exportierten Aufträgen kann nur noch über die API.

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

API-Zugang

Sie können auf die API über die Registerkarte Einstellungen in Ihrer Partner-Schnittstelle. Um die Daten zu erhalten, müssen Sie den Stammcode eingeben URL des Partnerteils der API zur Verwendung in der Richtung Zlevomat → Partner, z. B..

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

Die Zugangsdaten werden nur angezeigt, wenn auf die API zugegriffen wird, lesen Sie sie sorgfältig bewahren Sie sie sorgfältig auf.

Sobald auf die API zugegriffen wird, werden neu angelegte Aufträge vom System in diese eingegeben beginnen, die Aufträge in das System zu exportieren.

Anfänglicher Datenexport

Zum Überlauf bestehender Aufträge in dem Moment, in dem die API verfügbar gemacht wird kann ein einmaliger Export nach CSV in der Partnerschnittstelle genutzt werden.

In dem Moment, in dem Sie bestehende Aufträge (erstellt vor dem API-Zugang erstellt wurden) in Ihrem eigenen System und Sie möchten mit ihnen über API arbeiten möchten, verwenden Sie die Funktion "Arbeit mit markierten Aufträgen über API starten" in der im Menü "Bulk-Aktionen mit Aufträgen".

Beschreibung der üblichen HTTP-Antworten

• 200 OK – Anfrage wurde erfolgreich bearbeitet
• 204 No Content – Die Anfrage wurde erfolgreich bearbeitet, Antwort hat keinen Inhalt
• 400 Bad Request – Anfrage ist ungültig – möglicherweise fehlende oder ungültige Parameter entgegen der Spezifikation
• 403 Forbidden – Client-Autorisierung fehlgeschlagen
• 404 Not Found – angeforderter Endpunkt oder Daten wurden nicht gefunden
• 405 Method Not Allowed – der Endpunkt unterstützt nicht diese HTTP-Protokollmethode nicht
• 422 Unprocessable Entity – erwarteter Fehler bei der Verarbeitung der Anfrage (siehe Abschnitt Fehlerbedingungen )
• 500 Internal Server Error – ein Fehler ist auf der Seite aufgetreten Server
• 502 Bad Gateway – ein serverseitiger Fehler ist aufgetreten
• 503 Service Unavailable – der Server befindet sich im Wartungsmodus (neue Version oder geplante Ausfallzeit kann im Gange sein)
• 504 Gateway Timeout – ein Fehler ist auf der Serverseite aufgetreten Server

HTTP 5×x-Antworten dürfen nicht das JSON-Format verwenden.

Im Falle von 4xx Fehlern liegt der Fehler in der ausgehenden Anfrage und muss vor dem erneuten Versuch korrigiert werden.

Fehler 5xx weisen auf Serverfehler hin und die Anfrage kann kann ohne Änderung erneut versucht werden. Im Falle von 503 sollte der Aufrufer den Antwort-Header Retry-After beachten und den nächsten Versuch erst wiederholen, wenn die in der Kopfzeile angegebene Zeit verstrichen ist.

Zustände von Aufträgen

Ein Auftrag befindet sich immer in einem der folgenden Zustände:

Statuswert	Beschreibung
1	Neue bezahlte Bestellung
2	In Bearbeitung
3	Unterwegs (nur Bestellungen mit Versand)
4	In Vorbereitung zur persönlichen Abholung – z. B. auf dem Weg zur Filiale
5	Bereit zur persönlichen Abholung
6	Ausgeliefert an den Kunden – wartet auf die Bestätigung des Kunden
7	Ausgeliefert und vom Kunden bestätigt
8	Kunde weigert sich, den Erhalt der Bestellung zu bestätigen
9	Bestellung storniert

Der Kunde wird über jede Änderung des Status per E‑Mail informiert.

Die Bestellung muss nicht unbedingt alle Status durchlaufen, um erfolgreich zu sein Es ist möglich, direkt vom Status "Neue bezahlte Bestellung" zu zu "Auf dem Weg" / "Abholbereit" und dann zu "An den Kunden geliefert – Kundenbestätigung steht noch aus". Die Verwendung von aller Status führt jedoch zu einer besseren Kundeninformation über den Fortschritt der Auftragsabwicklung und ist daher empfehlenswert.

Fehlerzustände

Im Falle von 4×x HTTP-Codes enthält die Antwort immer einen Schlüssel status (siehe Codeliste unten) und das Feld messages mit Textbeschreibungen zu den Fehlern.

Status Wert	Beschreibung
1	Ungültige Anfrage – fehlende oder ungültige Werte
2	Ungültige Anmeldeinformationen
3	Nicht vorhandener Auftrag
4	Nicht existierende Auftragsposition
5	Übergang des Auftrags in einen unzulässigen 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 ist nicht kann nicht über die API manipuliert werden
9	Um automatisch den Status "Ware an Kunde geliefert" zu setzen zu setzen, ist es notwendig, dass die Sendung automatisch in den Status "Ware bereit bereit zur Abholung" zu setzen.

Beispiel:

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

Datentypen

Die Datentypen der einzelnen Schlüssel in den Requests und Responses sind sind immer für bestimmte Endpunkte beschrieben. Wenn nicht anders angegeben, ist der Wert in Anführungszeichen "" immer ein obligatorischer String. Wenn nicht ist der numerische Wert immer eine obligatorische Ganzzahl.

Kommunikationsdiskontomat ⇒ Partner

Dieser Teil der API ist auf der Seite des Partners implementiert und wird von Zlevomat Aufrufen.

Die benötigte API-Root-URL wird vom Partner freigegeben, sie sollte in der Form

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

Autorisierung anfordern

Wenn die API aktiviert ist, erhält der Partner partner_api_se­cret, die werden die eingehenden Anfragen daraufhin überprüft, ob sie tatsächlich von Rabatt.

Dieser Parameter wird im HTTP-Header übergeben X-PartnerApiSecret .

Testschnittstelle

Discountomat enthält Funktionen, um die API auf der Partnerseite aufzurufen und die Antwort anzuzeigen. An die vom Partner beim Zugriff auf die API angegebene Root-URL -test wird an die URL des Partners angehängt, so dass sie im Test API bei z. B.

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

aufgerufen wird, um eine Vermischung von Testdaten mit Live-Aufträgen zu vermeiden.

Das Testen der Partner-API erfolgt über 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 Auftragsstatus in "Geliefert an Kunde – wartet auf Bestätigung durch den Kunden"

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

   – Auftragsstatus ändern in "Bereit zur persönlichen Abholung".

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

   – Bestätigung der Lieferung

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

   – Verweigerung der Annahme

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

   – Stornierung

Ersetzen Sie den <orderId> Teil der URL durch eine beliebige Zahl Auftragsnummer, mit dieser Auftragsnummer werden die Anfragen an den API-Partner weitergeleitet.

Anfragen an diese Testschnittstelle müssen autorisiert werden mit den Kopfzeilen X-PartnerToken und X-ApiSecret.

Bei einem Testaufruf an die Partner-API sendet das System den Header X-PartnerApiSecret genau wie im Echtbetrieb.

Die mit einem neuen Auftrag gesendeten Daten sind Testdaten und zufällig generiert.

Bei der Übermittlung einer Auftragsstornierung wird der POST-Body der Anfrage das JSON-Feld items (im gleichen Format wie bei der von der API gesendet), das von der Testschnittstelle validiert und an die Partner-API gesendet wird. Die API wird es im gleichen Format weiterleiten.

Neuer Auftrag

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

Aufträge haben immer eine eindeutige zlavomatId. Wenn die API ein Duplikat zlavomatId eintrifft, sollte die Anfrage ignorieren (die erste konvertierte Anfrage wurde von Discountomat als fehlgeschlagen bewertet und also wiederholen wir sie) und antworten ebenfalls mit HTTP 204.

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

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

Das optionale internalId bezeichnet die interne ID, die beim Variante einer Aktion beim Anlegen in der Partnerschnittstelle. Dient zur Identifizierung des Produkts im System des Partners.

In billingAddress (Rechnungsadresse) ist nur der Name (name) des Kunden.

In shippingAddress (Lieferadresse) ist die Angabe der Firma optional (company). Im Falle einer Lieferung an shippingAddress die Adresse des Kunden, bei persönlicher die Adresse der Einrichtung, in der der Kunde die Waren abholt.

Der Schlüssel delivery.type kann folgende Werte annehmen address (Zustellung an Adresse) oder pickup (persönliche Abholung) annehmen. delivery.name enthält den Namen des Transports oder den Namen des Vorgangs.

delivery.expec­tedShippingDa­te (voraussichtliches Datum der Sendung) und delivery.expec­tedDeliveryDa­te (voraussichtlicher Liefertermin) sind Daten im Format YYYY-MM-DD .

Der Schlüssel weight enthält das Gewicht des Auftrags in Kilogramm. Falls wir nicht das Gewicht aller Artikel in der Bestellung kennen, nimmt er den Wert null an.

POST /bestellung/$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 /Bestellung/$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 erwarteten Versanddaten

Wenn der Geschäftsmanager auf Anfrage des Partners die Massendaten Versandtermine für ausgewählte Bestellungen, informiert das System die Partner-API über diese Aktualisierung.

Die gesendeten Daten enthalten das Feld Auftrags-ID und das neue erwartete Datum des Versands.

POST /update-shipping-dates

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

Stornierungen

Stornierungen können sowohl auf der Rabatt- als auch auf der Partnerseite erstellt werden System erstellt werden. Dieser Endpunkt wickelt die Erstellung von Stornierungen auf der Zlavomat-Seite und deren Übertragung an das Partnersystem.

Er erstellt eine Stornierung von Bestellpositionen in der angegebenen Menge. Wenn die der gesamte Auftrag storniert wird, werden alle Positionen mit der entsprechenden Menge aufgelistet.

Einzelne Positionen können auch teilweise storniert werden (z. B. 1 Stück von zwei).

Der Stornovermerk (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 die Bestellung als "An den Kunden geliefert" markiert haben werden wir vom Kunden eine Bestätigung verlangen, dass er die Bestellung tatsächlich erhalten hat. Wenn die Bestellung als eingegangen markiert ist, wird dieser Endpunkt aufgerufen.

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

{}

Verweigerung der Annahme

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

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

Ändern Sie den Status der Bestellung auf "Abholbereit".

Dieser Endpunkt wird aufgerufen, wenn der Endpunkt previous Status "Bereit zur persönlichen Abholung" gesetzt wurde mit autoMarkRea­dyForPickuptrue und auf der Seite Rabatt der Auftrag automatisch in den Status "Bereit zur persönlichen Abholung"

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

{}

Ändern Sie den Bestellstatus auf "An den Kunden geliefert – Warten auf Kundenbestätigung"

Dieser Endpunkt wird aufgerufen, wenn der previous Status "Unterwegs", "Bereit zur persönlichen Abholung" oder "Bereit zur persönlichen Abholung" gesetzt wurde mit autoMarkDeli­veredtrue und auf der Seite Rabatt auf der Rabattseite automatisch in den Status "Ausgeliefert an Kunde – Bestätigung des Kunden erwartet".

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

{}

Kommunikationspartner ⇒ Zľavomat

Dieser Teil der API ist auf der Discountomat-Seite implementiert und ruft das Partnersystem auf.

Die Root-URL der API lautet

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

PHP-Bibliothek

Für die Implementierung dieser Seite der API ist es möglich, die vorbereitete PHP Bibliothek zu verwenden. Die Bibliothek erfordert derzeit die PHP-Version 5.4 oder höher und setzt die Verwendung des Composer-Tools voraus.

Anweisungen zur Verwendung der Bibliothek und der Quellcode sind auf GitHub zu finden.

Autorisierungsanfragen

Wenn die API aktiviert ist, erhält der Partner partner_token und api_secret , die für die Authentifizierung des Zlavomat-API-Aufrufs verwendet werden.

Diese Parameter werden in den Headern X-PartnerToken und X-ApiSecret ÜBERGEBEN.

Testschnittstelle

Die Root-URL der Testschnittstelle lautet

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

Es ist möglich, alle Aktionen auf dieser Schnittstelle wie auf der anderen Schnittstelle aufzurufen.

Die Testschnittstelle prüft die Berechtigung von Anfragen (Korrektheit Partner-Token und API-Geheimnis) und die Gültigkeit der eingehenden Request-Bodies (JSON). In diesen Punkten verhält sie sich identisch zur crisp API.

Die Testschnittstelle arbeitet jedoch nicht mit tatsächlichen Aufträgen. Sie prüft also nicht, ob eine Bestellung zwischen den richtigen Zuständen übergeht und ob Positionen mit bestimmten IDs enthält. Sobald die Autorisierung und Validierung die der Anfrage, antwortet die Testschnittstelle immer mit einem Erfolgscode 200 oder 204.

Erstellen einer Stornierung

Erstellen Sie eine Stornierung von Auftragspositionen in der angegebenen Menge. Wenn es 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 Position von zwei).

Der Stornovermerk (note) ist optional.

POST /bestellung/$slevomatId/stornieren

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

Auftragsstatus auf "In Bearbeitung" ändern

POST /bestellung/$slevomatId/mark-pending

{}

Ändern des Bestellstatus in "Unterwegs"

Wenn eine Bestellung aufgegeben wird, wird der Parameter autoMarkDelivered verwendet, um festzustellen, ob nach dem eingestellten Versandzeitraum ("Zeit von Versand bis Lieferung") automatisch in den Status "Ausgeliefert an Kunde – Warten auf Kundenbestätigung" wechseln soll.

Die Antwort enthält das aktualisierte voraussichtliche Lieferdatum.

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

{ "autoMarkDeli­vered": true }

Antwort 200

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

Ändern des Bestellstatus in "Bereit zur persönlichen Abholung"

Wenn die Bestellung den Parameter autoMarkReady­ForPickup durchläuft, um anzugeben, ob die Zeit vom Versand bis zur Zustellung für die angegebene Art der Abholstelle automatisch auf den Status "Bereit zur Abholung" umgestellt werden soll. zur persönlichen Abholung" wechseln soll.

Bei der Bestellung bestimmt der Parameter autoMarkDelivered, ob nach der eingestellten Anzahl von Tagen für die Abholung für einen bestimmten Annahmestellentyp Abholstelle automatisch vom Status "Bereit zur persönlichen Abholung" in den Status in den Status "Ausgeliefert an Kunde – Bestätigung durch durch den Kunden" wechseln soll.

Die Kombination der Parameter autoMarkReady­ForPickup false und autoMarkDelivered true ist nicht zulässig. In diesem Fall wird wird der Fehlercode 9 zurückgegeben.

Die Antwort enthält ein aktualisiertes voraussichtliches Lieferdatum.

POST /bestellung/$slevomatId/mark-bereit-zur-abholung

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

Antwort 200

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

Auftragsstatus in "Bereit zur Abholung" ändern

Wenn eine Bestellung aufgegeben wird, wird der Parameter autoMarkDelivered verwendet, um zu bestimmen, ob nach einer bestimmten Anzahl von Tagen für die Abholung für eine bestimmte Abholart Abholstelle automatisch in den Status "An den Kunden geliefert – auf Kundenbestätigung warten" wechseln soll.

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

{ "autoMarkDeli­vered": true }

Ändern Sie den Auftragsstatus in "An den Kunden geliefert – wartet auf Kundenbestätigung"

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

{}

Lieferadresse ändern

Die Lieferadresse kann nur bei der Lieferung an eine Adresse geändert werden (d.h. Sie können den Abholort nicht ändern).

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/$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" }