Slevomat.cz Partner API

Die API wird verwendet, um Informationen über Gutscheine zwischen Zľavomat und dem System des Geschäftspartners zu übertragen. Sie ermöglicht es dem Partner, die Gültigkeit von Gutscheinen zu überprüfen und Gutscheine innerhalb seines eigenen Systems einzulösen. Daher muss der Partner zu diesem Zweck nicht das Partner-Interface verwenden.

Mögliche Anwendungsbeispiele:

• Ein Kunde kauft einen Gutschein, bei dem die Eingabe des Codes auf der Website des Partners erforderlich ist, um die Dienstleistung bei der Bestellung bereitzustellen. Dank der API wird die Gültigkeit des Gutscheins sofort nach Eingabe des Codes überprüft. Sein Wert wird dann im Warenkorb des Partners abgezogen und gleichzeitig wird der Gutschein automatisch bei Zľavomat eingelöst.
• Die Gültigkeit von Gutscheinen kann auch im Reservierungssystem des Partners auf die gleiche Weise überprüft werden, oder das gekaufte Guthaben eines bestimmten Wertes kann direkt dem Kundenkonto auf der Website des Partners gutgeschrieben werden.

Die Partner-API erfordert ein Token, das für jeden Partner einzigartig ist und mit jeder Anfrage gesendet wird. Wenn Sie die Partner-API verwenden möchten, wenden Sie sich an Ihren/unseren Vertriebsmitarbeiter.

Anfrageformat

Der API-Endpunkt befindet sich unter /api.

Das Anfrageformat ist

<API endpoint URL>/<action>[<parameters>]

Alle Anfragen sind standardmäßige HTTP-GET-Anfragen, d. h. eine Anfrage zur Überprüfung der Gültigkeit eines Gutscheins kann wie folgt aussehen:

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Antwortformat

Die Serverantwort ist immer im JSON-Format mit dem entsprechenden Content-Type-Header. Die Grundstruktur der Antwort ist wie folgt.

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Der Wert des Elements result ist true (im Erfolgsfall) oder false (im Fehlerfall). Im Fehlerfall enthält das Element error den Fehlercode (code) und dessen Beschreibung (message). Zusätzlich zur Angabe im Fehlerfeld gibt das System im Fehlerfall auch den entsprechenden HTTP-Statuscode (400, 401, 403, 404) zurück.

Das Element data enthält die von der aufgerufenen Aktion zurückgegebenen Daten und dessen Inhalt ist individuell.

Alle Datumsangaben sind im Format JJJJ-MM-TTTHH:MM:SSZ (ISO8601; z. B. 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Gutschein-Gültigkeitsprüfung

• action: voucherCheck
• Parameter: token (erforderlich; einzigartiges Partner-Token), code (erforderlich; Gutscheincode)

Es gibt drei Test-Gutscheincodes:

• 1234⁠–⁠5677⁠–⁠77⁠–⁠111 (bezahlt, unbenutzt),
• 2234⁠–⁠5688⁠–⁠88⁠–⁠222 (bezahlt, benutzt),
• 3234⁠–⁠5699⁠–⁠99⁠–⁠333 (unbezahlt, unbenutzt).

Wenn die Anwendung einen dieser Codes verwendet, gibt der Server die entsprechende Antwort zurück (im Fall eines bezahlten und unbenutzten Gutscheins werden auch Beispiel-Gutschein- und Aktionsdaten zurückgegeben).

Antwortdatenformat

{
 "token": <authentication token>,
 "code": <voucher code>,
 "voucherData": <voucher data>
}

Der Parameter voucherData enthält die Gutschein-Definition im folgenden Format.

{
 "id": <voucher ID>,
 "orderId": <order ID>,
 "title": <voucher name>,
 "ordered": <order date and time; date and time>,
 "paidDate": <order payment date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code>,
 "product": <action ID>,
 "productName": <action name>,
 "variant": <action variant ID>,
 "variantName": <action variant name>,
 "imageUrl": <image URL>,
 "smallImageUrl": <thumbnail URL>,
 "productUrl": <action URL>
}

Die Elemente variant und variantName enthalten die ID und den Namen der bestellten Aktionsvariante, falls die jeweilige Aktion Varianten enthält. Falls nicht, haben beide Attribute den Wert NULL.

Fehlerzustände

• Code 1101 (HTTP-Statuscode 400): Authentifizierungs-Token oder Gutscheincode wurde nicht angegeben,
• Code 1102 (HTTP-Statuscode 403): Das angegebene Token befindet sich nicht in der Datenbank,
• Code 1103 (HTTP-Statuscode 404): Gutschein mit dem angegebenen Code existiert nicht,
• Code 1104 (HTTP-Statuscode 401): Die Bestellung, auf deren Grundlage der Gutschein ausgestellt wurde, wurde nicht bezahlt,
• Code 1105 (HTTP-Statuscode 401): Der Gutschein wurde bereits eingelöst,
• Code 1106 (HTTP-Statuscode 401): Der Gutschein wurde erstattet,
• Code 1107 (HTTP-Statuscode 401): Die Bestellung oder der Gutschein wurde storniert,
• Code 1108 (HTTP-Statuscode 401): Die Aktion wurde bereits mit dem Partner abgerechnet; es können keine weiteren Gutscheine eingelöst werden,
• Code 1109 (HTTP-Statuscode 401): Die Gültigkeit der Gutscheine für diese Aktion hat noch nicht begonnen.
• Code 1111 (HTTP-Statuscode 500): interner Serverfehler

Anfragebeispiel

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Antwortbeispiel

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Gutscheineinlösung

• action: voucherApply
• Parameter: token (erforderlich; einzigartiges Partner-Token), code (erforderlich; Gutscheincode)

Versucht, den Gutschein mit dem angegebenen Code einzulösen.

Zu Testzwecken kann die Test-Gutscheinnummer verwendet werden. In diesem Fall wird der Gutschein tatsächlich nicht eingelöst, aber das System gibt eine Antwort zurück, als ob er eingelöst worden wäre.

Antwortdatenformat

Das Antwortformat ist genau das gleiche wie bei der Gutschein-Gültigkeitsprüfung.

Fehlerzustände

• Code 1201 (HTTP-Statuscode 400): Authentifizierungs-Token oder Gutscheincode wurde nicht angegeben,
• Code 1202 (HTTP-Statuscode 403): Das angegebene Token befindet sich nicht in der Datenbank,
• Code 1203 (HTTP-Statuscode 404): Gutschein mit dem angegebenen Code existiert nicht,
• Code 1204 (HTTP-Statuscode 401): Die Bestellung, auf deren Grundlage der Gutschein ausgestellt wurde, wurde nicht bezahlt,
• Code 1205 (HTTP-Statuscode 401): Der Gutschein wurde bereits eingelöst,
• Code 1206 (HTTP-Statuscode 401): Der Gutschein wurde erstattet,
• Code 1207 (HTTP-Statuscode 401): Die Bestellung oder der Gutschein wurde storniert,
• Code 1208 (HTTP-Statuscode 401): Die Aktion wurde bereits mit dem Partner abgerechnet; es können keine weiteren Gutscheine eingelöst werden,
• Code 1209 (HTTP-Statuscode 401): Die Gültigkeit der Gutscheine für diese Aktion hat noch nicht begonnen.
• Code 1211 (HTTP-Statuscode 500): interner Serverfehler

Anfragebeispiel

https://www.zlavomat.sk/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Antwortbeispiel

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Hinweis: Für die Verwendung der Partner-API zum Abzug von Wert oder Produkten im Warenkorb sollten Sie in Erwägung ziehen, weitere Attribute des Parameters voucherData einzubeziehen. Dies ist besonders wichtig, wenn Sie mehrere laufende Aktionen mit unterschiedlichen Werten der angebotenen Produkte haben. Wir empfehlen insbesondere die Verwendung der Attribute product oder variant.