API slouží k přenosu informací o voucherech mezi Slevomatem a systémem obchodního partnera. Umožňuje, aby partner ve svém systému ověřil platnost voucherů a vouchery uplatnil. Partner tedy za tímto účelem nemusí využívat Partnerské rozhraní.
Možné příklady využití:
- Zákazník zakoupí voucher, kde je podmínkou poskytnutí služby zadání kódu na webových stránkách partnera při tvorbě objednávky. Díky API dojde po tomto zadání k okamžité kontrole platnosti voucheru. Jeho hodnota se pak odečte v košíku partnera a zároveň je voucher automaticky uplatněn u Slevomatu.
- Stejným způsobem lze také ověřovat platnost voucherů v rezervačním systému partnera či zákazníkovi nahrát zakoupený kredit v určité hodnotě přímo na webu partnera.
Partner API vyžaduje token, který je unikátní pro každého partnera a posílá se v rámci každého požadavku. Chcete-li Partner API používat, kontaktujte 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í HTTP GET požadavky, tzn. požadavek na kontrolu platnosti voucheru může vypadat například takto:
https://www.slevomat.cz/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>,
"reservationTime": <Termín rezervace, pokud je voucher rezervován; datum a čas>
}
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,
- kód 1112 (HTTP status kód 403): voucher musí být uplatněn pouze skrze rezervaci
Příklad požadavku
https://www.slevomat.cz/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í 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
- kód 1212 (HTTP status kód 403): voucher musí být uplatněn pouze skrze rezervaci
Příklad požadavku
https://www.slevomat.cz/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
}
}
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.