API se používá k přenosu informací o voucherech mezi Zľavomat a systémem obchodního partnera. Umožňuje partnerovi ověřit platnost voucherů a uplatnit vouchery ve vlastním systému. Partner tedy nemusí za tímto účelem používat Partnerské rozhraní.
Možné příklady použití:
- Zákazník zakoupí voucher, kde je pro poskytnutí služby při zadávání objednávky nutné zadat kód na webových stránkách partnera. Díky API je platnost voucheru ověřena ihned po zadání kódu. Jeho hodnota je poté odečtena v košíku partnera a zároveň je voucher automaticky uplatněn v Zľavomat.
- Platnost voucherů lze stejným způsobem ověřit také v rezervačním systému partnera, nebo lze zakoupený kredit určité hodnoty připsat přímo na účet zákazníka na webových stránkách partnera.
Partnerské API vyžaduje token, který je jedinečný pro každého partnera a je zasílán s každým požadavkem. Pokud chcete používat Partnerské API, kontaktujte svého/našeho obchodního zástupce.
Formát požadavku
API endpoint se nachází na /api.
Formát požadavku je
<API endpoint URL>/<action>[<parameters>]Všechny požadavky jsou standardní HTTP GET požadavky, tj. požadavek na ověření platnosti voucheru může vypadat takto:
https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.Formát odpovědi
Odpověď serveru je vždy ve formátu JSON s příslušnou Content-type hlavičkou. Základní struktura odpovědi je následující.
{
"result": true,
"data": {
...
},
"error": {
"code": 0,
"message": null
}
}
Hodnota položky result je true (v případě úspěchu) nebo false (v případě chyby). V případě chyby obsahuje položka error chybový kód (code) a jeho popis (message). Kromě indikace v poli error systém v případě chyby vrací také odpovídající HTTP status kód (400, 401, 403, 404).
Položka data obsahuje data vrácená volanou akcí a její obsah je individuální.
Všechny datumy jsou ve formátu YYYY-MM-DDTHH:MM:SSZ (ISO8601; např. 2011–01–01T10:10:10+02:00).
Ověření platnosti voucheru
- akce: voucherCheck
- parametry: token (povinné; jedinečný token partnera), code (povinné; kód voucheru)
Existují tři testovací kódy voucherů:
- 1234–5677–77–111 (zaplaceno, nevyužito),
- 2234–5688–88–222 (zaplaceno, využito),
- 3234–5699–99–333 (nezaplaceno, nevyužito).
Pokud aplikace použije jeden z těchto kódů, server vrátí odpovídající odpověď (v případě zaplaceného a nevyužitého voucheru vrátí také ukázková data voucheru a akce).
Formát dat odpovědi
{
"token": <authentication token>,
"code": <voucher code>,
"voucherData": <voucher data>
}
Parametr voucherData obsahuje definici voucheru v následujícím formátu.
{
"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>
}
Položky variant a variantName obsahují ID a název objednané varianty akce, pokud daná akce obsahuje varianty. Pokud ne, mají obě atributy hodnotu NULL.
Chybové stavy
- kód 1101 (HTTP status kód 400): nebyl zadán autentizační token nebo kód voucheru,
- kód 1102 (HTTP status kód 403): zadaný token není v databázi,
- kód 1103 (HTTP status kód 404): voucher se zadaným kódem neexistuje,
- kód 1104 (HTTP status kód 401): objednávka, na jejímž základě byl voucher vydán, nebyla zaplacena,
- kód 1105 (HTTP status kód 401): voucher již byl uplatněn,
- kód 1106 (HTTP status kód 401): voucher byl refundován,
- kód 1107 (HTTP status kód 401): objednávka nebo voucher byla zrušena,
- kód 1108 (HTTP status kód 401): akce již byla s partnerem vypořádána; není možné uplatnit více voucherů,
- kód 1109 (HTTP status kód 401): platnost voucherů pro tuto akci ještě nezačala.
- kód 1111 (HTTP status kód 500): interní chyba serveru
Příklad požadavku
https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345Příklad odpovědi
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <voucher name>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Uplatnění voucheru
- akce: voucherApply
- parametry: token (povinné; jedinečný token partnera), code (povinné; kód voucheru)
Pokouší se uplatnit voucher se zadaným kódem.
Pro testovací účely je možné použít testovací číslo voucheru. V takovém případě nebude voucher skutečně uplatněn, ale systém vrátí odpověď, jako by byl.
Formát dat odpovědi
Formát odpovědi je zcela stejný jako v případě ověření platnosti voucheru.
Chybové stavy
- kód 1201 (HTTP status kód 400): nebyl zadán autentizační token nebo kód voucheru,
- kód 1202 (HTTP status kód 403): zadaný token není v databázi,
- kód 1203 (HTTP status kód 404): voucher se zadaným kódem neexistuje,
- kód 1204 (HTTP status kód 401): objednávka, na jejímž základě byl voucher vydán, nebyla zaplacena,
- kód 1205 (HTTP status kód 401): voucher již byl uplatněn,
- kód 1206 (HTTP status kód 401): voucher byl refundován,
- kód 1207 (HTTP status kód 401): objednávka nebo voucher byla zrušena,
- kód 1208 (HTTP status kód 401): akce již byla s partnerem vypořádána; není možné uplatnit více voucherů,
- kód 1209 (HTTP status kód 401): platnost voucherů pro tuto akci ještě nezačala.
- kód 1211 (HTTP status kód 500): interní chyba serveru
Příklad požadavku
https://www.zlavomat.sk/api/voucherapply?code=1234-5677-77-111&token=123456789012345Příklad odpovědi
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <voucher name>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Poznámka: Pro použití Partnerského API k odečtení hodnoty nebo produktů v košíku zvažte zahrnutí více atributů parametru voucherData. To je zvláště důležité, pokud máte několik probíhajících akcí s různými hodnotami nabízených produktů. Doporučujeme používat zejména atributy product nebo variant.