API roba treće strane

API se koristi za prijenos informacija o narudžbama između Diskontnog automata i sustava poslovnog partnera. API zahtijeva implementaciju dvosmjerne komunikacije – sustav Diskontnog automata poziva API partnera, a partner poziva API Diskontnog automata.

Nalozi izvezeni u partnerski API više se ne mogu manipulirati u partnerskom sučelju Zlavomat, već se mogu samo pregledavati. Izvezeni nalozi sada se mogu manipulirati samo putem API-ja.

Svi zahtjevi moraju biti poslani putem HTTPS-a, a svi podaci su u JSON formatu.

Pristupačnost API-ja

API-ju možete pristupiti na kartici Postavke vašeg partnerskog sučelja. Za dohvaćanje podataka morate unijeti korijenski URL partnerskog dijela API-ja za korištenje u smjeru Zlavomat → Partner, npr.

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

Podaci o pristupu prikazivat će se samo kada se pristupi API-ju, stoga ih čuvajte na sigurnom.

Nakon što API postane dostupan, sustav će početi izvoziti novokreirane narudžbe na njega.

Početni izvoz podataka

Za prijenos postojećih narudžbi u trenutku kada API postane dostupan, moguće je koristiti jednokratni izvoz u CSV u partnerskom sučelju.

Kada već imate postojeće narudžbe (kreirane prije nego što je API postao dostupan) u vlastitom sustavu i želite početi raditi s njima putem API-ja, upotrijebite funkciju "Počni raditi s označenim narudžbama putem API-ja" u izborniku "Skupne akcije s narudžbama".

Opis uobičajenih HTTP odgovora

• 200 OK – zahtjev je uspješno obrađen
• 204 No Content – zahtjev je uspješno obrađen, odgovor nema sadržaja
• 400 Bad Request – zahtjev nije valjan – moguće je da nedostaju ili su parametri nevažeći u usporedbi sa specifikacijom
• 403 Forbidden – autorizacija klijenta nije uspjela
• 404 Not Found – krajnja točka ili traženi podaci nisu pronađeni
• 405 Method Not Allowed – krajnja točka ne podržava ovu metodu HTTP protokola
• 422 Unprocessable Entity – očekivana greška prilikom obrade zahtjeva (vidi odjeljak Stanja grešaka )
• 500 Internal Server Error – došlo je do greške na strani servera
• 502 Bad Gateway – došlo je do greške na strani servera
• 503 Service Unavailable – poslužitelj je u načinu održavanja (možda je u tijeku implementacija nove verzije ili planirani prekid rada)
• 504 Gateway Timeout – došlo je do greške na strani servera

HTTP 5×x odgovori ne moraju koristiti JSON format.

U slučaju grešaka4xx Došlo je do pogreške u odlaznom zahtjevu i potrebno ju je ispraviti prije ponovnog pokušaja.

Pogreške5xx ukazuju na pogreške poslužitelja i zahtjev se može ponoviti bez promjene. U slučaju503 pozivatelj treba poštovati zaglavlje odgovoraRetry-After i ponovite sljedeći pokušaj tek nakon isteka vremena navedenog u zaglavlju.

Statusi narudžbi

Narudžba je uvijek u jednom od sljedećih statusa:

Kupac se o svakoj promjeni statusa obavještava putem e‑pošte.

Narudžba ne mora nužno proći kroz sve statuse da bi bila uspješno isporučena; iz statusa "Nova plaćena narudžba" moguće je odmah prijeći na "Na putu" / "Spremno za osobno preuzimanje", a zatim na "Dostavljeno kupcu – čeka se potvrda kupca". Međutim, korištenje svih statusa dovodi do bolje informiranosti kupaca o napretku narudžbe i preporučujemo ga.

Stanja grešaka

U slučaju HTTP 4×x kodova, odgovor uvijek sadrži ključstatus (vidi popis kodova u nastavku) i poljemessages s tekstualnim opisima grešaka.

Uzorak:

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

Vrste podataka

Tipovi podataka pojedinačnih ključeva u zahtjevima i odgovorima uvijek su opisani za određene krajnje točke. Osim ako nije drugačije navedeno, vrijednost je u navodnicima"" je uvijek obavezni niz. Osim ako nije drugačije navedeno, numerička vrijednost je uvijek obavezni cijeli broj.

Komunikacijski popustni stroj ⇒ Partner

Ovaj dio API-ja implementiran je na strani partnera i poziva ga Zlavovamat.

Partner će podijeliti potreban korijenski URL API-ja, a trebao bi biti u obliku

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

Autorizacija zahtjeva

Kada je API uključen, partner primapartner_api_se­cret , što dokazuje da dolazni zahtjevi zaista dolaze od Zlavomata.

Ovaj parametar se prosljeđuje u HTTP zaglavljuX-PartnerApiSecret .

Testno sučelje

Uređaj za popuste uključuje funkcionalnost za pozivanje API-ja na strani partnera i prikaz odgovora. Korijenski URL koji je partner naveo prilikom puštanja API-ja u rad priložen je uz-test , pa se kao dio testiranja API poziva na, na primjer,

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

kako bi se izbjeglo miješanje testnih podataka s aktivnim narudžbama.

Testiranje partnerskog API-ja provodi se pomoću POST zahtjeva na sljedeće adrese:

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

   – Nova narudžba

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

   – Skupno ažuriranje očekivanih datuma isporuke

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

   – Promjena statusa narudžbe u "Dostavljeno kupcu – čeka se potvrda kupca"

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

   – Promjena statusa narudžbe u "Spremno za osobno preuzimanje"

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

   – Potvrda o dostavi

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

   – Odbijanje prihvaćanja

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

   – Otkaži

Dio URL-a<orderId> zamijenite bilo kojim brojem narudžbe, zahtjevi partnerskom API-ju podnose se s ovim brojem narudžbe.

Zahtjevi prema ovom testnom sučelju moraju biti autorizirani zaglavljimaX-PartnerToken iX-ApiSecret .

Prilikom testiranja poziva partnerskog API-ja, sustav šalje zaglavljeX-PartnerApiSecret baš kao i u radu uživo.

Podaci poslani s novom narudžbom su testne prirode i generiraju se nasumično.

U slučaju slanja otkazivanja narudžbe, potrebno je u tijelo POST zahtjeva uključiti JSON polje.items (u istom formatu kao što API šalje), koje testno sučelje validira i prosljeđuje partnerskom API-ju u istom obliku.

Nova narudžba

Zahtjev sadrži podatke novokreirane narudžbe.

Narudžbe su uvijek jedinstvenezlavomatId Ako duplikat stigne u APIzlavomatId , partnerski API trebao bi ignorirati zahtjev (prvi zahtjev koji je podnio Zľavomat ocijenjen je kao neuspješan i stoga ga ponavljamo) i također odgovoriti s HTTP 204.

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

productId sadrži ID akcije, variantId ID kupljene varijante.

IzbornointernalId znači interni ID unesen za varijantu akcije prilikom njenog kreiranja u partnerskom sučelju. Koristi se za identifikaciju proizvoda u partnerskom sustavu.

UbillingAddress (adresa za naplatu) samo ime ( je obavezno)name ) kupca.

UshippingAddress (adresa za dostavu) je opcionalna tvrtka (company ). U slučaju dostave na adresushippingAddress sadrži adresu kupca, u slučaju osobnog preuzimanja, adresu trgovine u kojoj će kupac preuzeti robu.

Ključdelivery .type može poprimiti vrijednostiaddress (dostava na adresu) ilipickup (osobna kolekcija).delivery .name sadrži naziv prijevoza ili naziv operacije.

delivery .expec­tedShippingDa­te (očekivani datum otpreme) idelivery .expec­tedDeliveryDa­te (procijenjeni datum isporuke) je podatak u formatuYYYY-MM-DD .

Ključweight sadrži težinu narudžbe u kilogramima. Ako ne znamo težinu svih artikala u narudžbi, uzima vrijednostnull .

POST /narudžba/$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 /narudžba/$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 }

Skupno ažuriranje očekivanih datuma isporuke

Ako upravitelj poslova, na zahtjev partnera, skupno pomakne datume isporuke odabranih narudžbi, sustav obavještava partnerski API o tom ažuriranju.

Poslani podaci uključuju polje s ID-om narudžbe i novim očekivanim datumom isporuke.

POST /update-shipping-dates

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

Otkazati

Otkazivanja se mogu kreirati i na strani Zlavomata i na partnerskom sustavu. Ova krajnja točka obrađuje kreiranje otkazivanja na strani Zlavomata i njihov prijenos u partnerski sustav.

Stvara otkazivanje stavki narudžbe u navedenoj količini. Ako se cijela narudžba treba otkazati, navode se sve stavke s odgovarajućom količinom.

Pojedinačni artikli mogu se i djelomično otkazati (npr. 1 komad od dva).

Obavijest o otkazivanju (note ) nije obavezno.

POST /order/$slevo­matId/cancel

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

Potvrda o dostavi

Nakon što označite narudžbu kao "Dostavljeno kupcu", zatražit ćemo potvrdu od kupca da ju je zapravo primio. Kada je narudžba označena kao primljena, pozvat će se ova krajnja točka.

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

{}

Odbijanje prihvaćanja

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

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

Promjena statusa narudžbe u "Spremno za osobno preuzimanje"

Ova krajnja točka bit će pozvana ako je prethodni status "Priprema za osobno preuzimanje" bio postavljen naautoMarkRea­dyForPickuptrue a na strani Zlavomata narudžba je automatski prebačena u status "Spremno za osobno preuzimanje"

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

{}

Promjena statusa narudžbe u "Dostavljeno kupcu – čeka se potvrda kupca"

Ova krajnja točka bit će pozvana ako je prethodni status bio postavljen na "Na putu", "Priprema za osobno preuzimanje" ili "Spremno za osobno preuzimanje" sautoMarkDeli­veredtrue a na strani Zlavomata narudžba je automatski prebačena u status "Isporučeno kupcu – čeka se potvrda kupca".

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

{}

Komunikacijski partner ⇒ Automat za popuste

Ovaj dio API-ja implementiran je na strani Zľavomata i poziva ga partnerski sustav.

URL korijena API-ja je

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

PHP biblioteka

Za implementaciju ove API stranice možete koristiti gotovu PHP biblioteku. Biblioteka trenutno zahtijeva PHP verziju 5.4 ili noviju i pretpostavlja korištenje alata Composer.

Upute i izvorni kod biblioteke nalaze se na GitHubu .

Autorizacija zahtjeva

Kada je API uključen, partner primapartner_token iapi_secret , što se koristi za dokazivanje prilikom pozivanja Zlavomat API-ja.

Ovi parametri se prosljeđuju u zaglavljimaX-PartnerToken iX-ApiSecret .

Testno sučelje

Korijenski URL testnog sučelja je

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

Moguće je pozivati ​​sve akcije na njemu kao i na drugom sučelju.

Testno sučelje provjerava autorizaciju zahtjeva (ispravnost partnerskog tokena i API tajne) i valjanost dolaznih tijela zahtjeva (JSON). U tim se aspektima ponaša identično kao i aktivni API.

Međutim, testno sučelje ne radi sa stvarnim narudžbama. Ne provjerava prelazi li narudžba između ispravnih stanja i sadrži li stavke s zadanim ID-ovima. Nakon što autorizacija i validacija obrasca zahtjeva prođu, testno sučelje uvijek odgovara s kodom uspjeha 200 ili 204.

Kreiraj otkazivanje

Kreirajte stavke za otkazivanje narudžbe u određenoj količini. Ako se cijela narudžba treba otkazati, navedene su sve stavke s odgovarajućom količinom.

Pojedinačni artikli mogu se i djelomično otkazati (npr. 1 komad od dva).

Obavijest o otkazivanju (note ) nije obavezno.

POST /narudžba/$slevomatId/otkaz

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

Promjena statusa narudžbe u "U obradi"

POST /narudžba/$slevomatId/oznaka-na-čekanju

{}

Promjena statusa narudžbe u "Na putu"

Prilikom naručivanja, parametar jeautoMarkDelivered odrediti treba li se status automatski promijeniti u "Isporučeno kupcu – čeka se potvrda kupca" nakon postavljenog razdoblja prijevoza ("Vrijeme od otpreme do isporuke")

Odgovor uključuje ažurirani procijenjeni datum isporuke.

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

{ "autoMarkDeli­vered": true }

Odgovor 200

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

Promjena statusa narudžbe u "Priprema za osobno preuzimanje"

Prilikom naručivanja, parametar jeautoMarkReady­ForPickup odrediti treba li se status automatski prebaciti na "Spremno za osobno preuzimanje" nakon što istekne vrijeme od otpreme do isporuke za određenu vrstu mjesta preuzimanja.

Prilikom naručivanja, parametar jeautoMarkDelivered odrediti treba li se status automatski promijeniti iz "Spremno za osobno preuzimanje" u "Dostavljeno kupcu – čeka se potvrda kupca" nakon zadanog broja dana za preuzimanje na određenoj vrsti mjesta preuzimanja.

Kombinacija parametaraautoMarkReady­ForPickup lažno iautoMarkDelivered Vrijednost "true" nije dopuštena. U ovom slučaju vraća se kod pogreške 9.

Odgovor uključuje ažurirani procijenjeni datum isporuke.

POŠTA /narudžba/$slevomatId/oznaka-spremnosti-za-preuzimanje

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

Odgovor 200

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

Promjena statusa narudžbe u "Spremno za osobno preuzimanje"

Prilikom naručivanja, parametar jeautoMarkDelivered odrediti treba li se status automatski promijeniti u "Dostavljeno kupcu – čeka se potvrda kupca" nakon zadanog broja dana za preuzimanje za određenu vrstu mjesta preuzimanja.

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

{ "autoMarkDeli­vered": true }

Promjena statusa narudžbe u "Dostavljeno kupcu – čeka se potvrda kupca"

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

{}

Promjena adrese za dostavu

Adresa za dostavu može se promijeniti samo prilikom dostave na adresu (tj. mjesto sličnog preuzimanja ne može se promijeniti).

Sve tipke osimcompany su obavezni.

Važeće vrijednosti za ključstate sucz (Češka) isk (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" }