Slevomat.cz Partner API

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>[<pa­rametry>]

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+0­2: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,
• 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=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
• 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=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.