Slevomat.cz Partner API

Die API dient zum Übertragen von Gutscheininformationen zwischen Slevomat und dem System des Geschäftspartners. Sie ermöglicht es dem Partner, die Gültigkeit der Gutscheine in seinem System zu überprüfen und die Gutscheine einzulösen. Der Partner muss hierfür nicht die Partnerschnittstelle verwenden.

Mögliche Anwendungsbeispiele:

• Ein Kunde erwirbt einen Gutschein, bei dem die Leistung von der Eingabe eines Codes auf der Website des Partners bei der Erstellung der Bestellung abhängig ist. Dank der API wird die Gültigkeit des Gutscheins unmittelbar nach dieser Eingabe überprüft. Der Wert des Gutscheins wird dann vom Warenkorb des Partners abgezogen und der Gutschein wird automatisch bei Slevomat eingelöst.
• Auf gleichem Wege ist es auch möglich, die Gültigkeit von Gutscheinen im Buchungssystem des Partners zu prüfen oder ein erworbenes Guthaben in einer bestimmten Höhe direkt auf der Website des Partners hochzuladen.

Die Partner-API erfordert ein Token, das für jeden Partner eindeutig ist und als Teil jeder Anfrage gesendet wird. Um die Partner-API zu verwenden, wenden Sie sich bitte an Ihren/unseren Vertriebsmitarbeiter.

Anfrageformat

Der API-Zugriffspunkt befindet sich unter /api.

Das Anfrageformat ist

<URL přístupového bodu>/<akce>[<pa­rametry>]

Bei allen Anfragen handelt es sich um Standard-HTTP-GET-Anfragen, d. h. eine Anfrage zur Überprüfung der Gültigkeit eines Gutscheins könnte beispielsweise wie folgt aussehen:

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

Antwortformat

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

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

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

Das Datenelement enthält die von der aufgerufenen Aktion zurückgegebenen Daten und sein Inhalt ist individuell.

Alle Daten liegen im Format JJJJ-MM-TTTHH:MM:SSZ (ISO8601; zB 2011–01–01T10:10:10+02:00) vor.

Gutscheinvalidierung

• Aktion: GutscheinCheck
• Parameter: Token (Pflichtfeld; eindeutiger Partner-Token), Code (Pflichtfeld; Gutscheincode)

Es gibt drei Test-Gutscheincodes:

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

Wenn die Anwendung einen dieser Codes verwendet, gibt der Server eine entsprechende Antwort zurück (bei einem bezahlten und nicht genutzten Gutschein auch Beispielgutschein- und Veranstaltungsdaten).

Antwortdatenformat

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

Der Parameter couponData enthält die Gutscheindefinition im folgenden Format.

{
 "id": <Voucher ID>,
 "orderId": <Order ID>,
 "title": <voucher title>,
 "ordered": <order date and time; datetime>,
 "paidDate": <order paid date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code,
 "product": <promotion ID>,
 "productName": <promotion title>,
 "variant": <variant ID>,
 "variantName": <variant title>,
 "imageUrl": <URL image>,
 "smallImageUrl": <URL image>,
 "productUrl": <URL image>,
 "reservationTime": <Reservation time if voucher is reserved; datetime>
}

Fehlerzustände

• Code 1101 (HTTP-Statuscode 400): Es wurde kein Authentifizierungstoken oder Gutscheincode eingegeben,
• Code 1102 (HTTP-Statuscode 403): Das Token ist nicht in der Datenbank,
• Code 1103 (HTTP-Statuscode 404): Der Gutschein mit dem angegebenen Code existiert nicht,
• Code 1104 (HTTP-Statuscode 401): Die Bestellung, auf die 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 zurückerstattet,
• Code 1107 (HTTP-Statuscode 401): Die Bestellung oder der Gutschein wurde storniert,
• Code 1108 (HTTP-Statuscode 401): Die Veranstaltung wurde dem Partner bereits in Rechnung gestellt; es können keine weiteren Gutscheine in Anspruch genommen werden,
• Code 1109 (HTTP-Statuscode 401): Die Gültigkeit der Gutscheine für diese Veranstaltung hat noch nicht begonnen,
• Code 1111 (HTTP-Statuscode 500): interner Serverfehler,
• Code 1112 (HTTP-Statuscode 403): Gutschein kann nur über Reservierung eingelöst werden

Beispielanforderung

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

Beispiel einer Antwort

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Einlösen eines Gutscheins

• Aktion: GutscheinAnwenden
• Parameter: Token (Pflichtfeld; eindeutiger Partner-Token), Code (Pflichtfeld; Gutscheincode)

Versucht den Gutschein mit dem angegebenen Code einzulösen.

Die Testgutscheinnummer kann zu Testzwecken verwendet werden. In diesem Fall wird der Gutschein nicht eingelöst, das System gibt aber eine Rückmeldung als wäre er eingelöst worden.

Antwortdatenformat

Das Format der Antwort ist exakt das gleiche wie bei der Gutscheingültigkeitsprüfung.

Fehlerbedingungen

• Code 1201 (HTTP-Statuscode 400): Es wurde kein Authentifizierungstoken oder Gutscheincode eingegeben,
• Code 1202 (HTTP-Statuscode 403): Das Token ist nicht in der Datenbank,
• Code 1203 (HTTP-Statuscode 404): Der Gutschein mit dem angegebenen Code existiert nicht,
• Code 1204 (HTTP-Statuscode 401): Die Bestellung, auf die 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 zurückerstattet,
• Code 1207 (HTTP-Statuscode 401): Die Bestellung oder der Gutschein wurde storniert,
• Code 1208 (HTTP-Statuscode 401): Die Veranstaltung wurde dem Partner bereits in Rechnung gestellt; es können keine weiteren Gutscheine in Anspruch genommen werden,
• Code 1209 (HTTP-Statuscode 401): Die Gültigkeit der Gutscheine für diese Veranstaltung hat noch nicht begonnen,
• Code 1211 (HTTP-Statuscode 500): interner Serverfehler
• Code 1212 (HTTP-Statuscode 403): Gutschein kann nur über Reservierung eingelöst werden

Beispielanforderung

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

Beispiel einer Antwort

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Hinweis: Um die Partner-API zum Abziehen des Werts oder der Produkte in Ihrem Warenkorb zu verwenden, sollten Sie mehrere Attribute des VoucherData-Parameters einschließen. Dies ist insbesondere dann wichtig, wenn Sie mehrere laufende Werbeaktionen mit unterschiedlichen Produktwerten haben. Insbesondere empfehlen wir die Verwendung von Produkt- oder Variantenattributen.