Toto API slouží k poskytnutí kódu voucheru Slevomat.cz poté, co zákazník zaplatí objednávku obchodu. Obvykle Slevomat.cz generuje svůj vlastní kód voucheru, ale pomocí tohoto API lze dát vědět o objednávce našemu obchodnímu partnerovi a vygenerovat mu vlastní kód voucheru pro zákazníka.
Všechny požadavky se provádějí přes protokol HTTPS (což vyžaduje, aby server obchodního partnera podporoval HTTPS a měl platný certifikát) a všechna data musí být formátována jako JSON.
Seznam změn
01. 03. 2017 – přidána sekce pro zpracování neplatných požadavků
10. 02. 2017 – původní verze
Povolení API
Všechny 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 serverem partnera zkontrolován, aby byla zaručena bezpečnost. Tento tajný řetězec zná pouze Slevomat.cz a partner.
Pro aktivaci API musí partner požádat Slevomat.cz a uvést URL adresu, kde bude API např:
https://example.com/slevomat-external-voucher-code/generate
Jakmile Slevomat.cz partnerovi API povolí a předá mu hodnotu X-RequestToken, je pouze v testovacím režimu, což znamená, že žádná reálná objednávka neprovede požadavek na získání vlastního kódu voucheru. Partnerovi však umožní vyvinout a otestovat API na svém serveru s poskytnutou hodnotou X-RequestToken.
Po vyvinutí a otestování API na serveru partnera Slevomat.cz přepne režim na reálné objednávky. Objednávky obchodů, které se začaly prodávat po přepnutí, si 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ždou prodanou jednotku zvlášť.
Požadavek obsahuje požadovanou předponu kódu voucheru. Vygenerovaný kód voucheru musí začínat tímto prefixem.
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 daným prefixem a musí být jedinečný. Existují 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:
| Důvod opakování | Popis |
|---|---|
| 1 | První pokus. |
| 2 | Připojení k serveru nebylo úspěšné. To může znamenat buď neplatný certifikát HTTPS, nebo výpadek sítě. |
| 3 | Server neodpověděl včas. |
| 4 | Server odpověděl stavovým kódem HTTP jiným než 200. |
| 5 | Server odpověděl protokolem HTTP 200, ale tělo odpovědi neobsahovalo JSON nebo JSON neobsahoval klíč voucherCode. |
| 6 | Vygenerovaný kód voucheru neobsahoval požadovanou předponu. |
| 7 |
Vygenerovaný kód voucheru obsahoval neplatné znaky. Platné jsou pouze tyto znaky: [a-zA-Z0-9-]+.
|
| 8 | Vygenerovaný kód voucheru nebyl jedinečný. |
Tělo požadavku bude vždy obsahovat stejný identifikátor uuid jako požadavek previous na vygenerování kódu poukazu pro stejnou objednávku zákazníka.
Zpracování neplatného požadavku
Pokud se objeví požadavek, který nesplňuje bezpečnostní požadavky, tj. obsahuje neplatný X-RequestToken, musí server odpovědět kódem HTTP 403 Forbidden.
Testování implementace rozhraní API
Přihlastese jako náš partner, abyste viděli stav svého API a otestovali a ověřili implementaci API.