Slevomat.cz Partner API

Die API wird verwendet, um Informationen über Gutscheine zwischen Slevomat und dem System des Geschäftspartners 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 verwenden.

Mögliche Beispiele für die Verwendung:

• Ein Kunde kauft einen Gutschein, bei dem die Leistung an die Eingabe eines Codes auf der Website des Partners bei der Erstellung der Bestellung gebunden ist. Dank der API wird die Gültigkeit des Gutscheins unmittelbar nach dieser Eingabe geprüft. Der Wert des Gutscheins wird dann vom Warenkorb des Partners abgezogen und der Gutschein wird automatisch bei Slevomat eingelöst.
• Genauso ist es möglich, die Gültigkeit von Gutscheinen im Buchungssystem des Partners zu prüfen oder ein gekauftes Guthaben eines bestimmten Wertes direkt auf der Website des Partners 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, kontaktieren Sie bitte Ihren/unseren Vertriebsmitarbeiter.

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.slevomat.cz/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.

Fehlerzustände

• 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 in Anspruch genommen werden,
• Code 1109 (HTTP-Statuscode 401): Die Gutscheine für diese Veranstaltung haben noch nicht begonnen, gültig zu sein,
• Code 1111 (HTTP-Statuscode 500): Interner Serverfehler,
• Code 1112 (HTTP-Statuscode 403): der Gutschein kann nur über eine Reservierung eingelöst werden

Beispiel-Anfrage

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: 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 der Gutschein-Gültigkeitsprüfung.

Fehlerbedingungen

• Code 1201 (HTTP-Statuscode 400): Es wurde kein Authentifizierungstoken oder Gutscheincode eingegeben,
• Code 1202 (HTTP-Statuscode 403): Das Token befindet sich 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
• Code 1212 (HTTP-Statuscode 403): der Gutschein kann nur über die Reservierung eingelöst werden

Beispiel-Anfrage

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: Wenn Sie die Partner-API verwenden möchten, um den Wert oder die Produkte in Ihrem Einkaufswagen abzuziehen, sollten Sie mehrere Attribute für den Parameter voucherData angeben. Dies ist besonders wichtig, wenn Sie mehrere laufende Werbeaktionen mit unterschiedlichem Wert der angebotenen Produkte haben. Wir empfehlen insbesondere die Verwendung von Produkt- oder Variantenattributen.