API tretje osebe

API se uporablja za prenos informacij o naročilu med Slevomatom in sistemom našega trgovinskega partnerja. API zahteva implementacijo dvosmerne komunikacije – sistem Slevomat kliče partnerjev API, partner pa kliče Slevomatov API.

Naročil, izvoženih v partnerski API, ni več mogoče manipulirati v partnerskem vmesniku Slevomat, le ogledovati. Manipulacija z izvoženimi naročili je mogoča le preko API-ja.

Vse zahteve morajo biti podane na HTTPS in vsi podatki so v formatu JSON.

API dostop

Do poverilnic za API lahko dostopate na zavihku Nastavitve v partnerskem vmesniku. Za pridobitev podatkov morate zagotoviti korenski URL partnerskega dela API-ja za uporabo v smeri Slevomat → Partner, npr.

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

Podatki o dostopu bodo prikazani samo enkrat, ko boste dostopali do API-ja, zato jih skrbno shranite.

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

Začetni izvoz podatkov

Za prenos obstoječih naročil v trenutku dostopa do API-ja lahko uporabite enkraten izvoz v CSV v partnerskem vmesniku.

Č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 delati z označenimi naročili prek API-ja" v "Množična dejanja z naročili" meni.

Opis pogostih odzivov HTTP

• 200 OK – zahteva je bila uspešno obdelana
• 204 No Content – zahteva je bila obdelana, odgovor je brez vsebine
• 400 Bad Request – zahteva ni veljavna – morda manjkajo ali so neveljavni parametri glede na specifikacijo
• 403 Forbidden – avtorizacija odjemalca 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 HTTP
• 422 Unprocessable Entity – pričakovana napaka med obdelavo zahteve (glejte razdelek Pogoji napake )
• 500 Internal Server Error – prišlo je do napake na strani strežnika
• 502 Bad Gateway – prišlo je do napake na strani strežnika
• 503 Service Unavailable – strežnik je v vzdrževalnem načinu (uvajanje nove različice je morda v teku ali je načrtovana izpad)
• 504 Gateway Timeout – prišlo je do napake na strani strežnika

Odgovori HTTP 5×x morda ne bodo uporabljali zapisa JSON.

V primeru4xx napake, je odhodna zahteva napačna in jo je treba popraviti pred ponovnim poskusom.

Napake5xx kažejo napake strežnika in zahtevo lahko poskusite znova, ne da bi jo spremenili. V primeru503 , mora klicatelj spoštovatiRetry-After glavo odgovora in poskusite znova šele po preteku časa, določenega v glavi.

Statusi naročil

Naročilo je vedno v enem od naslednjih stanj:

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

Ni nujno, da gre naročilo skozi vse statuse za uspešno dostavo, iz "Novo naročilo plačano" je mogoče preiti naravnost v "Blago odposlano" / "Pripravljeno za osebni prevzem" in nato v "Dostavljeno stranki – čaka na potrditev stranke". ". Uporaba vseh statusov pa vodi do boljše obveščenosti kupca o poteku naročila in je priporočljiva.

Stanja napak

V primeru kod HTTP 4×x odgovor vedno vsebuje ključstatus (glej šifrant spodaj) in poljemessages z besedilnimi opisi napak.

primer:

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

Vrste podatkov

Tipi podatkov vsakega ključa v zahtevah in odgovorih so vedno opisani za določene končne točke. Če ni drugače določeno, vrednost v narekovajih"" je vedno obvezen niz. Če ni določeno drugače, je številska vrednost vedno obvezno celo število.

Komunikacija Slevomat ⇒ Partner

Ta del API-ja je implementiran na strani partnerja in Slevomat ga imenuje.

Zahtevani korenski URL API-ja zagotovi partner in mora biti v obrazcu

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

Zahtevaj avtorizacijo

Ko je API omogočen, partner prejmepartner_api_se­cret , kar dokazuje, da so dohodni zahtevki res iz Slevomata.

Ta parameter se posreduje v glavi HTTPX-PartnerApiSecret .

Testni vmesnik

Slevomat vključuje funkcionalnost za klic API-ja na strani partnerja in ogled odgovora. Korenski URL, ki ga določi partner, ko je API na voljo, je pripet-test , tako da se pri testiranju API kliče na npr

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

da se izognete mešanju testnih podatkov z živimi naročili.

Testiranje partnerskega API-ja poteka prek POST zahtev na naslednje naslove:

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order

   – Novo naročilo

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

   – Spremenite status naročila v "Dostavljeno stranki – čaka na potrditev stranke"

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

   – Spremenite status naročila v "Pripravljeno za osebni prevzem"

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 

   – Potrditev dostave

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 

   – Zavrnitev sprejema

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

   – Odpoved

Zamenjajte<orderId> del URL-ja s katero koli številko naročila, se zahteve za API partnerja izvajajo s to številko naročila.

Zahteve za ta testni vmesnik je treba odobriti z glavamiX-PartnerToken inX-ApiSecret .

Pri testnem klicu partnerskemu API-ju sistem pošljeX-PartnerApiSecret glavo, kot to počne pri delovanju v živo.

Podatki, poslani z novim naročilom, so testni podatki in naključno ustvarjeni.

V primeru pošiljanja preklica naročila morate vključitiitems polje v telesu POST zahteve v JSON (v enakem formatu, kot ga je poslal API), ki ga bo preskusni vmesnik preveril in posredoval partnerskemu API-ju v isti obliki.

Novo naročilo

Zahteva vsebuje podatke novo oblikovanega naročila.

Naročila imajo vedno unikatslevomatId . Če API prejme dvojnikslevomatId , mora biti zahteva prezrta s strani partnerskega API-ja (prvo zahtevo je Slevomat ocenil kot neuspešno in jo je zato ponovil), odgovor pa mora biti tudiHTTP 204 .

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

productId vsebuje ID dogodka, variantId ID kupljene variante.

NeobveznointernalId označuje notranji ID, vnesen za različico dejanja, ko je ustvarjena v partnerskem vmesniku. Uporablja se za identifikacijo izdelka v sistemu partnerja.

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

notershippingAddress (naslov za dostavo) podjetje (company ) ni obvezna. V primeru dostave doshippingAddress vsebuje naslov stranke, v primeru osebnega prevzema naslov lokala, kjer bo stranka prevzela blago.

Ključdelivery .type lahko prevzame vrednostaddress (dostava na naslov) ozpickup (osebni prevzem).delivery .name vsebuje ime prevoza ali ime obrata.

delivery .expec­tedShippingDa­te (predvideni datum pošiljanja) indelivery .expec­tedDeliveryDa­te (predvideni rok dobave) 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 /order/$slevomatId

{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "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": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$slevomatId

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "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–02", "expectedDeli­veryDate": "2021–09–02", "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 premakne datume odpreme izbranih naročil, sistem o tej posodobitvi obvesti partnerski API.

Poslani podatki vsebujejo polje ID naročila in nov pričakovani datum odpreme.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Odpoved

Preklici se lahko kreirajo tako na strani Slevomat kot v partnerskem sistemu. Ta končna točka skrbi za ustvarjanje stornacije na strani Slevomat in njen prenos v sistem partnerja.

Ustvari preklic postavk 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 odpovedati (npr. 1 od 2).

Opomba o preklicu (note ) ni obvezna.

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 je naročilo dejansko prejela. Ko je naročilo označeno kot prejeto, bo ta končna točka poklicana.

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

{}

Zavrnitev sprejema

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

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

Spremenite status naročila v "Pripravljeno za osebni prevzem"

Ta končna točka bo poklicana, če je bilo prejšnje stanje »Pripravljeno za osebni prevzem« nastavljeno zautoMarkRea­dyForPickuptrue in naročilo se je samodejno preklopilo na "Pripravljeno za osebni prevzem" na strani Slevomat.

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

{}

Spremenite status naročila v "Dostavljeno stranki – čaka na potrditev stranke"

Ta končna točka se pokliče, če je bil prejšnji status »Na poti«, »Pripravljen za osebni prevzem« ali »Pripravljen za osebni prevzem« nastavljen zautoMarkDeli­veredtrue in naročilo se je na strani Slevomat samodejno preklopilo v status "Dostavljeno kupcu – čaka na potrditev kupca".

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

{}

Komunikacijski partner ⇒ Slevomat

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

Korenski URL API-ja je

 https://www.slevomat.cz/zbozi-api/v1

PHP knjižnica

Za implementacijo te strani API-ja lahko uporabite pripravljeno knjižnico PHP. Knjižnica trenutno zahteva PHP 5.4 ali novejši in zahteva uporabo Composerja.

Navodila za uporabo knjižnice in izvorne kode so na GitHubu .

Zahtevaj avtorizacijo

Ko je API omogočen, partner prejmepartner_token inapi_secret , ki se uporabljajo za avtentikacijo pri klicu Slevomat API.

Ti parametri se posredujejo vX-PartnerToken inX-ApiSecret glave.

Testni vmesnik

Korenski URL testnega vmesnika je

https://www.slevomat.cz/zbozi-api/v1-test

Na njem lahko kličete vsa dejanja kot na živem vmesniku.

Testni vmesnik preverja avtorizacijo zahtev (pravilnost partnerskega žetona in API skrivnost) in veljavnost teles dohodnih zahtev (JSON). V teh pogledih se obnaša enako kot API v živo.

Vendar testni vmesnik ne deluje z dejanskimi naročili. Tako ne preveri, ali naročilo prehaja med pravilnimi stanji in ali vsebuje artikle z danimi ID-ji. Ko je avtorizacija in preverjanje obrazca zahteve uspešno, se testni vmesnik vedno ujema s kodo uspeha 200 ali 204.

Ustvarjanje preklica

Ustvari preklic postavk naročila v podani količini. V primeru, da se naročilo v celoti prekine, so navedeni vsi artikli z ustrezno količino.

Posamezne artikle je mogoče tudi delno odpovedati (npr. 1 od 2).

Odpoved (note ) ni obvezna.

POST /order/$slevomatId/cancel

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

Spremenite status naročila v "V teku"

POST /order/$slevomatId/mark-pending

{}

Spremenite status naročila v "Blago odposlano"

Za naročilo, autoMarkDelivered s parametrom lahko določite, ali naj se samodejno preklopi v status »Dostavljeno stranki – čaka na potrditev stranke« po nastavljenem času pošiljanja (»Čas od pošiljke do dostave«).

Odgovor vsebuje posodobljen predviden datum dostave.

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

{ "autoMarkDeli­vered": true }

Odgovor 200

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

Spremenite status naročila v "Pripravljeno za osebni prevzem"

Lahko uporabite parameterautoMarkReady­ForPickup da določite, ali naj se naročilo samodejno preklopi v status "Pripravljeno za osebni prevzem" po času od odpreme do dostave za dano vrsto prevzemnega mesta.

Za naročilo, autoMarkDelivered s parametrom lahko določite, ali naj samodejno preklopi iz statusa »Pripravljeno za osebni prevzem« v status »Dostavljeno stranki – čaka na potrditev stranke« po določenem številu dni za prevzem na dani vrsti prevzemnega mesta.

Kombinacija parametrovautoMarkReady­ForPickup lažno inautoMarkDelivered true ni dovoljeno. V tem primeru bo vrnjena koda napake 9.

Odgovor vsebuje posodobljen pričakovani datum dostave.

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

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

Odgovor 200

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

Spremenite status naročila v "Pripravljeno za osebni prevzem"

TheautoMarkDelivered s parametrom lahko določite, ali naj se naročilo samodejno preklopi v status "Dostavljeno stranki – čaka na potrditev stranke" po določenem številu dni za prevzem na dani vrsti prevzemnega mesta.

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

{ "autoMarkDeli­vered": true }

Spremenite status naročila v "Dostavljeno stranki – čaka na potrditev stranke"

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

{}

Spremenite naslov za dostavo

Naslov za dostavo se lahko spremeni le za dostavo na naslov (tj. mesta osebnega prevzema ni mogoče spremeniti).

Vsi ključi razencompany so potrebni.

Veljavne vrednosti zastate ključni socz (Češka) 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" }

Dnevnik sprememb