PARTNERSKÝ SPRIEVODCA
Čeština Němčina Angličtina Chorvatština Maďarština Polština Slovenština Vietnamština
Úvod Praktické návody IT podpora API partnerov Slevomat.cz

API partnerov Slevomat.cz

Tento článok bol strojovo preložený.

API slúži na prenos informácií o poukážkach medzi Slevomatom a systémom obchodného partnera. Partnerovi umožňuje overiť platnosť poukážok v jeho 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 poukaz, kde je služba podmienená zadaním kódu na webovej stránke partnera pri vytváraní objednávky. Vďaka API sa po tomto zadaní okamžite skontroluje platnosť poukazu. Hodnota poukazu sa následne odpočíta z košíka partnera a poukaz sa automaticky uplatní na Slevomate.
  • Rovnakým spôsobom je možné skontrolovať platnosť poukazov aj v rezervačnom systéme partnera alebo nahrať zakúpený kredit v určitej hodnote priamo na webovej stránke partnera.

Partnerské API vyžaduje token, ktorý je pre každého partnera jedinečný a zasiela sa ako súčasť každej požiadavky. Ak chcete používať partnerské API, obráťte sa na svojho/nášho obchodného zástupcu.

Formát požiadavky

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

Formát požiadavky je 

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

Všetky požiadavky sú štandardné požiadavky HTTP GET, t. j. požiadavka na kontrolu platnosti poukazu 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 položky výsledku je true (v prípade úspechu) alebo false (v prípade chyby). V prípade chyby obsahuje položka chyby kód chyby (code) a jej popis (message). Okrem údaju v poli chyby systém v prípade chyby vráti príslušný stavový kód HTTP (400, 401, 403, 404).

Dátová 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 platnosti poukazu

  • akcia: voucherCheck
  • parametre: token (povinné; jedinečný partnerský token), kód (povinné; kód poukazu)

Existujú tri kódy testovacích poukazov:

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

Ak aplikácia použije jeden z týchto kódov, server vráti zodpovedajúcu odpoveď (v prípade zaplateného a nepoužitého poukazu vráti aj údaje o vzorovom poukaze a udalosti).

Formát údajov odpovede 

{
 "token": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

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

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Polia variant a variantName obsahujú ID alebo názov objednaného variantu udalosti, ak udalosť obsahuje varianty. Ak nie, oba atribúty sú NULL.

Chybové stavy

  • Kód 1101 (stavový kód HTTP 400): nebol zadaný autentifikačný token alebo kód kupónu,
  • Kód 1102 (stavový kód HTTP 403): token sa nenachádza v databáze,
  • kód 1103 (stavový kód HTTP 404): poukaz s daným kódom neexistuje,
  • kód 1104 (stavový kód HTTP 401): objednávka, na základe ktorej bol poukaz vystavený, nebola zaplatená,
  • kód 1105 (stavový kód HTTP 401): poukaz už bol uplatnený,
  • kód 1106 (stavový kód HTTP 401): poukaz bol preplatený,
  • kód 1107 (stavový kód HTTP 401): objednávka alebo poukaz boli zrušené,
  • kód 1108 (stavový kód HTTP 401): udalosť už bola partnerovi vyúčtovaná; ďalšie poukazy už nie je možné uplatniť,
  • kód 1109 (stavový kód HTTP 401): poukazy na túto udalosť ešte nezačali platiť,
  • kód 1111 (stavový kód HTTP 500): vnútorná chyba servera,
  • kód 1112 (stavový kód HTTP 403): poukaz sa musí uplatniť len 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 poukazu

  • Akcia: voucherApply
  • parametre: token (povinné; jedinečný partnerský token), kód (povinné; kód poukazu)

Pokúsi sa uplatniť poukaz s daným kódom.

Číslo testovacieho poukazu možno použiť na testovacie účely. V tomto prípade sa poukaz neuplatní, ale systém vráti odpoveď, ako keby bol uplatnený.

Formát údajov odpovede

Formát odpovede je presne rovnaký ako pri kontrole platnosti poukazu.

Chybové podmienky

  • Kód 1201 (stavový kód HTTP 400): nebol zadaný žiadny overovací token ani kód poukazu,
  • Kód 1202 (stavový kód HTTP 403): token sa nenachádza v databáze,
  • kód 1203 (stavový kód HTTP 404): poukaz so zadaným kódom neexistuje,
  • kód 1204 (stavový kód HTTP 401): objednávka, na základe ktorej bol poukaz vystavený, nebola zaplatená,
  • kód 1205 (stavový kód HTTP 401): poukaz už bol uplatnený,
  • kód 1206 (stavový kód HTTP 401): poukaz bol preplatený,
  • kód 1207 (stavový kód HTTP 401): objednávka alebo poukaz boli zrušené,
  • kód 1208 (stavový kód HTTP 401): udalosť už bola partnerovi vyúčtovaná; ďalšie poukazy už nie je možné uplatniť,
  • kód 1209 (stavový kód HTTP 401): platnosť poukazov na túto udalosť ešte nezačala plynúť,
  • kód 1211 (stavový kód HTTP 500): vnútorná chyba servera
  • kód 1212 (stavový kód HTTP 403): poukaz sa musí uplatniť len 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é API na odčí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 prebiehajúcich propagačných akcií s rôznou hodnotou ponúkaných produktov. Odporúčame použiť najmä atribúty produktu alebo variantu.

Späť na výpis článkov

Súvisiace články
Nahoru