Slevomat.cz Partnerski API

API se koristi za prijenos informacija o vaučerima između Zľavomat-a i sustava poslovnog partnera. Omogućuje partneru provjeru valjanosti vaučera i iskorištavanje vaučera unutar vlastitog sustava. Stoga partner ne mora koristiti Sučelje za partnere u tu svrhu.

Mogući primjeri korištenja:

• Kupac kupuje vaučer kod kojeg je potrebno unijeti kod na web stranici partnera kako bi se usluga omogućila prilikom narudžbe. Zahvaljujući API-ju, valjanost vaučera provjerava se odmah nakon unosa koda. Njegova vrijednost se tada oduzima u košarici partnera i istovremeno se vaučer automatski iskorištava u Zľavomat-u.
• Valjanost vaučera može se također provjeriti u partnerskom rezervacijskom sustavu na isti način, ili se kupljeni kredit određene vrijednosti može izravno pripisati na korisnički račun na web stranici partnera.

Partner API zahtijeva token koji je jedinstven za svakog partnera i šalje se sa svakim zahtjevom. Ako želite koristiti Partner API, kontaktirajte svog/našeg prodajnog predstavnika.

Format zahtjeva

API endpoint se nalazi na /api.

Format zahtjeva je

<API endpoint URL>/<action>[<parameters>]

Svi zahtjevi su standardni HTTP GET zahtjevi, tj. zahtjev za provjeru valjanosti vaučera može izgledati ovako:

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

Format odgovora

Odgovor servera je uvijek u JSON formatu s odgovarajućom Content-type zaglavljem. Osnovna struktura odgovora je sljedeća.

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

Vrijednost stavke result je true (u slučaju uspjeha) ili false (u slučaju pogreške). U slučaju pogreške, stavka error sadrži kod pogreške (code) i njegov opis (message). Osim naznake u polju error, sustav također vraća odgovarajući HTTP status kod (400, 401, 403, 404) u slučaju pogreške.

Stavka data sadrži podatke koje vraća pozvana akcija i njezin sadržaj je individualan.

Svi datumi su u formatu YYYY-MM-DDTHH:MM:SSZ (ISO8601; npr., 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Provjera valjanosti vaučera

• akcija: voucherCheck
• parametri: token (obavezno; jedinstveni token partnera), code (obavezno; kod vaučera)

Postoje tri testna koda vaučera:

• 1234⁠–⁠5677⁠–⁠77⁠–⁠111 (plaćen, neiskorišten),
• 2234⁠–⁠5688⁠–⁠88⁠–⁠222 (plaćen, iskorišten),
• 3234⁠–⁠5699⁠–⁠99⁠–⁠333 (neplaćen, neiskorišten).

Ako aplikacija koristi jedan od ovih kodova, server će vratiti odgovarajući odgovor (u slučaju plaćenog i neiskorištenog vaučera, također će vratiti primjer vaučera i podatke o akciji).

Format podataka odgovora

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

Parametar voucherData sadrži definiciju vaučera u sljedećem formatu.

{
 "id": <voucher ID>,
 "orderId": <order ID>,
 "title": <voucher name>,
 "ordered": <order date and time; date and time>,
 "paidDate": <order payment date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code>,
 "product": <action ID>,
 "productName": <action name>,
 "variant": <action variant ID>,
 "variantName": <action variant name>,
 "imageUrl": <image URL>,
 "smallImageUrl": <thumbnail URL>,
 "productUrl": <action URL>
}

Stavke variant i variantName sadrže ID i naziv naručene varijante akcije, ako određena akcija sadrži varijante. Ako ne, oba atributa imaju vrijednost NULL.

Stanja pogreške

• kod 1101 (HTTP status kod 400): autentifikacijski token ili kod vaučera nije naveden,
• kod 1102 (HTTP status kod 403): navedeni token nije u bazi podataka,
• kod 1103 (HTTP status kod 404): vaučer s navedenim kodom ne postoji,
• kod 1104 (HTTP status kod 401): narudžba na temelju koje je vaučer izdan nije plaćena,
• kod 1105 (HTTP status kod 401): vaučer je već iskorišten,
• kod 1106 (HTTP status kod 401): vaučer je refundiran,
• kod 1107 (HTTP status kod 401): narudžba ili vaučer su otkazani,
• kod 1108 (HTTP status kod 401): akcija je već podmirena s partnerom; nije moguće iskoristiti više vaučera,
• kod 1109 (HTTP status kod 401): valjanost vaučera za ovu akciju još nije započela.
• kod 1111 (HTTP status kod 500): interna pogreška servera

Primjer zahtjeva

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

Primjer odgovora

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Iskorištavanje vaučera

• akcija: voucherApply
• parametri: token (obavezno; jedinstveni token partnera), code (obavezno; kod vaučera)

Pokušava se iskoristiti vaučer s navedenim kodom.

U svrhu testiranja moguće je koristiti testni broj vaučera. U tom slučaju vaučer zapravo neće biti iskorišten, ali će sustav vratiti odgovor kao da jest.

Format podataka odgovora

Format odgovora je potpuno isti kao u slučaju provjere valjanosti vaučera.

Stanja pogreške

• kod 1201 (HTTP status kod 400): autentifikacijski token ili kod vaučera nije naveden,
• kod 1202 (HTTP status kod 403): navedeni token nije u bazi podataka,
• kod 1203 (HTTP status kod 404): vaučer s navedenim kodom ne postoji,
• kod 1204 (HTTP status kod 401): narudžba na temelju koje je vaučer izdan nije plaćena,
• kod 1205 (HTTP status kod 401): vaučer je već iskorišten,
• kod 1206 (HTTP status kod 401): vaučer je refundiran,
• kod 1207 (HTTP status kod 401): narudžba ili vaučer su otkazani,
• kod 1208 (HTTP status kod 401): akcija je već podmirena s partnerom; nije moguće iskoristiti više vaučera,
• kod 1209 (HTTP status kod 401): valjanost vaučera za ovu akciju još nije započela.
• kod 1211 (HTTP status kod 500): interna pogreška servera

Primjer zahtjeva

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

Primjer odgovora

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Napomena: Za korištenje Partner API-ja za odbitak vrijednosti ili proizvoda u košarici, razmislite o uključivanju više atributa parametra voucherData. Ovo je posebno važno kada imate nekoliko tekućih akcija s različitim vrijednostima ponuđenih proizvoda. Preporučujemo korištenje posebno atributa product ili variant.