VODIČ ZA POSLOVNE PARTNERJE
Slovenština Čeština Němčina Angličtina Chorvatština Maďarština Italština Polština Ruština Slovinština Ukrajinština Vietnamština
Uvod Uporabni priročniki IT podpora API partnerja Slevomat.cz

API partnerja Slevomat.cz

Ta članek je bil strojno preveden.

API se uporablja za prenos informacij o bonih med Zlavomatom in sistemom poslovnega partnerja. Partnerju omogoča preverjanje veljavnosti bonov v svojem sistemu in unovčenje bonov. Partnerju za ta namen ni treba uporabljati partnerskega vmesnika.

Možni primeri uporabe:

  • Stranka kupi bon, pri čemer je pogoj za opravljanje storitve vnos kode na spletni strani partnerja ob ustvarjanju naročila. Zahvaljujoč API-ju se po tem vnosu takoj preveri veljavnost bona. Njegova vrednost se nato odšteje iz partnerjeve košarice in bon se samodejno unovči v trgovini Zlavomot.
  • Na enak način je mogoče preveriti tudi veljavnost bonov v rezervacijskem sistemu partnerja ali pa lahko stranka naloži kupljeni dobropis določene vrednosti neposredno na spletni strani partnerja.

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

Oblika zahteve

Dostopna točka API se nahaja na /api.

Oblika zahteve je

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

Vse zahteve so standardne zahteve HTTP GET, tj. zahteva za preverjanje veljavnosti bona lahko izgleda na primer 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 rezultata je true (v primeru uspeha) ali false (v primeru napake). V primeru napake element napake vsebuje kodo napake ( code ) in njen opis ( message ). Poleg indikacije v polju za napako sistem vrne ustrezno kodo stanja HTTP (400, 401, 403, 404) v primeru napake.

Podatkovni element vsebuje podatke, ki jih vrne klicano dejanje, in njegova vsebina je individualna.

Vsi podatki so v obliki YYYY-MM-DDTHU:MM:SSZ (ISO8601; npr. 2011–01–01T10:10:10+02:00).

Preverjanje veljavnosti bona

  • dejanje: Preverjanje bona
  • parametri: žeton (obvezno; edinstveni partnerski žeton), koda (obvezno; koda darilnega bona)

Obstajajo tri kode za testne darilne bone:

  • 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 plačanega in neuporabljenega bona bo vrnil tudi vzorčni bon in podatke o dejanju).

Oblika podatkov odgovora

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

Parameter voucherData vsebuje definicijo vavčerja 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>
}

Elementi variant ali variantName vsebujejo ID ali ime urejene variante dejanja, če dano dejanje vsebuje variante. Če ne, sta oba atributa NULL .

Stanja napak

  • koda 1101 (koda stanja HTTP 400): žeton za preverjanje pristnosti ali koda kupona nista bila vnesena,
  • koda 1102 (koda stanja HTTP 403): danega žetona ni v bazi podatkov,
  • koda 1103 (koda stanja HTTP 404): bon z navedeno kodo ne obstaja,
  • koda 1104 (koda statusa HTTP 401): naročilo, na podlagi katerega je bil izdan bon, ni bilo plačano,
  • koda 1105 (koda stanja HTTP 401): bon je že bil uporabljen,
  • koda 1106 (koda stanja HTTP 401): kupon je bil povrnjen,
  • koda 1107 (koda stanja HTTP 401): naročilo ali bon je bil preklican,
  • koda 1108 (koda stanja HTTP 401): dejanje je bilo partnerju že zaračunano; drugih bonov ni mogoče uporabiti,
  • koda 1109 (koda stanja HTTP 401): veljavnost kuponov za ta dogodek še ni začela teč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=123456789012345

Primer odgovora

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

Unovčenje bona

  • dejanje: bonUporabi
  • parametri: žeton (obvezno; edinstveni partnerski žeton), koda (obvezno; koda bona)

Poskušali bomo unovčiti dano kodo.

Številko testnega bona je mogoče uporabiti za namene testiranja. V tem primeru bon ne bo unovčen, vendar bo sistem vrnil odgovor, kot da bi se to zgodilo.

Oblika podatkov odgovora

Oblika odgovora je popolnoma enaka kot v primeru preverjanja veljavnosti bona.

Stanja napak

  • koda 1201 (koda stanja HTTP 400): žeton za preverjanje pristnosti ali koda kupona nista bila vnesena,
  • koda 1202 (koda stanja HTTP 403): danega žetona ni v bazi podatkov,
  • koda 1203 (koda stanja HTTP 404): bon z navedeno kodo ne obstaja,
  • koda 1204 (koda statusa HTTP 401): naročilo, na podlagi katerega je bil izdan bon, ni bilo plačano,
  • koda 1205 (koda stanja HTTP 401): bon je že bil uporabljen,
  • koda 1206 (koda stanja HTTP 401): kupon je bil povrnjen,
  • koda 1207 (koda stanja HTTP 401): naročilo ali bon je bil preklican,
  • koda 1208 (koda stanja HTTP 401): dejanje je bilo partnerju že zaračunano; ni mogoče uporabiti drugih bonov,
  • koda 1209 (koda stanja HTTP 401): veljavnost kuponov za ta dogodek še ni začela teči.
  • koda 1211 (koda stanja HTTP 500): notranja 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": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Opomba: Če želite uporabiti Partner API za branje vrednosti izdelkov v košarici, razmislite o vključitvi več atributov parametra voucherData. To je še posebej pomembno v trenutku, ko imate več aktivnih kampanj z različno vrednostjo ponujenih izdelkov. Priporočamo uporabo predvsem atributov product ali variant.

Nazaj na seznam člankov

Povezani članki

Navzgor