API se používá k přenosu informací o poukázkách mezi Zlavomatem a systémem obchodního partnera. Umožňuje partnerovi ověřit platnost poukázek ve svém systému a uplatnit je. Partner k tomuto účelu nemusí používat partnerské rozhraní.
Možné příklady použití:
- Zákazník si zakoupí voucher, kde podmínkou poskytnutí služby je zadání kódu na webových stránkách partnera při vytváření objednávky. Díky API se po tomto zadání okamžitě ověří platnost voucheru. Jeho hodnota se následně odečte z košíku partnera a voucher se automaticky uplatní v obchodě Zlavomot.
- Stejným způsobem lze platnost voucherů ověřit i v rezervačním systému partnera nebo si zákazník může nahrát zakoupený kredit v určité hodnotě přímo na webových stránkách partnera.
Partnerské API vyžaduje token, který je jedinečný pro každého partnera a je odesílán s každým požadavkem. Pokud chcete používat Partnerské API, kontaktujte prosím svého/našeho obchodníka.
Formát požadavku
Přístupový bod API se nachází na adrese /api.
Formát žádosti je
<URL přístupového bodu>/<akce>[<parametry>]Všechny požadavky jsou standardní HTTP GET požadavky, tj. požadavek na ověření 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 typu Content-type. Základní struktura odpovědi je následující.
{
"result": true,
"data": {
...
},
"error": {
"code": 0,
"message": null
}
}
Hodnota výsledné položky je true (v případě úspěchu) nebo false (v případě chyby). V případě chyby obsahuje chybová položka kód chyby ( code ) a její popis ( message ). Kromě indikace v poli chyby systém v případě chyby vrátí odpovídající stavový kód HTTP (400, 401, 403, 404).
Datová položka obsahuje data vrácená volanou akcí a její obsah je individuální.
Všechna data jsou ve formátu RRRR-MM-DDTHH:MM:SSZ (ISO8601; např. 2011–01–01T10:10:10+02:00).
Ověření platnosti poukazu
- akce: Kontrola voucheru
- parametry: token (povinný; unikátní partnerský token), kód (povinný; kód voucheru)
Existují tři kódy poukazů na testování:
- 1234–5677–77–111 (zaplaceno, nevyužito),
- 2234–5688–88–222 (zaplacené, použité),
- 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é vzorový voucher a data o akci).
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 nebo variantName obsahují ID nebo název seřazené varianty akce, pokud daná akce obsahuje varianty. Pokud ne, oba atributy jsou NULL .
Chybové stavy
- kód 1101 (stavový kód HTTP 400): nebyl zadán ověřovací token nebo kód poukazu,
- kód 1102 (stavový kód HTTP 403): daný token se nenachází v databázi,
- kód 1103 (stavový kód HTTP 404): poukaz s daným kódem neexistuje,
- kód 1104 (stavový kód HTTP 401): objednávka, na základě které byl poukaz vystaven, nebyla uhrazena,
- kód 1105 (stavový kód HTTP 401): poukaz již byl použit,
- kód 1106 (stavový kód HTTP 401): poukaz byl vrácen,
- kód 1107 (stavový kód HTTP 401): objednávka nebo poukaz byl zrušen,
- kód 1108 (stavový kód HTTP 401): akce již byla partnerovi fakturována; nelze uplatnit další vouchery,
- kód 1109 (stavový kód HTTP 401): platnost poukazů na tuto akci ještě nezačala.
- kód 1111 (stavový kód HTTP 500): interní chyba serveru
Příklad žádosti
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": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Uplatnění poukazu
- akce: poukazPoužít
- parametry: token (povinný; unikátní partnerský token), kód (povinný; kód voucheru)
Bude proveden pokus o uplatnění poukazu s daným kódem.
Číslo testovacího poukazu je možné použít pro účely testování. V takovém případě nebude poukaz uplatněn, ale systém vrátí odpověď, jako by k uplatnění došlo.
Formát dat odpovědi
Formát odpovědi je naprosto stejný jako v případě kontroly platnosti poukazu.
Chybové stavy
- kód 1201 (stavový kód HTTP 400): nebyl zadán ověřovací token nebo kód poukazu,
- kód 1202 (stavový kód HTTP 403): daný token se nenachází v databázi,
- kód 1203 (stavový kód HTTP 404): poukaz s daným kódem neexistuje,
- kód 1204 (stavový kód HTTP 401): objednávka, na základě které byl poukaz vystaven, nebyla uhrazena,
- kód 1205 (stavový kód HTTP 401): poukaz již byl použit,
- kód 1206 (stavový kód HTTP 401): poukaz byl vrácen,
- kód 1207 (stavový kód HTTP 401): objednávka nebo poukaz byl zrušen,
- kód 1208 (stavový kód HTTP 401): akce již byla partnerovi fakturována; nelze uplatnit další vouchery,
- kód 1209 (stavový kód HTTP 401): platnost poukazů na tuto akci ještě nezačala.
- kód 1211 (stavový kód HTTP 500): interní chyba serveru
Příklad žádosti
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": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Poznámka: Chcete-li pomocí Partner API číst hodnotu produktů v košíku, zvažte zahrnutí dalších atributů parametru voucherData. To je obzvláště důležité v okamžiku, kdy máte spuštěných několik kampaní s různou hodnotou nabízených produktů. Doporučujeme používat hlavně atributy product nebo variant.