API partnerov Slevomat.cz

API slúži na prenos informácií o poukážkach medzi Slevomatom a systémom obchodného partnera. Umožňuje partnerovi overiť si platnosť poukážok vo svojom systéme a poukážky uplatniť. Partner na tento účel nemusí používať partnerské rozhranie.

Možné príklady použitia:

• Zákazník si zakúpi poukážku, kde je služba podmienená zadaním kódu na stránke partnera pri vytváraní objednávky. Vďaka API je po tomto zadaní ihneď skontrolovaná platnosť poukážky. Hodnota poukážky sa následne odpočíta z košíka partnera a poukážka sa automaticky uplatní na Slevomate.
• Rovnakým spôsobom je možné skontrolovať aj platnosť poukážok v rezervačnom systéme partnera alebo priamo na stránke partnera nahrať zakúpený kredit v určitej hodnote.

Partner API vyžaduje token, ktorý je jedinečný pre každého partnera a je odoslaný ako súčasť každej žiadosti. Ak chcete používať Partner API, kontaktujte svojho/nášho obchodného zástupcu.

Formát žiadosti

Prístupový bod API sa nachádza na /api.

Formát žiadosti je

<URL přístupového bodu>/<akce>[<pa­rametry>]

Všetky požiadavky sú štandardné požiadavky HTTP GET, tj požiadavka na kontrolu platnosti voucheru môže vyzerať takto:

https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Formát odpovede

Odpoveď servera je vždy vo formáte JSON s príslušnou hlavičkou Content-type. Základná štruktúra odpovede je nasledovná.

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Hodnota výslednej položky je true (v prípade úspechu) alebo false (v prípade chyby). V prípade chyby záznam chyby obsahuje kód chyby (kód ) a jej popis (správa ). Okrem indikácie v poli chyby systém v prípade chyby vráti zodpovedajúci stavový kód HTTP (400, 401, 403, 404).

Údajová položka obsahuje údaje vrátené volanou akciou a jej obsah je individuálny.

Všetky údaje sú vo formáte RRRR-MM-DDTHH:MM:SSZ (ISO8601; napr. 2011–01–01T10:10:10+02:00).

Overenie voucheru

• akcia: voucherSkontrolujte
• parametre: token (povinný; jedinečný partnerský token), kód (povinný; kód voucheru)

Existujú tri kódy testovacích kupónov:

• 1234–5677–77–111 (zaplatené, nepoužité),
• 2234–5688–88–222 (zaplatené, použité),
• 3234–5699–99–333 (nezaplatené, nepoužité).

Ak aplikácia používa jeden z týchto kódov, server vráti zodpovedajúcu odpoveď (v prípade zaplateného a nevyužitého voucheru vráti aj vzorový voucher a údaje o udalosti).

Formát údajov odpovede

{
 "token": <auth token>,
 "code": <voucher code>,
 "voucherData": <voucher data>
}

Parameter voucherData obsahuje definíciu voucheru v nasledujúcom formáte.

{
 "id": <Voucher ID>,
 "orderId": <Order ID>,
 "title": <voucher title>,
 "ordered": <order date and time; datetime>,
 "paidDate": <order paid date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code,
 "product": <promotion ID>,
 "productName": <promotion title>,
 "variant": <variant ID>,
 "variantName": <variant title>,
 "imageUrl": <URL image>,
 "smallImageUrl": <URL image>,
 "productUrl": <URL image>,
 "reservationTime": <Reservation time if voucher is reserved; datetime>
}

Chybové stavy

• Kód 1101 (stavový kód HTTP 400): nebol zadaný overovací token alebo kód voucheru,
• Kód 1102 (stavový kód HTTP 403): token nie je v databáze,
• kód 1103 (stavový kód HTTP 404): voucher s daným kódom neexistuje,
• kód 1104 (HTTP stavový kód 401): objednávka, na ktorú bol poukaz vystavený, nebola uhradená,
• kód 1105 (stavový kód HTTP 401): poukážka už bola uplatnená,
• kód 1106 (stavový kód HTTP 401): poukázka bola vrátená,
• kód 1107 (stavový kód HTTP 401): objednávka alebo voucher boli zrušené,
• kód 1108 (stavový kód HTTP 401): udalosť už bola partnerovi vyúčtovaná; nie je možné reklamovať ďalšie poukážky,
• kód 1109 (stavový kód HTTP 401): poukazy na toto podujatie ešte nezačali platiť,
• kód 1111 (stavový kód HTTP 500): interná chyba servera,
• kód 1112 (stavový kód HTTP 403): voucher je potrebné uplatniť iba prostredníctvom rezervácie

Príklad žiadosti

https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Príklad odpovede

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Uplatnenie voucheru

• Akcia: voucherPoužiť
• parametre: token (povinný; jedinečný partnerský token), kód (povinný; kód voucheru)

Pokusy o uplatnenie poukazu daného kódu.

Číslo testovacieho poukazu je možné použiť na testovacie účely. V takom prípade nebude voucher preplatený, ale systém vráti odpoveď, ako keby bol uplatnený.

Formát údajov odpovede

Formát odpovede je úplne rovnaký ako pri kontrole platnosti voucheru.

Chybové stavy

• Kód 1201 (stavový kód HTTP 400): nebol zadaný žiadny overovací token alebo kód voucheru,
• Kód 1202 (stavový kód HTTP 403): token nie je v databáze,
• kód 1203 (stavový kód HTTP 404): voucher s daným kódom neexistuje,
• kód 1204 (stavový kód HTTP 401): objednávka, na ktorú bol poukaz vystavený, nebola uhradená,
• kód 1205 (stavový kód HTTP 401): voucher už bol uplatnený,
• kód 1206 (stavový kód HTTP 401): poukázka bola vrátená,
• kód 1207 (stavový kód HTTP 401): objednávka alebo voucher boli zrušené,
• kód 1208 (stavový kód HTTP 401): udalosť už bola partnerovi vyúčtovaná; nie je možné reklamovať ďalšie poukážky,
• kód 1209 (stavový kód HTTP 401): platnosť poukazov na túto udalosť ešte nezačala vypršať,
• kód 1211 (stavový kód HTTP 500): interná chyba servera
• kód 1212 (stavový kód HTTP 403): voucher je potrebné uplatniť iba prostredníctvom rezervácie

Príklad žiadosti

https://www.slevomat.cz/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Príklad odpovede

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Poznámka: Ak chcete použiť partnerské rozhranie API na odpočítanie hodnoty alebo produktov v košíku, zvážte zahrnutie viacerých atribútov parametra voucherData. Je to dôležité najmä vtedy, keď máte viacero bežiacich akcií s rôznou hodnotou ponúkaných produktov. Odporúčame použiť najmä atribúty produktu alebo variantu.