Toto API slouží k poskytnutí kódu voucheru Slevomat.cz poté, co zákazník zaplatí svou objednávku. Obvykle Slevomat.cz generuje svůj vlastní kód voucheru, ale pomocí tohoto API lze informovat o objednávce našeho obchodního partnera a ten tak může vygenerovat vlastní kód voucheru pro zákazníka.
Všechny požadavky se provádějí prostřednictvím protokolu HTTPS (což vyžaduje, aby server obchodního partnera podporoval tento protokol a měl platný certifikát). Všechna data musí být ve formátu JSON.
Seznam změn
01. 03. 2017 – přidána sekce pro zpracování neplatných požadavků
10. 02. 2017 – původní verze
Spuštění API
Veškeré požadavky provádí aplikace Slevomat.cz odesláním požadavku na server partnera. Požadavek bude obsahovat HTTP hlavičku X-RequestToken s tajným řetězcem. Tento řetězec musí být zkontrolován serverem partnera pro zajištění bezpečnosti. Tento tajný řetězec zná pouze Slevomat.cz a partner.
Pro aktivaci API musí partner požádat Slevomat.cz a poskytnout URL adresu, na které API bude např:
https://example.com/slevomat-external-voucher-code/generate
Jakmile Slevomat.cz povolí API pro partnera a předá mu hodnotu X-RequestToken, je API nastaveno nejprve pouze v testovacím režimu. To znamená, že žádná skutečná objednávka neprovede požadavek na získání vlastního kódu voucheru. Umožňuje však partnerovi vyvinout a otestovat API na svém serveru.
Po otestování API na serveru partnera Slevomat.cz přepne do ostrého režimu. Objednávky, které se začaly prodávat po přepnutí, si tak již vyžádají API partnera pro vlastní kódy voucherů.
Generování kódu voucheru
Po zaplacení objednávky na obchod odešle Slevomat.cz na server partnera POST požadavek na vygenerování kódu voucheru a předá partnerovi některé informace o objednávce. Tento požadavek bude odeslán pro každý prodaný kus zvlášť.
Požadavek obsahuje požadovanou předponu kódu voucheru. Vygenerovaný kód voucheru musí začínat touto předponou
Tělo požadavku bude vypadat takto:
{ "uuid": "91987a73-095c-4b94-bd38-f6ffd4ab86a7", "deal": { "product_id": 123, "product_name": "Aktivní dovolená: 4 až 6 dní s all inclusive v Rakousku. 2 děti do 8,9 let zdarma!", "variant_id": 456, "variant_name": "1 osoba | 4 dny (3 noci) | Období So 13. 5. – So 24. 6. 2017, Ne 27. 8. – Ne 5. 11. 2017" }, "customer": { "email": "cu******@ex*****.com" }, "voucherCodePrefix": "LIN", "repeatReason": 1 }Server by měl odpovědět stavovým kódem HTTP 200 a tělo odpovědi s vygenerovaným kódem voucheru musí vypadat takto:
{ "voucherCode": "LIN1234567890" }Server musí odpovědět do 10 sekund, jinak je požadavek označen jako neúspěšný. Vygenerovaný kód voucheru musí začínat danou předponou a musí být jedinečný. Existují zde i další důvody, proč vygenerovaný kód voucheru nemusíme přijmout.
Když požadavek není úspěšný, opakuje se s důvodem v poli repeatReason, dokud není úspěšný. Toto pole bude obsahovat jednu z následujících hodnot:
| Repeat reason | Description |
|---|---|
| 1 | První pokus. |
| 2 | Připojení na serveer nebylo úspěšné. To může znamena neplatný HTTPS certifikát nebo mohlo dojít k výpadku sítě. |
| 3 | Server neodpověděl včas. |
| 4 | Server odpověděl s jiným kódem něž 200 HTTP. |
| 5 | Server odpověděl s HTTP 200, ale tělo odpověďi neobsahovalo JSON nebo JSON neobsahoval kód voucheru. |
| 6 | Vygenerovaný kód voucheru neobsahoval povinnou předponu. |
| 7 |
Vygenerovaný kód voucheru obsahoval neplatné znaky. Platné znaky jsou: [a-zA-Z0-9-]+.
|
| 8 | Vygenerovaný kód voucheru nebyl unikátní. |
Tělo požadavku bude vždy obsahovat stejný identifikátor uuid jako předchozí požadavek na vygenerování kódu voucheru pro stejnou objednávku zákazníka.
Vyřízení neplátné žádosti
Pokud dojde k požadavku, který nesplňuje bezpečnostní požadavky, tj. obsahuje neplatný X-RequestToken, musí server odpovědět kódem HTTP 403 Forbidden.
Testování API
Přihlašte se jako náš partner. V rozhraní následně můžete zjistit stav vašeho API a případně si jej otestovat a nastavit.