API blago tretjih oseb

API se uporablja za prenos podatkov o naročilu med Discountomat in sistemom trgovskega partnerja. API zahteva izvedbo dvostranske komunikacije – API partnerja pokliče Discount sistem, partner pa API Discount.

Z naročili, izvoženimi v partnerski API, ni več mogoče manipulirati v partnerjevem vmesniku, le ogledovati. Manipulacija z izvoženimi naročili je možna le prek API-ja.

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

API dostopnost

Do API-ja lahko dostopate na zavihku Nastavitve v svojem partnerskem vmesniku. Za pridobitev podatkov morate vnesti URL korenske kode partnerskega dela API-ja za uporabo v smeri Zlevomat → Partner, npr.

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

Podatki o dostopu bodo prikazani samo, ko se dostopa do API-ja, pozorno jih preberite, skrbno jih shranite.

Ko je API dostopen, se novo ustvarjena naročila vnesejo vanj, tako da sistem začne izvažati naročila v sistem.

Začetni izvoz podatkov

Za prekoračitev obstoječih naročil v trenutku, ko je API na voljo Uporabite lahko enkraten izvoz v CSV v partnerskem vmesniku.

V trenutku, ko imate v lastnem sistemu obstoječa naročila (ustvarjena pred dostopom API) in želite z njimi začeti delati preko API-ja, uporabite funkcijo "Začni delati z označenimi naročili preko API-ja" v meniju "Množična dejanja z naročili". .

Opis pogostih odzivov HTTP

• 200 OK – zahteva je bila uspešno obdelana
• 204 No Content – zahteva je bila uspešno 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 protokola HTTP
• 422 Unprocessable Entity – pričakovana napaka pri obdelavi zahteve (glejte razdelek Pogoji napake )
• 500 Internal Server Error – prišlo je do napake na strežniku strani
• 502 Bad Gateway – prišlo je do napake na strani strežnika
• 503 Service Unavailable – strežnik je v vzdrževalnem načinu (morda poteka uvajanje nove različice ali načrtovani izpad)
• 504 Gateway Timeout – prišlo je do napake na strežniku na strani strežnika

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

V primeru4xx napake, je napaka v odhodni zahtevi 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 naslednji poskus ponovite šele po preteku časa, določenega v glavi.

Stanja naročila

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, da bi bilo uspešno dostavljeno, možno je preiti neposredno iz statusa »Novo plačano naročilo« v »Na poti« / »Pripravljeno za prevzem« in nato v »Dostavljeno stranki – čaka na potrditev stranke«. Uporaba vseh statusov pa vodi do boljše obveščenosti stranke o poteku obdelave naročila in jo priporočamo.

Stanja napak

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

primer:

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

Vrste podatkov

Tipi podatkov posameznih ključev 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 Discountomat ⇒ Partner

Ta del API-ja je implementiran na strani partnerja in ga uporabljajo klici Zlevomat.

Zahtevani korenski URL API-ja je v skupni rabi s partnerjem, mora biti v obliki

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

Zahtevaj avtorizacijo

Ko je API omogočen, partner prejmepartner_api_se­cret , pri katerem se dohodni zahtevki preverijo, ali res prihajajo iz Popusta.

Ta parameter se posreduje v glavi HTTPX-PartnerApiSecret .

Testni vmesnik

Discountomat vključuje funkcionalnost za klic API-ja na strani partnerja in prikaz odgovora. Na korenski URL, ki ga določi partner ob dostopu do API-ja-test je pripet partnerjevemu URL-ju, tako da se pri testiranju imenuje API 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 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

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

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

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

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

   – Spremenite status 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

   – Odpoved

Zamenjajte<orderId> del URL-ja s poljubno številko naročila številke, s to številko naročila se zahteve prenesejo na API partnerja.

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

Ko se izvede testni klic partnerskemu API-ju, sistem pošlje glavoX-PartnerApiSecret glavo tako kot pri delovanju v živo.

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

V primeru pošiljanja preklica naročila, POST telo zahteve vključite v polje JSONitems (v enakem formatu, kot ga je poslal API), ki ga bo preskusni vmesnik potrdil in poslal partnerskemu API-ju, ga bo posredoval API v istem formatu.

Novo naročilo

Zahteva vsebuje podatke novo oblikovanega naročila.

Naročila imajo vedno unikatzlavomatId . Če je API dvojnikzlavomatId prispe, je treba zahtevo ignorirati (prvo pretvorjeno zahtevo je Discountomat ocenil kot neuspešno, zato jo ponavljamo) in odgovoriti tudi s HTTP 204.

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

productId vsebuje ID dogodka, variantId ID kupljene variante.

NeobveznointernalId označuje notranji ID, vnesen pri različici dejanja, ko je ustvarjeno v partnerskem vmesniku. Služi za identifikacijo produkta v sistemu partnerja.

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

notershippingAddress (naslov za dostavo) podjetje ni obvezno (company ). V primeru dostave doshippingAddress vsebuje naslov kupca, v primeru osebne dostave pa naslov lokala, kjer kupec prevzame blago.

Ključdelivery .type lahko prevzamejo vrednoteaddress (dostava na naslov) ozpickup (osebni prevzem).delivery .name vsebuje ime prevoza ali ime operacije.

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

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

POST /order/$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 /order/$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 potisne datume pošiljanja množičnih podatkov za izbrana naročila, 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–09–06", "slevomatIds": [ "123456", "45454544" ] }

Odpovedi

Preklici se lahko ustvarijo tako na strani Popust kot na partnerski strani. Ta končna točka skrbi za ustvarjanje stornacije na strani Zlatomata in njen prenos v sistem partnerja.

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

Posamezne artikle je možno tudi delno odpovedati (npr. 1 kos 2).

Odpoved (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 označite naročilo kot »Dostavljeno stranki«, bomo od stranke zahtevali potrditev, da jo je 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 prevzem"

Ta končna točka bo poklicana, če je bila prejšnja končna točka nastavljena s statusom »Pripravljeno za osebni prevzem«.autoMarkRea­dyForPickuptrue in na strani Popusti je naročilo samodejno prestavljeno na "Pripravljeno za osebni prevzem"

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

{}

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

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

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

{}

Komunikacijski partner ⇒ Zľavomat

Ta del API-ja je implementiran na strani Discountomat in ga imenuje partnerski sistem.

Korenski URL API-ja je

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

PHP knjižnica

Za implementacijo te strani API-ja je možno uporabiti pripravljeno knjižnico PHP. Knjižnica trenutno zahteva različico PHP 5.4 ali novejšo in predvideva uporabo orodja Composer.

Navodila za uporabo knjižnice in izvorna koda so na GitHubu .

Zahteve za avtorizacijo

Ko je API omogočen, partner prejmepartner_token inapi_secret , ki se uporabljajo za avtentikacijo klica Zlatomat API.

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

Testni vmesnik

Korenski URL preskusnega vmesnika je

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

Na njem je mogoče priklicati vse akcije kot na drugem vmesniku.

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

Vendar testni vmesnik ne deluje z dejanskimi naročili. Tako ne preverja, ali naročilo prehaja med pravilnimi stanji in ali vsebuje elemente z danimi ID-ji. Ko avtorizacija in potrditev prestaneta obrazce zahteve, se testni vmesnik vedno odzove z uspešno kodo 200 ali 204.

Ustvarjanje preklica

Ustvarite preklic artiklov naročila v določeni količini. Če ima naročilo za preklic v celoti, so vsi artikli navedeni z ustrezno količino.

Posamezne artikle je možno tudi delno odpovedati (npr. 1 kos od dveh).

Odpoved (note ) ni obvezna.

POST /order/$slevomatId/cancel

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

Spremenite status naročila v "V obdelavi"

POST /order/$slevomatId/mark-pending

{}

Spremenite status naročila v "Na poti"

Ko je naročilo oddano, seautoMarkDelivered parameter se uporablja za določitev, ali naj se po nastavljenem obdobju pošiljanja ("Čas od pošiljanja do dostave") samodejno preklopi v status "Dostavljeno stranki – čaka na potrditev stranke".

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"

Ko gre naročilo skoziautoMarkReady­ForPickup parameter za določitev, ali naj se čas od odpreme do dostave za dano vrsto zbiralnice samodejno preklopi v status "Pripravljeno za dostavo". za osebni prevzem«.

Ob naročilu, autoMarkDelivered parameter določa, ali naj se prevzemno mesto po nastavljenem številu dni za prevzem za dani tip prevzemnega mesta samodejno preklopi iz statusa »Pripravljeno za osebni prevzem« v »Dostavljeno stranki – čaka na potrditev s strani stranke«.

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

Odgovor vsebuje posodobljen predviden datum dostave.

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

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

Odgovor 200

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

Spremenite status naročila v "Pripravljeno za prevzem"

Ko je naročilo oddano, seautoMarkDelivered parameter se uporablja za določitev, ali naj se po določenem številu dni za prevzem za dano vrsto prevzema zbirno mesto samodejno preklopi v status "Dostavljeno stranki – čaka na potrditev stranke".

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 samo ob dostavi na naslov (tj. mesta prevzema ne morete 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" }