Ez az API arra szolgál, hogy a Slevomat.cz-nek egy utalványkódot adjon meg, miután a vásárló kifizette a rendelést egy üzletért. Általában a Slevomat.cz saját utalványkódot generál, de ennek az API-nak a használatával üzleti partnerünk tudomást szerezhet a megrendelésről, és saját, egyedi utalványkódot generálhat az ügyfél számára.
Minden kérés HTTPS protokollon keresztül történik (ami megköveteli, hogy az üzleti partner szervere támogassa a HTTPS-t és érvényes tanúsítvánnyal rendelkezzen), és minden adatot JSON formátumban kell megformázni.
Changelog
01. 03. 2017 – az érvénytelen kérések kezelése szakasz hozzáadva.
10. 02. 2017 – kezdeti verzió
Az API engedélyezése
Minden kérést a Slevomat.cz alkalmazás végez, amely kérést küld a partner szerverére. A kérés tartalmazza a X-RequestToken HTTP fejlécet egy titkos karakterlánccal. Ezt a karakterláncot a partner szerverének ellenőriznie kell a biztonság garantálása érdekében. Ezt a titkos karakterláncot csak a Slevomat.cz és a partner ismeri.
Az API engedélyezéséhez a partnernek meg kell kérdeznie a Slevomat.cz-t és meg kell adnia egy URL-t, ahol az API található, például:
https://example.com/slevomat-external-voucher-code/generate
Miután a Slevomat.cz engedélyezi az API-t a partner számára, és megadja a partner számára a X-RequestToken értéket, az csak tesztelési üzemmódban van, ami azt jelenti, hogy semmilyen valódi megrendelés nem fog kérést végrehajtani az egyedi utalványkód megszerzésére. De lehetővé teszi a partner számára, hogy a X-RequestToken megadott értékkel fejlessze és tesztelje az API-t a saját szerverén.
Miután az API a partner szerverén kifejlesztésre és tesztelésre került, a Slevomat.cz átállítja az üzemmódot valós megrendelésekre. A váltás után értékesítésre indított ajánlatok megrendelései a partner API-jától kérnek majd egyedi utalványkódokat.
Utalványkód generálása
Amikor egy üzletre vonatkozó megrendelés kifizetésre kerül, a Slevomat.cz egy POST kérést küld a partner szerverére, hogy generáljon egy utalványkódot, és megadja a partner számára a megrendeléssel kapcsolatos információkat. Ez a kérés minden egyes eladott egységre külön-külön kerül elküldésre.
A kérés tartalmazza a szükséges utalványkód előtagot. A generált utalványkódnak ezzel az előtaggal kell kezdődnie.
A kérelem teste így fog kinézni:
{ "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 }A szervernek 200-as HTTP státuszkóddal kell válaszolnia, és a választestnek a generált utalványkóddal a következőképpen kell kinéznie:
{ "voucherCode": "LIN1234567890" }A kiszolgálónak 10 másodpercen belül válaszolnia kell, különben a kérés sikertelennek minősül. A generált utalványkódnak egy adott előtaggal kell kezdődnie, és egyedinek kell lennie. Vannak más okok is, amelyek miatt nem fogadjuk el a generált utalványkódot.
Ha a kérés nem sikeres, a kérés megismétlődik a repeatReason mezőben szereplő okkal, amíg sikeres nem lesz. Ez a mező a következő értékek egyikét tartalmazza:
| Ismétlés oka | Leírás |
|---|---|
| 1 | Első kísérlet. |
| 2 | A kapcsolat a kiszolgálóval nem volt sikeres. Ez vagy azt jelenti, hogy a HTTPS tanúsítvány érvénytelen, vagy azt, hogy a hálózat nem működött. |
| 3 | A szerver nem válaszolt időben. |
| 4 | A kiszolgáló nem 200-as HTTP státuszkóddal válaszolt. |
| 5 | A kiszolgáló HTTP 200-zal válaszolt, de a válasz teste nem tartalmazott JSON-t, vagy a JSON nem tartalmazta a voucherCode kulcsot. |
| 6 | A generált utalványkód nem tartalmazta a szükséges előtagot. |
| 7 |
A generált utalványkód érvénytelen karaktereket tartalmazott. Csak a következő karakterek érvényesek: [a-zA-Z0-9-]+.
|
| 8 | A generált utalványkód nem volt egyedi. |
A kérelem teste mindig ugyanazt a uuid azonosítót tartalmazza, mint a previous kérés, amely az utalványkód generálására vonatkozik ugyanarra az ügyfélrendelésre.
Érvénytelen kérés kezelése
Ha olyan kérés érkezik, amely nem felel meg a biztonsági követelményeknek, azaz érvénytelen X-RequestToken címet tartalmaz, a kiszolgálónak a 403 Forbidden HTTP kóddal kell válaszolnia.
Az API megvalósításának tesztelése
Jelentkezzenbe partnerként, hogy láthassa API státuszát, valamint tesztelhesse és ellenőrizhesse API implementációját.