API partnerja Slevomat.cz

API se uporablja za prenos informacij o voucherjih med Zľavomat in sistemom poslovnega partnerja. Partnerju omogoča preverjanje veljavnosti voucherjev in unovčenje voucherjev znotraj lastnega sistema. Zato partner za ta namen ne potrebuje uporabe Partner Interface.

Možni primeri uporabe:

• Stranka kupi voucher, kjer je za izvedbo storitve ob oddaji naročila potrebno vnesti kodo na spletni strani partnerja. Zahvaljujoč API-ju se veljavnost voucherja preveri takoj po vnosu kode. Njegova vrednost se nato odšteje v partnerjevi košarici in hkrati se voucher samodejno unovči v Zľavomat.
• Veljavnost voucherjev je mogoče na enak način preveriti tudi v partnerjevem rezervacijskem sistemu ali pa se kupljeni kredit določene vrednosti neposredno pripiše na račun stranke na spletni strani partnerja.

Partner API zahteva žeton, ki je edinstven za vsakega partnerja in se pošilja z vsako zahtevo. Če želite uporabljati Partner API, kontaktirajte svojega/našega prodajnega predstavnika.

Format zahteve

API endpoint se nahaja na /api.

Format zahteve je

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

Vse zahteve so standardne HTTP GET zahteve, torej lahko zahteva za preverjanje veljavnosti voucherja izgleda takole:

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

Format odgovora

Odziv strežnika je vedno v JSON formatu z ustrezno Content-type glavo. Osnovna struktura odgovora je naslednja.

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

Vrednost elementa result je true (v primeru uspeha) ali false (v primeru napake). V primeru napake element error vsebuje kodo napake (code) in njen opis (message). Poleg označitve v polju error sistem v primeru napake vrne tudi ustrezno HTTP status kodo (400, 401, 403, 404).

Element data vsebuje podatke, ki jih vrne klicana akcija, in je njegova vsebina individualna.

Vsi datumi so v formatu YYYY-MM-DDTHH:MM:SSZ (ISO8601; npr. 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Preverjanje veljavnosti voucherja

• akcija: voucherCheck
• parametri: token (obvezno; edinstven žeton partnerja), code (obvezno; koda voucherja)

Obstajajo tri testne kode voucherjev:

• 1234⁠–⁠5677⁠–⁠77⁠–⁠111 (plačan, neuporabljen),
• 2234⁠–⁠5688⁠–⁠88⁠–⁠222 (plačan, uporabljen),
• 3234⁠–⁠5699⁠–⁠99⁠–⁠333 (neplačan, neuporabljen).

Če aplikacija uporabi eno od teh kod, bo strežnik vrnil ustrezen odgovor (v primeru plačanega in neuporabljenega voucherja bo vrnil tudi vzorčne podatke voucherja in akcije).

Format podatkov odgovora

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

Parameter voucherData vsebuje definicijo voucherja v naslednjem 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>
}

Elementa variant in variantName vsebujeta ID in ime naročene variante akcije, če ima dana akcija variante. Če ne, imata obe atributa vrednost NULL.

Stanja napak

• koda 1101 (HTTP status koda 400): žeton za avtentikacijo ali koda voucherja nista bila podana,
• koda 1102 (HTTP status koda 403): podani žeton ni v bazi,
• koda 1103 (HTTP status koda 404): voucher s podano kodo ne obstaja,
• koda 1104 (HTTP status koda 401): naročilo, na podlagi katerega je bil voucher izdan, ni bilo plačano,
• koda 1105 (HTTP status koda 401): voucher je že bil unovčen,
• koda 1106 (HTTP status koda 401): voucher je bil povrnjen,
• koda 1107 (HTTP status koda 401): naročilo ali voucher je bil preklican,
• koda 1108 (HTTP status koda 401): akcija je že bila poravnana s partnerjem; ni mogoče unovčiti več voucherjev,
• koda 1109 (HTTP status koda 401): veljavnost voucherjev za to akcijo se še ni začela.
• koda 1111 (HTTP status koda 500): interna napaka strežnika

Primer zahteve

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

Primer odgovora

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

Unovčenje voucherja

• akcija: voucherApply
• parametri: token (obvezno; edinstven žeton partnerja), code (obvezno; koda voucherja)

Poskusi unovčiti voucher s podano kodo.

V testne namene je mogoče uporabiti testno številko voucherja. V tem primeru voucher dejansko ne bo unovčen, vendar bo sistem vrnil odgovor, kot da bi bil.

Format podatkov odgovora

Format odgovora je popolnoma enak kot v primeru preverjanja veljavnosti voucherja.

Stanja napak

• koda 1201 (HTTP status koda 400): žeton za avtentikacijo ali koda voucherja nista bila podana,
• koda 1202 (HTTP status koda 403): podani žeton ni v bazi,
• koda 1203 (HTTP status koda 404): voucher s podano kodo ne obstaja,
• koda 1204 (HTTP status koda 401): naročilo, na podlagi katerega je bil voucher izdan, ni bilo plačano,
• koda 1205 (HTTP status koda 401): voucher je že bil unovčen,
• koda 1206 (HTTP status koda 401): voucher je bil povrnjen,
• koda 1207 (HTTP status koda 401): naročilo ali voucher je bil preklican,
• koda 1208 (HTTP status koda 401): akcija je že bila poravnana s partnerjem; ni mogoče unovčiti več voucherjev,
• koda 1209 (HTTP status koda 401): veljavnost voucherjev za to akcijo se še ni začela.
• koda 1211 (HTTP status koda 500): interna napaka strežnika

Primer zahteve

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

Primer odgovora

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

Opomba: Pri uporabi Partner API za odštevanje vrednosti ali izdelkov v košarici razmislite o vključitvi več atributov parametra voucherData. To je še posebej pomembno, kadar imate več tekočih akcij z različnimi vrednostmi ponujenih izdelkov. Priporočamo uporabo predvsem atributov product ali variant.