API slúži k prenosu informácií o voucheroch medzi Zľavomatom a systémom obchodného partnera. Umožňuje, aby partner vo svojom systéme overil platnosť voucherov a vouchery uplatnil. Partner teda za týmto účelom nemusí využívať Partnerské rozhranie.
Možné príklady využitia:
- Zákazník zakúpi voucher, kde je podmienkou poskytnutia služby zadanie kódu na webových stránkach partnera pri tvorbe objednávky. Vďaka API dôjde po tomto zadaní k okamžitej kontrole platnosti voucheru. Jeho hodnota sa potom odpočíta v košíku partnera a zároveň je voucher automaticky uplatnený v Zľavomate.
- Rovnakým spôsobom sa dá taktiež overovať platnosť voucherov v rezervačnom systéme partnera či zákazníkovi nahrať zakúpený kredit v určitej hodnote priamo na webe partnera.
Partner API vyžaduje token, který je unikátny pre každého partnera a posiela sa v rámci každej požiadavky. Ak chcete Partner API používať, kontaktujte svojho/nášho obchodníka.
Formát požadavku
Přístupový bod API se nachází na adrese /api.
Formát požadavku je
<URL přístupového bodu>/<akce>[<parametry>]
Všechny požadavky jsou standardní HTTP GET požadavky, tzn. požadavek na kontrolu platnosti voucheru může vypadat například 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 odpovídající hlavičkou Content-type. 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 kód chyby (code) a její popis (message). Kromě indikace v poli error vrací systém v případě chyby odpovídající HTTP status kód (400, 401, 403, 404).
Položka data obsahuje údaje vrácené volanou akcí a její obsah je individuální.
Všechna data 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ý; unikátní token partnera), code (povinný; kód voucheru)
Existují tři testovací kódy voucherů:
- 1234–5677–77–111 (zaplacený, nepoužitý),
- 2234–5688–88–222 (zaplacený, použitý),
- 3234–5699–99–333 (nezaplacený, nepoužitý).
Pokud aplikace použije jeden z těchto kódů, vrátí server odpovídající odpověď (v případě zaplaceného a nepoužitého voucheru vrátí i ukázková data voucheru a akce).
Formát dat odpovědi
{
"token": <autentizační token>,
"code": <kód voucheru>,
"voucherData": <data voucheru>
}
Parametr voucherData obsahuje definici voucheru v následujícím formátu.
{
"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>
}
Položky variant resp. variantName obsahují ID resp. název objednané varianty akce, pokud daná akce obsahuje varianty. Pokud ne, mají oba 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): daný token není v databázi,
- kód 1103 (HTTP status kód 404): voucher s daným kódem neexistuje,
- kód 1104 (HTTP status kód 401): objednávka, na základě které byl voucher vystaven, nebyla zaplacena,
- kód 1105 (HTTP status kód 401): voucher už 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 byly stornovány,
- kód 1108 (HTTP status kód 401): akce už byla partnerovi vyúčtovaná; není možné uplatňovat další vouchery,
- kód 1109 (HTTP status kód 401): platnost voucherů této akce 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=123456789012345
Příklad odpovědi
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Uplatnění voucheru
- akce: voucherApply
- parametry: token (povinný; unikátní token partnera), code (povinný; kód voucheru)
Pokusí se uplatnit voucher daného kódu.
Pro testovací účely je možné použít číslo testovacího voucheru. V tom případě k uplatnění voucheru nedojde, ale systém vrátí odpověď, jako by k němu došlo.
Formát dat odpovědi
Formát odpovědi je úplně stejný jako v případě kontroly 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): daný token není v databázi,
- kód 1203 (HTTP status kód 404): voucher s daným kódem neexistuje,
- kód 1204 (HTTP status kód 401): objednávka, na základě které byl voucher vystaven, nebyla zaplacena,
- kód 1205 (HTTP status kód 401): voucher už 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 byly stornovány,
- kód 1208 (HTTP status kód 401): akce už byla partnerovi vyúčtovaná; není možné uplatňovat další vouchery,
- kód 1209 (HTTP status kód 401): platnost voucherů této akce 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=123456789012345
Příklad odpovědi
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Upozornění: Pro využívání Partner API k odečtu hodnoty nebo produktů v košíku zvažte zahrnutí více atributů parametru voucherData. Je to důležité zejm. v okamžiku, kdy máte několik běžících akcí s odlišnou hodnotou nabízených produktů. Doporučujeme využít především atributů product nebo variant.