API slouží k přenosu informací o voucheru mezi systémem Discountomat a systémem obchodníka. Umožňuje partnerovi ověřit platnost poukázek v jeho systému a poukázky uplatnit. Partner k tomuto účelu nemusí používat partnerské rozhraní.
Možné příklady použití:
- Zákazník si zakoupí poukaz, přičemž podmínkou služby je zadání kódu na webových stránkách partnera při vytváření objednávky. Díky rozhraní API se po tomto zadání okamžitě zkontroluje platnost poukazu. Jeho hodnota se pak odečte v košíku partnera a zároveň se voucher automaticky uplatní v systému Discountomat.
- Stejným způsobem je možné ověřit platnost poukazů i v rezervačním systému partnera nebo nahrát zakoupený kredit v určité hodnotě zákazníkovi přímo na webu partnera.
Partnerské API vyžaduje token, který je pro každého partnera jedinečný a je zasílán jako součást každého požadavku. Chcete-li používat rozhraní API pro partnery, obraťte se na svého/našeho 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í požadavky HTTP GET, tj. požadavek na ověření platnosti poukazu 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 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 výsledku 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ě údaje v poli chyby vrací systém v případě chyby odpovídající stavový kód HTTP (400, 401, 403, 404).
Datová položka obsahuje údaje vrácené volanou akcí a její obsah je individuální.
Všechny údaje jsou ve formátu RRRR-MM-DDTHH:MM:SSZ (ISO8601; např. 2011–01–01T10:10:10+02:00).
Ověření platnosti poukazu
- akce: voucherCheck
- parametry: token (povinný; jedinečný partnerský token), kód (povinný; kód voucheru)
Existují tři zkušební 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ů, server vrátí odpovídající odpověď (v případě zaplaceného a nevyužitého poukazu vrátí také vzorový poukaz a údaje o události).
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>
}
Pole variant a variantName obsahují ID nebo název objednané varianty události, pokud událost obsahuje varianty. Pokud ne, jsou oba atributy NULL.
Chybové podmínky
- Kód 1101 (stavový kód HTTP 400): nebyl zadán ověřovací token nebo kód voucheru,
- Kód 1102 (stavový kód HTTP 403): token není 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 kterou byl poukaz vystaven, nebyla zaplacena,
- kód 1105 (stavový kód HTTP 401): poukaz již byl proplacen,
- kód 1106 (stavový kód HTTP 401): poukaz byl proplacen,
- kód 1107 (stavový kód HTTP 401): objednávka nebo poukaz byly zrušeny,
- kód 1108 (stavový kód HTTP 401): událost již byla partnerovi vyúčtována; další poukazy již nelze uplatnit,
- kód 1109 (stavový kód HTTP 401): platnost poukazů pro tuto událost ještě nezačala vypršet.
- kód 1111 (stavový kód HTTP 500): vnitřní 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": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Uplatnění poukazu
- Akce: voucherApply
- parametry: token (povinný; jedinečný partnerský token), kód (povinný; kód poukazu)
Pokusí se uplatnit poukaz s daným kódem.
Číslo testovacího poukazu lze použít pro testovací účely. V tomto případě nebude poukaz uplatněn, ale systém vrátí odpověď, jako by byl uplatněn.
Formát dat odpovědi
Formát odpovědi je naprosto stejný jako v případě kontroly platnosti poukazu.
Chybové podmínky
- 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): token není 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 kterou byl poukaz vystaven, nebyla zaplacena,
- kód 1205 (stavový kód HTTP 401): poukaz již byl proplacen,
- kód 1206 (stavový kód HTTP 401): poukaz byl proplacen,
- kód 1207 (stavový kód HTTP 401): objednávka nebo poukaz byly zrušeny,
- kód 1208 (stavový kód HTTP 401): událost již byla partnerovi vyúčtována; další poukazy již nelze uplatnit,
- kód 1209 (stavový kód HTTP 401): platnost poukazů pro tuto událost ještě nezačala vypršet.
- kód 1211 (stavový kód HTTP 500): vnitřní 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": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Poznámka: Chcete-li použít rozhraní Partner API k odečtení hodnoty nebo produktů v košíku, zvažte, zda do parametru voucherData zahrnout více atributů. To je důležité, zejména pokud chcete použít parametr voucher. To je důležité, pokud máte více běžících akcí s různými hodnotami produktů. Zejména doporučujeme používat atributy produktu nebo varianty.