API se uporablja za prenos podatkov o bonih med Discountomat in sistemom trgovca. Partnerju omogoča, da preveri veljavnost bonov v svojem sistemu in unovči bone. Partnerju za ta namen ni treba uporabljati partnerskega vmesnika.
Možni primeri uporabe:
- Kupec kupi bon, pri čemer je pogoj za storitev vpis kode na spletni strani partnerja ob kreiranju naročila. Zahvaljujoč API-ju se po tem vnosu takoj preveri veljavnost kupona. Njegova vrednost se nato odšteje v partnerjevi košarici in hkrati avtomatsko unovči bon v Diskontomatu.
- Na enak način je možno tudi preveriti veljavnost bonov v partnerjevem rezervacijskem sistemu ali naložiti kupcu kupljeno dobroimetje v določeni vrednosti neposredno na spletno stran partnerja.
Partner API zahteva žeton, ki je edinstven za vsakega partnerja in se pošlje kot del vsake zahteve. Za uporabo partnerskega API-ja se obrnite na vašega/našega trgovca.
Oblika zahteve
Dostopna točka API se nahaja na /api.
Oblika zahteve je
<URL přístupového bodu>/<akce>[<parametry>]Vse zahteve so standardne zahteve HTTP GET, kar pomeni, da je zahteva za preverjanje veljavnosti kupona lahko videti takole:
https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.Oblika odgovora
Odgovor strežnika je vedno v formatu JSON z ustrezno glavo Content-type. Osnovna struktura odgovora je naslednja.
{
"result": true,
"data": {
...
},
"error": {
"code": 0,
"message": null
}
}
Vrednost elementa rezultata je true (v primeru uspeha) ali false (v primeru napake). V primeru napake vnos napake vsebuje kodo napake (koda ) in njen opis (sporočilo ). Poleg navedbe v polju napake sistem v primeru napake vrne ustrezno statusno kodo HTTP (400, 401, 403, 404).
Podatkovna postavka vsebuje podatke, ki jih vrne klicano dejanje, njena vsebina pa je individualna.
Vsi podatki so v obliki zapisa LLLL-MM-DDTHH:MM:SSZ (ISO8601; npr. 2011–01–01T10:10:10+02:00).
Potrditev vavčerja
- dejanje: voucherCheck
- parametri: žeton (obvezno; edinstven partnerski žeton), koda (obvezno; koda bona)
Obstajajo tri kode testnih bonov:
- 1234–5677–77–111 (plačano, neuporabljeno),
- 2234–5688–88–222 (plačano, rabljeno),
- 3234–5699–99–333 (neplačano, neuporabljeno).
Če aplikacija uporabi eno od teh kod, bo strežnik vrnil ustrezen odgovor (v primeru vplačanega in neizkoriščenega bona vrne tudi vzorec bona in podatke o dogodku).
Oblika podatkov o odgovoru
{
"token": <autentizační token>,
"code": <kód voucheru>,
"voucherData": <data voucheru>
}
Parameter voucherData vsebuje definicijo bona v naslednji obliki.
{
"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>
}
Polji variant in variantName vsebujejo ID ali ime naročene različice dogodka, če dogodek vsebuje različice. Če ni, sta oba atributa NULL .
Pogoji napak
- Koda 1101 (HTTP statusna koda 400): avtentikacijski žeton ali koda kupona ni bila vnesena,
- Koda 1102 (HTTP statusna koda 403): žetona ni v bazi podatkov,
- koda 1103 (HTTP statusna koda 404): bon z navedeno kodo ne obstaja,
- koda 1104 (HTTP statusna koda 401): naročilo, na podlagi katerega je bil bon izdan, ni plačano,
- koda 1105 (HTTP statusna koda 401): bon je že unovčen,
- koda 1106 (HTTP statusna koda 401): kupon je bil vrnjen,
- koda 1107 (HTTP statusna koda 401): naročilo ali kupon je bilo preklicano,
- koda 1108 (HTTP statusna koda 401): dogodek je že zaračunan partnerju; ni več mogoče zahtevati nobenih dodatnih kuponov,
- koda 1109 (HTTP statusna koda 401): boni za ta dogodek še niso začeli poteči.
- koda 1111 (koda stanja HTTP 500): notranja napaka strežnika
Primer zahteve
https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345Primer odgovora
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Unovčenje bona
- Akcija: bonPrijava
- parametri: žeton (obvezno; edinstven partnerski žeton), koda (obvezno; koda bona)
Poskusi unovčiti kupon dane kode.
Številko testnega bona lahko uporabite za namene testiranja. V tem primeru bon ne bo unovčen, ampak bo sistem vrnil odgovor, kot da je bil unovčen.
Oblika podatkov o odgovoru
Oblika odgovora je popolnoma enaka kot pri preverjanju veljavnosti bona.
Pogoji napak
- Koda 1201 (HTTP statusna koda 400): avtentikacijski žeton ali koda kupona ni bila vnesena,
- koda 1202 (koda stanja HTTP 403): žetona ni v bazi podatkov,
- koda 1203 (HTTP statusna koda 404): bon z navedeno kodo ne obstaja,
- koda 1204 (HTTP statusna koda 401): naročilo, na podlagi katerega je bil bon izdan, ni plačano,
- koda 1205 (HTTP statusna koda 401): bon je že unovčen,
- koda 1206 (HTTP statusna koda 401): kupon je bil povrnjen,
- koda 1207 (HTTP statusna koda 401): naročilo ali kupon je bilo preklicano,
- koda 1208 (HTTP statusna koda 401): dogodek je bil že zaračunan partnerju; ni več mogoče zahtevati nobenih dodatnih kuponov,
- koda 1209 (HTTP statusna koda 401): boni za ta dogodek še niso začeli potekati.
- koda 1211 (koda statusa HTTP 500): notranja napaka strežnika
Primer zahteve
https://www.zlavomat.sk/api/voucherapply?code=1234-5677-77-111&token=123456789012345Primer odgovora
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Opomba: če želite uporabiti Partner API za odštevanje vrednosti ali izdelkov v vašem vozičku, razmislite o vključitvi več atributov v parameter voucherData. To je pomembno, še posebej, če želite uporabiti parameter vavčerja. To je pomembno, če imate več aktivnih promocij z različnimi vrednostmi izdelkov. Zlasti priporočamo uporabo atributov izdelka ali različice.