Slevomat.cz Partner API

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

Mögliche Anwendungsbeispiele:

• Der Kunde kauft einen Gutschein. Voraussetzung für die Erbringung der Dienstleistung ist die Eingabe des Codes auf der Website des Partners bei der Bestellung. Dank der API wird nach dieser Eingabe sofort die Gültigkeit des Gutscheins geprüft. Der Wert wird dann vom Warenkorb des Partners abgezogen und der Gutschein automatisch bei Zlavomot eingelöst.
• Ebenso kann die Gültigkeit von Gutscheinen auch im Reservierungssystem des Partners überprüft werden oder der Kunde kann ein erworbenes Guthaben in einer bestimmten Höhe direkt auf der Website des Partners aufladen.

Die Partner-API erfordert ein Token, das für jeden Partner eindeutig ist und mit jeder Anfrage gesendet wird. Wenn Sie die Partner-API nutzen möchten, wenden Sie sich bitte an Ihren/unseren Händler.

Anforderungsformat

Der API-Zugriffspunkt befindet sich unter /api.

Das Anforderungsformat ist

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

Bei allen Anfragen handelt es sich um Standard-HTTP-GET-Anfragen, d. h. die Anfrage zur Überprüfung der Gültigkeit des Gutscheins kann beispielsweise so aussehen:

https://www.zlavomat.sk/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 das Fehlerelement den Fehlercode ( code ) und dessen 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.

Gutscheingültigkeitsprüfung

• Aktion: GutscheinCheck
• Parameter: Token (Pflichtfeld; eindeutiges 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 die entsprechende Antwort zurück (im Falle eines bezahlten und nicht verwendeten Gutscheins werden auch Beispielgutschein- und Aktionsdaten zurückgegeben).

Antwortdatenformat

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

Der Parameter voucherData enthält die Gutscheindefinition im folgenden 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>
}

Variantenelemente oder variantName enthalten die ID oder den Namen der bestellten Variante der Aktion, sofern die angegebene Aktion Varianten enthält. Andernfalls sind beide Attribute NULL .

Fehlerzustände

• Code 1101 (HTTP-Statuscode 400): Es wurde kein Authentifizierungstoken oder Gutscheincode eingegeben,
• Code 1102 (HTTP-Statuscode 403): Das angegebene Token ist nicht in der Datenbank vorhanden.
• 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 verwendet,
• 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 Aktion wurde dem Partner bereits in Rechnung gestellt; die Anwendung anderer Gutscheine ist nicht möglich,
• 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

Beispiel einer Anfrage

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

Beispielantwort

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

Gutscheineinlösung

• Aktion: Gutschein anwenden
• Parameter: Token (Pflichtfeld; eindeutiges Partner-Token), Code (Pflichtfeld; Gutscheincode)

Es wird versucht, den Gutschein des angegebenen Codes einzulösen.

Es besteht die Möglichkeit, die Nummer des Testgutscheins zu Testzwecken zu verwenden. In diesem Fall wird der Gutschein nicht eingelöst, das System gibt aber eine Rückmeldung zurück, als wäre dies geschehen.

Antwortdatenformat

Das Format der Antwort ist genau dasselbe wie bei der Überprüfung der Gültigkeit des Gutscheins.

Fehlerzustände

• Code 1201 (HTTP-Statuscode 400): Es wurde kein Authentifizierungstoken oder Gutscheincode eingegeben,
• Code 1202 (HTTP-Statuscode 403): Das angegebene Token ist nicht in der Datenbank vorhanden,
• 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 verwendet,
• 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 Aktion wurde dem Partner bereits in Rechnung gestellt; die Anwendung anderer Gutscheine ist nicht möglich,
• 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

Beispiel einer Anfrage

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

Beispielantwort

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

Hinweis: Um die Partner-API zum Auslesen des Warenkorbwerts oder der Produkte zu verwenden, sollten Sie weitere Attribute des VoucherData-Parameters hinzufügen. Dies ist besonders wichtig, wenn Sie mehrere laufende Kampagnen mit unterschiedlichen Produktwerten haben. Wir empfehlen, hauptsächlich die Produkt- oder Variantenattribute zu verwenden.