Zlavomat.sk Partner API

API slúži k prenosu informácií o voucheroch medzi Zľavomatom a systémom obchodného partnera. Umožňuje, aby partner vo svojom systéme overil platnosť voucherov a vouchery uplatnil. Partner teda za týmto účelom nemusí využívať Partnerské rozhranie či mobilnú aplikáciu.

Možné príklady využitia:

  • Zákazník zakúpi voucher, kde je podmienkou poskytnutia služby zadanie kódu na webových stránkach partnera pri tvorbe objednávky. Vďaka API dôjde po tomto zadaní k okamžitej kontrole platnosti voucheru. Jeho hodnota sa potom odpočíta v košíku partnera a zároveň je voucher automaticky uplatnený v Zľavomate.
  • Rovnakým spôsobom sa dá taktiež overovať platnosť voucherov v rezervačnom systéme partnera či zákazníkovi nahrať zakúpený kredit v určitej hodnote priamo v mobilnej aplikácii či na webe partnera.

Partner API vyžaduje token, který je unikátny pre každého partnera a posiela sa v rámci každej požiadavky. Ak chcete Partner API používať, kontaktujte svojho/nášho obchodníka.

Formát požadavku

Přístupový bod API se nachází na adrese /api.

Formát požadavku je

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

Všechny požadavky jsou standardní HTTP GET požadavky, tzn. požadavek na kontrolu platnosti voucheru může vypadat například takto:

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

Formát odpovědi

Odpověď serveru je vždy ve formátu JSON s odpovídající hlavičkou Content-type. Základní struktura odpovědi je následující.

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

Hodnota položky result je true (v případě úspěchu) nebo false (v případě chyby). V případě chyby obsahuje položka error kód chyby (code) a její popis (message). Kromě indikace v poli error vrací systém v případě chyby odpovídající HTTP status kód (400, 401, 403, 404).

Položka data obsahuje údaje vrácené volanou akcí a její obsah je individuální.

Všechna data jsou ve formátu YYYY-MM-DDTHH:MM:SSZ (ISO8601; např. 2011–01–01T10:10:10+0­2:00).

Ověření platnosti voucheru

  • akce: voucherCheck
  • parametry: token (povinný; unikátní token partnera), code (povinný; kód voucheru)

Existují tři testovací kódy voucherů:

  • 1234–5677–77–111 (zaplacený, nepoužitý),
  • 2234–5688–88–222 (zaplacený, použitý),
  • 3234–5699–99–333 (nezaplacený, nepoužitý).

Pokud aplikace použije jeden z těchto kódů, vrátí server odpovídající odpověď (v případě zaplaceného a nepoužitého voucheru vrátí i ukázková data voucheru a akce).

Formát dat odpovědi

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

Parametr voucherData obsahuje definici voucheru v následujícím formátu.

{
 "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>
}

Položky variant resp. variantName obsahují ID resp. název objednané varianty akce, pokud daná akce obsahuje varianty. Pokud ne, mají oba atributy hodnotu NULL.

Chybové stavy

  • kód 1101 (HTTP status kód 400): nebyl zadán autentizační token nebo kód voucheru,
  • kód 1102 (HTTP status kód 403): daný token není v databázi,
  • kód 1103 (HTTP status kód 404): voucher s daným kódem neexistuje,
  • kód 1104 (HTTP status kód 401): objednávka, na základě které byl voucher vystaven, nebyla zaplacena,
  • kód 1105 (HTTP status kód 401): voucher už byl uplatněn,
  • kód 1106 (HTTP status kód 401): voucher byl refundován,
  • kód 1107 (HTTP status kód 401): objednávka nebo voucher byly stornovány,
  • kód 1108 (HTTP status kód 401): akce už byla partnerovi vyúčtovaná; není možné uplatňovat další vouchery,
  • kód 1109 (HTTP status kód 401): platnost voucherů této akce ještě nezačala.
  • kód 1111 (HTTP status kód 500): interní chyba serveru

Příklad požadavku

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

Příklad odpovědi

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

Uplatnění voucheru

  • akce: voucherApply
  • parametry: token (povinný; unikátní token partnera), code (povinný; kód voucheru)

Pokusí se uplatnit voucher daného kódu.

Pro testovací účely je možné použít číslo testovacího voucheru. V tom případě k uplatnění voucheru nedojde, ale systém vrátí odpověď, jako by k němu došlo.

Formát dat odpovědi

Formát odpovědi je úplně stejný jako v případě kontroly platnosti voucheru.

Chybové stavy

  • kód 1201 (HTTP status kód 400): nebyl zadán autentizační token nebo kód voucheru,
  • kód 1202 (HTTP status kód 403): daný token není v databázi,
  • kód 1203 (HTTP status kód 404): voucher s daným kódem neexistuje,
  • kód 1204 (HTTP status kód 401): objednávka, na základě které byl voucher vystaven, nebyla zaplacena,
  • kód 1205 (HTTP status kód 401): voucher už byl uplatněn,
  • kód 1206 (HTTP status kód 401): voucher byl refundován,
  • kód 1207 (HTTP status kód 401): objednávka nebo voucher byly stornovány,
  • kód 1208 (HTTP status kód 401): akce už byla partnerovi vyúčtovaná; není možné uplatňovat další vouchery,
  • kód 1209 (HTTP status kód 401): platnost voucherů této akce ještě nezačala.
  • kód 1211 (HTTP status kód 500): interní chyba serveru

Příklad požadavku

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

Příklad odpovědi

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

Upozornění: Pro využívání Partner API k odečtu hodnoty nebo produktů v košíku zvažte zahrnutí více atributů parametru voucherData. Je to důležité zejm. v okamžiku, kdy máte několik běžících akcí s odlišnou hodnotou nabízených produktů. Doporučujeme využít především atributů product nebo variant.

PHP knihovna pro ověřování a uplatňování Voucherů

Jako ukázku napojení na Partner API a pro usnadnění integrace práce s vouchery do aplikací třetích stran jsme připravili jednoduchou PHP knihovnu. Vyžaduje PHP 5.2 nebo novější s rozšířením cURL.

Příklad použití

require_once 'Slevomat/Client/Partner.php';

$token = '...'; // token partnera
$voucherCode = '...'; // kód voucheru

// Instance klienta API; můžete si zvolit, zda komunikovat se Slevomat.cz nebo Zľavomat.sk
$client = new Slevomat_Client_Partner(Slevomat_Client_Partner::SERVER_CZ, $token);

// Ověření/uplatnění voucheru; návratová hodnota je boolean
// (voucher je/není platný resp. byl/nebyl uplatněn)
// a v proměnné $response je objekt s kompletní odpovědí serveru
$result = $client->checkVoucher($voucherCode, $response);
$result = $client->applyVoucher($voucherCode, $response);

// Obě metody je možné volat i bez druhého parametru,
// pokud vás zajímá pouze odpověď ano/ne
$result = $client->checkVoucher($voucherCode);
$result = $client->applyVoucher($voucherCode);

Pokud zavoláte zmíněné metody s druhým parametrem, uloží se do něj objekt s celou odpovědí serveru. Tato odpověď může být instancí třídy Slevomat_Clien­t_Response_Suc­cess (v případě úspěchu, tzn. voucher je platný resp. byl uplatněn) a Slevomat_Clien­t_Response_Fa­ilure (v případě neúspěchu, tzn. voucher není platný resp. nebyl uplatněn). Tyto objekty vám umožní získat podrobnější informace o voucheru, který byl kontrolován resp. uplatněn nebo chybě, ke které přitom došlo.

Knihovna je uložena v repozitáři na GitHubu, kde je uložena i její dokumentace. Odtud si můžete stáhnout její aktuální verzi, případně můžete kliknout na jedno z tlačítek níže.

Stáhnout aktuální verzi knihovny (ZIP)

Stáhnout aktuální verzi knihovny (TAR.GZ)