API blago tretjih oseb

API se uporablja za prenos informacij o naročilih med avtomatom za popuste in sistemom poslovnega partnerja. API zahteva izvedbo dvosmerne komunikacije – sistem avtomata za popuste pokliče API partnerja, partner pa pokliče API avtomata za popuste.

Naročil, izvoženih v partnerski API, ni več mogoče upravljati v partnerskem vmesniku Zlavomat, ampak si jih lahko le ogledate. Izvožena naročila je zdaj mogoče upravljati samo prek API-ja.

Vse zahteve morajo biti poslane prek HTTPS in vsi podatki so v formatu JSON.

Dostopnost API-ja

Do API-ja lahko dostopate na zavihku Nastavitve v partnerskem vmesniku. Za pridobivanje podatkov morate vnesti korenski URL partnerskega dela API-ja za uporabo v smeri Zlavomat → Partner, npr.

https://example.com/slevomat-zbozi-api

Podatki o dostopu bodo prikazani le, ko bo dostopan API, zato jih hranite varno.

Ko bo API na voljo, bo sistem začel izvažati novo ustvarjena naročila vanj.

Začetni izvoz podatkov

Za prenos obstoječih naročil v trenutku, ko je API na voljo, je mogoče uporabiti enkratni izvoz v CSV v partnerskem vmesniku.

Ko že imate v svojem sistemu obstoječa naročila (ustvarjena, preden je bil API na voljo) in želite z njimi začeti delati prek API-ja, uporabite funkcijo »Začni delo z označenimi naročili prek API-ja« v meniju »Množična dejanja z naročili«.

Opis pogostih odgovorov HTTP

• 200 OK – zahteva je bila uspešno obdelana
• 204 No Content – zahteva je bila uspešno obdelana, odgovor nima vsebine
• 400 Bad Request – zahteva ni veljavna – morda manjkajo ali so neveljavni parametri v primerjavi s specifikacijo
• 403 Forbidden – avtorizacija stranke ni uspela
• 404 Not Found – končna točka ali zahtevani podatki niso bili najdeni
• 405 Method Not Allowed – končna točka ne podpira te metode protokola HTTP
• 422 Unprocessable Entity – pričakovana napaka med obdelavo zahteve (glejte razdelek Stanja napak )
• 500 Internal Server Error – na strani strežnika je prišlo do napake
• 502 Bad Gateway – na strani strežnika je prišlo do napake
• 503 Service Unavailable – strežnik je v vzdrževalnem načinu (morda poteka uvajanje nove različice ali načrtovani izpad)
• 504 Gateway Timeout – na strani strežnika je prišlo do napake

Odgovori HTTP 5×x ni nujno, da uporabljajo format JSON.

V primeru napak4xx V odhodni zahtevi je napaka, ki jo je treba odpraviti, preden poskusite znova.

Napake5xx označujejo napake strežnika in zahtevo je mogoče ponoviti brez spreminjanja. V primeru503 Klicatelj mora upoštevati glavo odgovoraRetry-After in naslednji poskus ponovite šele po preteku časa, navedenega v glavi.

Stanja naročil

Naročilo je vedno v enem od naslednjih statusov:

Stranka je o vsaki spremembi statusa obveščena po elektronski pošti.

Naročilo ni nujno, da gre skozi vse statuse, da bi bilo uspešno dostavljeno; iz statusa »Novo plačano naročilo« je mogoče iti naravnost v »Na poti« / »Pripravljeno za osebni prevzem« in nato v »Dostavljeno stranki – čaka se na potrditev stranke«. Vendar pa uporaba vseh statusov vodi do boljše obveščenosti strank o napredku naročila in jo priporočamo.

Stanja napak

V primeru kod HTTP 4×x odgovor vedno vsebuje ključstatus (glejte spodnji seznam kod) in poljemessages z besedilnimi opisi napak.

Vzorec:

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Vrste podatkov

Podatkovni tipi posameznih ključev v zahtevah in odgovorih so vedno opisani za določene končne točke. Če ni drugače navedeno, je vrednost v narekovajih."" je vedno obvezen niz. Če ni drugače določeno, je številska vrednost vedno obvezno celo število.

Komunikacijski popustni avtomat ⇒ Partner

Ta del API-ja je implementiran na strani partnerja in ga kliče Zlavovamat.

Zahtevani korenski URL API-ja bo delil partner in mora biti v obliki

https://www.example.com/slevomat-zbozi-api/v1

Avtorizacija zahtev

Ko je API vklopljen, partner prejmepartner_api_se­cret , kar dokazuje, da dohodne zahteve resnično prihajajo iz Zlavomata.

Ta parameter se posreduje v glavi HTTPX-PartnerApiSecret .

Testni vmesnik

Avtomat za popuste vključuje funkcionalnost za klic API-ja na strani partnerja in prikaz odgovora. Korenski URL, ki ga partner določi ob omogočanju dostopa do API-ja, je priložen-test , zato se API kot del testiranja pokliče na primer na

https://example.com/slevomat-zbozi-api-test

da se izognemo mešanju testnih podatkov z aktivnimi naročili.

Testiranje partnerskega API-ja se izvaja z zahtevami POST na naslednje naslove:

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Novo naročilo

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

   – Posodobitev pričakovanih datumov pošiljanja v večjem obsegu

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

   – Sprememba statusa naročila v »Dostavljeno stranki – čaka se na potrditev stranke«

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

   – Sprememba statusa naročila v »Pripravljeno za osebni prevzem«

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Potrditev dostave

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Zavrnitev sprejema

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Prekliči

Del URL-ja<orderId> zamenjajte s katero koli številko naročila, zahteve partnerskemu API-ju se pošljejo s to številko naročila.

Zahteve za ta testni vmesnik morajo biti avtorizirane z glavami.X-PartnerToken inX-ApiSecret .

Pri testiranju klica partnerskega API-ja sistem pošlje glavoX-PartnerApiSecret tako kot v delovanju v živo.

Podatki, poslani z novim naročilom, so testne narave in naključno generirani.

V primeru pošiljanja preklica naročila je potrebno v telo zahteve POST vključiti polje JSON.items (v isti obliki, kot jo pošlje API), ki jo testni vmesnik potrdi in posreduje partnerskemu API-ju v isti obliki.

Novo naročilo

Zahteva vsebuje podatke o novo ustvarjenem naročilu.

Naročila so vedno edinstvenazlavomatId Če v API prispe dvojnikzlavomatId , bi moral partnerski API prezreti zahtevo (prva zahteva, ki jo je poslal Zľavomat, je bila ocenjena kot neuspešna, zato jo ponavljamo) in prav tako odgovoriti s HTTP 204.

created je datum v formatu ISO 8601, tj.YYYY-MM-DD'T'HH:mm:ss­+zz:zz .

productId vsebuje ID dejanja, variantId ID kupljene variante.

NeobveznointernalId pomeni interni ID, vnesen za varianto dejanja ob njenem ustvarjanju v partnerskem vmesniku. Uporablja se za identifikacijo izdelka v partnerskem sistemu.

VbillingAddress (naslov za izstavitev računa) samo ime ( je obvezno)name ) stranke.

VshippingAddress (naslov za dostavo) je neobvezno podjetje (company ). V primeru dostave na naslovshippingAddress vsebuje naslov stranke, v primeru osebnega prevzema pa naslov trgovine, kjer bo stranka prevzela blago.

Ključdelivery .type lahko prevzame vrednostiaddress (dostava na naslov) alipickup (osebna zbirka).delivery .name vsebuje ime prevoza ali ime operacije.

delivery .expec­tedShippingDa­te (predvideni datum odpreme) indelivery .expec­tedDeliveryDa­te (predvideni datum dostave) so podatki v oblikiYYYY-MM-DD .

Ključweight vsebuje težo naročila v kilogramih. Če ne poznamo teže vseh artiklov v naročilu, vzame vrednostnull .

POST /naročilo/$slevomatId

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /naročilo/$slevomatId

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShip­pingDate": "2021–09–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Množična posodobitev pričakovanih datumov pošiljanja

Če upravitelj poslov na zahtevo partnerja množično premakne datume pošiljanja izbranih naročil, sistem o tej posodobitvi obvesti partnerski API.

Poslani podatki vključujejo polje z ID-jem naročila in novim predvidenim datumom dostave.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Prekliči

Preklice je mogoče ustvariti tako na strani Zlavomata kot na partnerskem sistemu. Ta končna točka obravnava ustvarjanje preklicev na strani Zlavomata in njihov prenos v partnerski sistem.

Ustvari preklic naročila za artikle v določeni količini. Če je treba preklicati celotno naročilo, so navedeni vsi artikli z ustrezno količino.

Posamezne artikle je mogoče tudi delno stornirati (npr. 1 kos od dveh).

Opomba o preklicu (note ) je neobvezno.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Potrditev dostave

Ko naročilo označite kot »Dostavljeno stranki«, bomo od stranke zahtevali potrditev, da ga je dejansko prejela. Ko je naročilo označeno kot prejeto, bo poklicana ta končna točka.

POST /order/$slevo­matId/confirm-delivery

{}

Zavrnitev sprejema

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Sprememba statusa naročila v »Pripravljeno za osebni prevzem«

Ta končna točka bo poklicana, če je bil prejšnji status »Priprava na osebni prevzem« nastavljen naautoMarkRea­dyForPickuptrue in na strani Zlavomata je bilo naročilo samodejno preklopljeno v status »Pripravljeno za osebni prevzem«

POST /order/$slevo­matId/delivery-ready-for-pickup

{}

Sprememba statusa naročila v »Dostavljeno stranki – čaka se na potrditev stranke«

Ta končna točka bo poklicana, če je bil prejšnji status nastavljen na »Na poti«, »Priprava na osebni prevzem« ali »Pripravljeno za osebni prevzem« zautoMarkDeli­veredtrue in na strani Zlavomata se je naročilo samodejno preklopilo v status »Dostavljeno stranki – čaka se na potrditev stranke«.

POST /order/$slevo­matId/mark-delivered

{}

Komunikacijski partner ⇒ Avtomat za popuste

Ta del API-ja je implementiran na strani Zľavomata in ga kliče partnerski sistem.

Korenski URL API-ja je

https://www.zlavomat.sk/zbozi-api/v1

PHP knjižnica

Za implementacijo te API strani lahko uporabite že pripravljeno PHP knjižnico. Knjižnica trenutno zahteva PHP različice 5.4 ali novejše in predpostavlja uporabo orodja Composer.

Navodila in izvorna koda knjižnice so na voljo na GitHubu .

Avtorizacija zahtev

Ko je API vklopljen, partner prejmepartner_token inapi_secret , ki se uporablja za dokazovanje pri klicu Zlavomat API-ja.

Ti parametri se posredujejo v glavahX-PartnerToken inX-ApiSecret .

Testni vmesnik

Korenski URL testnega vmesnika je

https://www.zlavomat.sk/zbozi-api/v1-test

Vsa dejanja je mogoče na njem klicati kot na drugem vmesniku.

Testni vmesnik preverja avtorizacijo zahtev (pravilnost partnerskega žetona in API tajne kode) in veljavnost vhodnih teles zahtev (JSON). V teh pogledih se obnaša identično kot aktivni API.

Vendar testni vmesnik ne deluje z dejanskimi naročili. Ne preverja, ali naročilo prehaja med pravilnimi stanji in ali vsebuje artikle z navedenimi ID-ji. Ko sta avtorizacija in potrditev obrazca zahteve uspešni, testni vmesnik vedno odgovori s kodo uspeha 200 ali 204.

Ustvari preklic

Ustvarite artikle za preklic naročila v določeni količini. Če želite preklicati celotno naročilo, so navedeni vsi artikli z ustrezno količino.

Posamezne artikle je mogoče tudi delno stornirati (npr. 1 kos od dveh).

Opomba o preklicu (note ) je neobvezno.

POST /naročilo/$slevomatId/prekliči

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Sprememba statusa naročila v »V obdelavi«

POST /order/$slevomatId/mark-pending

{}

Sprememba statusa naročila v »Na poti«

Pri naročilu je parameterautoMarkDelivered določite, ali naj se status samodejno spremeni v »Dostavljeno stranki – čaka se na potrditev stranke« po nastavljenem obdobju prevoza (»Čas od odpreme do dostave«)

Odgovor vključuje posodobljen predvideni datum dostave.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

Odgovor 200

{ "expectedDeli­veryDate": "2021–08–25" }

Sprememba statusa naročila v »Priprava na osebni prevzem«

Pri naročilu je parameterautoMarkReady­ForPickup določite, ali naj se status samodejno spremeni v »Pripravljeno za osebni prevzem« po preteku časa od odpreme do dostave za določeno vrsto prevzemnega mesta.

Pri naročilu je parameterautoMarkDelivered določite, ali naj se status samodejno spremeni iz »Pripravljeno za osebni prevzem« v »Dostavljeno stranki – čaka se na potrditev stranke« po določenem številu dni za prevzem na določeni vrsti prevzemnega mesta.

Kombinacija parametrovautoMarkReady­ForPickup lažno inautoMarkDelivered Vrednost »true« ni dovoljena. V tem primeru se vrne koda napake 9.

Odgovor vključuje posodobljen predvideni datum dostave.

POST /order/$slevomatId/mark-getting-ready-for-pickup

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Odgovor 200

{ "expectedDeli­veryDate": "2021–09–06" }

Sprememba statusa naročila v »Pripravljeno za osebni prevzem«

Pri naročilu je parameterautoMarkDelivered določite, ali naj se status samodejno spremeni v »Dostavljeno stranki – čaka se na potrditev stranke« po določenem številu dni za prevzem za določeno vrsto prevzemnega mesta.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Sprememba statusa naročila v »Dostavljeno stranki – čaka se na potrditev stranke«

POST /order/$slevo­matId/mark-delivered

{}

Sprememba naslova za dostavo

Naslov za dostavo je mogoče spremeniti le ob dostavi na naslov (tj. kraja podobnega prevzema ni mogoče spremeniti).

Vse tipke razencompany so obvezni.

Veljavne vrednosti za ključstate socz (Češka republika) insk (Slovaška).

POST /order/$slevo­matId/update-shipping-address

{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }