Toto API slúži na poskytnutie kódu voucheru Slevomat.cz po zaplatení objednávky zákazníkom. Zvyčajne Slevomat.cz generuje svoj vlastný kód voucheru, ale pomocou tohto API môže dať náš obchodný partner vedieť o objednávke a vygenerovať svoj vlastný kód voucheru pre zákazníka.
Všetky požiadavky sa vykonávajú cez protokol HTTPS (čo vyžaduje, aby server obchodného partnera podporoval HTTPS a mal platný certifikát) a všetky údaje musia byť formátované ako JSON.
Zoznam zmien
01. 03. 2017 – pridaná časť o spracovaní neplatných požiadaviek
10. 02. 2017 – pôvodná verzia
Povolenie API
Všetky požiadavky vykonáva aplikácia Slevomat.cz odoslaním požiadavky na server partnera. Požiadavka bude obsahovať HTTP hlavičku X-RequestToken s tajným reťazcom. Tento reťazec musí byť skontrolovaný serverom partnera, aby bola zaručená bezpečnosť. Tento tajný reťazec je známy len Slevomat.cz a partnerovi.
Pre aktiváciu API musí partner požiadať Slevomat.cz a poskytnúť URL adresu, na ktorej bude API, napr:
https://example.com/slevomat-external-voucher-code/generate
Keď Slevomat.cz partnerovi API povolí a poskytne mu hodnotu X-RequestToken, je to len v testovacom režime, čo znamená, že žiadne reálne objednávky nebudú vykonávať požiadavku na získanie vlastného kódu voucheru. Partnerovi však umožňuje vyvíjať a testovať API na svojom serveri s poskytnutou hodnotou X-RequestToken.
Po vyvinutí a otestovaní API na serveri partnera Slevomat.cz prepne režim na reálne objednávky. Objednávky obchodov, ktoré sa začali predávať po prepnutí, si vyžiadajú od API partnera vlastné kódy voucherov.
Generovanie kódu poukazu
Po zaplatení objednávky na obchod Slevomat.cz odošle POST požiadavku na server partnera na vygenerovanie kódu poukazu a poskytne partnerovi niektoré informácie o objednávke. Táto požiadavka bude odoslaná jednotlivo pre každú predanú jednotku.
Požiadavka obsahuje požadovanú predvoľbu kódu voucheru. Vygenerovaný kód poukazu musí začínať týmto prefixom.
Telo žiadosti bude vyzerať 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 mal odpovedať stavovým kódom HTTP 200 a telo odpovede s vygenerovaným kódom voucheru musí vyzerať takto:
{ "voucherCode": "LIN1234567890" }Server musí odpovedať do 10 sekúnd, inak sa požiadavka označí ako neúspešná. Vygenerovaný kód poukazu musí začínať daným prefixom a musí byť jedinečný. Existujú aj ďalšie dôvody, prečo nemusíme vygenerovaný kód poukazu akceptovať.
Ak žiadosť nie je úspešná, opakuje sa s uvedením dôvodu v poli repeatReason, kým nie je úspešná. Toto pole bude obsahovať jednu z nasledujúcich hodnôt:
| Dôvod opakovania | Popis |
|---|---|
| 1 | Prvý pokus. |
| 2 | Pripojenie k serveru nebolo úspešné. Môže to znamenať buď neplatný certifikát HTTPS, alebo výpadok siete. |
| 3 | Server neodpovedal včas. |
| 4 | Server odpovedal stavovým kódom HTTP iným ako 200. |
| 5 | Server odpovedal HTTP 200, ale telo odpovede neobsahovalo JSON alebo JSON neobsahoval kľúč voucherCode. |
| 6 | Vygenerovaný kód poukážky neobsahoval požadovaný prefix. |
| 7 |
Vygenerovaný kód poukazu obsahoval neplatné znaky. Jediné platné znaky sú: [a-zA-Z0-9-]+.
|
| 8 | Vygenerovaný kód poukazu nebol jedinečný. |
Telo požiadavky bude vždy obsahovať rovnaký identifikátor uuid ako požiadavka previous na vygenerovanie kódu poukážky pre tú istú objednávku zákazníka.
Spracovanie neplatnej žiadosti
Ak sa objaví požiadavka, ktorá nespĺňa bezpečnostné požiadavky, t. j. obsahuje neplatný X-RequestToken, server musí odpovedať kódom HTTP 403 Forbidden.
Testovanie implementácie API
Prihláste sa ako náš partner a pozrite si stav API a otestujte a overte implementáciu API.