Slevomat.cz Partner API

Die API wird verwendet, um Gutscheininformationen zwischen Discountomat und dem System des Händlers zu übertragen. 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 dazu nicht die Partnerschnittstelle nutzen.

Mögliche Beispiele für die Verwendung:

• Ein Kunde erwirbt einen Gutschein, bei dem die Bedingung für die Leistung die Eingabe eines Codes auf der Website des Partners bei der Erstellung der Bestellung ist. Dank der API wird der Gutschein nach dieser Eingabe sofort auf seine Gültigkeit geprüft. Sein Wert wird dann im Warenkorb des Partners abgezogen und gleichzeitig wird der Gutschein automatisch im Discountomat eingelöst.
• Genauso ist es möglich, die Gültigkeit von Gutscheinen im Buchungssystem des Partners zu überprüfen oder ein gekauftes Guthaben eines bestimmten Wertes direkt auf der Website des Partners an den Kunden hochzuladen.

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

Anfrageformat

Der API-Zugangspunkt befindet sich unter /api.

Das Anfrageformat ist

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

Alle Anfragen sind Standard-HTTP-GET-Anfragen, d.h. eine Anfrage zur Überprüfung der Gültigkeit eines Gutscheins könnte wie folgt aussehen:

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

Antwortformat

Die Antwort des Servers erfolgt 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 Ergebniselements ist true (im Falle eines Erfolgs) oder false (im Falle eines Fehlers). Im Falle eines Fehlers enthält der Fehlereintrag den Fehlercode(code) und seine Beschreibung(message). Neben der Angabe im Fehlerfeld wird im Fehlerfall auch der entsprechende HTTP-Statuscode (400, 401, 403, 404) zurückgegeben.

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

Alle Daten sind im Format JJJJ-MM-TTTHH:MM:SSZ (ISO8601; z. B. 2011–01–01T10:10:10+02:00).

Validierung von Belegen

• Aktion: voucherCheck
• Parameter: Token (obligatorisch; eindeutiger Partner-Token), Code (obligatorisch; Gutscheincode)

Es gibt drei Test-Gutscheincodes:

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

Verwendet die Anwendung einen dieser Codes, gibt der Server die entsprechende Antwort zurück (im Falle eines bezahlten und nicht eingelösten Gutscheins werden auch Mustergutschein- und Ereignisdaten zurückgegeben).

Format der Antwortdaten

{
 "token": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

Der Parameter voucherData enthält die Gutscheindefinition in folgendem Format.

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Die Felder variant und variantName enthalten die ID oder den Namen der bestellten Variante des Ereignisses, wenn das Ereignis Varianten enthält. Wenn nicht, sind beide Attribute NULL.

Fehlerbedingungen

• Code 1101 (HTTP-Statuscode 400): Authentifizierungstoken oder Gutscheincode wurde nicht eingegeben,
• Code 1102 (HTTP-Statuscode 403): Das Token befindet sich nicht in der Datenbank,
• Code 1103 (HTTP-Statuscode 404): Der Gutschein mit dem angegebenen Code existiert nicht,
• Code 1104 (HTTP-Statuscode 401): Die Bestellung, für die der Gutschein ausgestellt wurde, wurde noch 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 beansprucht werden,
• Code 1109 (HTTP-Statuscode 401): die Gutscheine für diese Veranstaltung haben noch nicht begonnen zu verfallen.
• Code 1111 (HTTP-Statuscode 500): Interner Serverfehler

Beispiel-Anfrage

https://www.zlavomat.sk/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: voucherApply
• Parameter: Token (obligatorisch; eindeutiger Partner-Token), Code (obligatorisch; 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, aber das System gibt eine Antwort zurück, als ob er eingelöst worden wäre.

Format der Antwortdaten

Das Format der Antwort ist genau dasselbe wie bei einer Gutschein-Gültigkeitsprüfung.

Fehlerbedingungen

• Code 1201 (HTTP-Statuscode 400): Das Authentifizierungstoken oder der Gutscheincode wurde nicht 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, für die der Gutschein ausgestellt wurde, wurde noch 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 Gutscheine für diese Veranstaltung haben noch nicht begonnen zu verfallen.
• Code 1211 (HTTP-Statuscode 500): Interner Serverfehler

Beispiel-Anfrage

https://www.zlavomat.sk/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: Wenn Sie die Partner-API verwenden möchten, um den Wert oder die Produkte in Ihrem Warenkorb abzuziehen, sollten Sie mehrere Attribute in den Parameter voucherData aufnehmen. Dies ist besonders wichtig, wenn Sie den Parameter voucher verwenden möchten. Dies ist wichtig, wenn Sie mehrere laufende Werbeaktionen mit unterschiedlichen Produktwerten haben. Wir empfehlen insbesondere die Verwendung von Produkt- oder Variantenattributen.