Diese API dient dazu, Slevomat.cz einen Gutscheincode zur Verfügung zu stellen, nachdem ein Kunde eine Bestellung für ein Geschäft bezahlt hat. Normalerweise generiert Slevomat.cz seinen eigenen Gutscheincode, aber mit Hilfe dieser API kann unser Geschäftspartner über die Bestellung informiert werden und seinen eigenen Gutscheincode für den Kunden generieren.
Alle Anfragen werden über das HTTPS-Protokoll durchgeführt (was voraussetzt, dass der Server des Geschäftspartners HTTPS unterstützt und über ein gültiges Zertifikat verfügt) und alle Daten müssen als JSON formatiert werden.
Änderungsliste
01. 03. 2017 – Abschnitt zur Behandlung ungültiger Anfragen hinzugefügt
10. 02. 2017 – erste Version
Freischaltung der API
Alle Anfragen werden von der Anwendung Slevomat.cz durchgeführt, die eine Anfrage an den Server des Partners sendet. Die Anfrage enthält den HTTP-Header X-RequestToken mit einer geheimen Zeichenfolge. Diese Zeichenkette muss vom Server des Partners überprüft werden, um die Sicherheit zu gewährleisten. Diese geheime Zeichenfolge ist nur Slevomat.cz und dem Partner bekannt.
Um die API zu aktivieren, muss der Partner bei Slevomat.cz anfragen und eine URL angeben, unter der sich die API befindet, z. B:
https://example.com/slevomat-external-voucher-code/generate
Sobald Slevomat.cz die API für den Partner freigeschaltet und ihm den Wert X-RequestToken mitgeteilt hat, befindet sich die API nur im Testmodus, d.h. es werden keine echten Bestellungen ausgeführt, um einen individuellen Gutscheincode zu erhalten. Aber es ermöglicht dem Partner, die API auf seinem Server mit dem bereitgestellten X-RequestToken Wert zu entwickeln und zu testen.
Nachdem die API auf dem Server des Partners entwickelt und getestet wurde, wird Slevomat.cz den Modus auf echte Bestellungen umstellen. Bestellungen für Angebote, die nach der Umstellung in den Verkauf gehen, werden die API des Partners nach individuellen Gutscheincodes fragen.
Gutscheincode generieren
Wenn eine Bestellung für ein Geschäft bezahlt wird, sendet Slevomat.cz eine POST-Anfrage an den Server des Partners, um einen Gutscheincode zu generieren und gibt dem Partner einige Informationen über die Bestellung. Diese Anfrage wird für jede verkaufte Einheit einzeln gesendet.
Die Anfrage enthält den erforderlichen Gutscheincode-Präfix. Der generierte Gutscheincode muss mit diesem Präfix beginnen.
Der Anfragekörper sieht wie folgt aus:
{ "uuid": "91987a73-095c-4b94-bd38-f6ffd4ab86a7", "deal": { "product_id": 123, "product_name": "Aktivní dovolená: 4 až 6 dní s all inclusive v Rakousku. 2 děti do 8,9 let zdarma!", "variant_id": 456, "variant_name": "1 osoba | 4 dny (3 noci) | Období So 13. 5. – So 24. 6. 2017, Ne 27. 8. – Ne 5. 11. 2017" }, "customer": { "email": "cu******@ex*****.com" }, "voucherCodePrefix": "LIN", "repeatReason": 1 }Der Server sollte mit dem HTTP-Statuscode 200 antworten, und der Antwortkörper mit dem generierten Gutscheincode muss wie folgt aussehen:
{ "voucherCode": "LIN1234567890" }Der Server muss innerhalb von 10 Sekunden antworten, sonst wird die Anfrage als erfolglos markiert. Der generierte Gutscheincode muss mit einem bestimmten Präfix beginnen und muss eindeutig sein. Es gibt noch andere Gründe, warum wir den generierten Gutscheincode nicht akzeptieren können.
Wenn die Anfrage nicht erfolgreich ist, wird sie mit dem Grund im Feld repeatReason wiederholt, bis sie erfolgreich ist. Dieses Feld wird einen der folgenden Werte enthalten:
| Grund wiederholen | Beschreibung |
|---|---|
| 1 | Erster Versuch. |
| 2 | Die Verbindung zum Server war nicht erfolgreich. Dies kann entweder bedeuten, dass das HTTPS-Zertifikat ungültig ist oder dass das Netzwerk ausgefallen ist. |
| 3 | Der Server hat nicht rechtzeitig geantwortet. |
| 4 | Der Server antwortete mit einem HTTP-Statuscode ungleich 200. |
| 5 | Der Server antwortete mit HTTP 200, aber der Antwortkörper enthielt kein JSON oder das JSON enthielt keinen voucherCode-Schlüssel. |
| 6 | Der generierte Gutscheincode enthielt nicht das erforderliche Präfix. |
| 7 |
Der generierte Gutscheincode enthielt ungültige Zeichen. Die einzigen gültigen Zeichen sind: [a-zA-Z0-9-]+.
|
| 8 | Der erzeugte Gutscheincode war nicht eindeutig. |
Der Body der Anfrage enthält immer die gleiche uuid Kennung wie die previous Anfrage zur Generierung des Gutscheincodes für dieselbe Kundenbestellung.
Behandlung ungültiger Anfragen
Wenn eine Anfrage gestellt wird, die nicht den Sicherheitsanforderungen entspricht, d.h. ungültige X-RequestToken enthält, muss der Server mit dem HTTP-Code 403 Forbidden antworten.
Testen der API-Implementierung
Melden Sie sich als unser Partneran, um Ihren API-Status einzusehen und Ihre API-Implementierung zu testen und zu überprüfen.