API treće strane

API se koristi za prijenos informacija o narudžbama između Slevomata i sustava našeg trgovačkog partnera. API zahtijeva implementaciju dvosmjerne komunikacije – Slevomat sustav poziva partnerov API, a partner poziva Slevomatov API.

Nalozima izvezenim u partnerski API više se ne može manipulirati u partnerskom sučelju Slevomat, već samo pregledavati. Manipulacija izvezenim nalozima može se odvijati samo putem API-ja.

Svi zahtjevi moraju biti postavljeni na HTTPS i svi podaci su u JSON formatu.

API pristup

Možete pristupiti API vjerodajnicama na kartici Postavke u sučelju svog partnera. Za dobivanje podataka trebate dati korijenski URL partnerskog dijela API-ja za korištenje u smjeru Slevomat → Partner, npr.

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

Pristupni podaci bit će prikazani samo jednom kada pristupite API-ju, pažljivo ih spremite.

Nakon što se pristupi API-ju, sustav će u njega početi izvoziti novostvorene naloge.

Početni izvoz podataka

Za prijenos postojećih naloga u trenutku pristupa API-ju, možete koristiti jednokratni izvoz u CSV u partnerskom sučelju.

Ako imate postojeće naloge (kreirane prije nego što je API postao dostupan) u vlastitom sustavu i želite početi raditi s njima putem API-ja, koristite funkciju "Počnite raditi s označenim nalozima putem API-ja" u "Skupnim radnjama s nalozima" Jelovnik.

Opis uobičajenih HTTP odgovora

• 200 OK – zahtjev je uspješno obrađen
• 204 No Content – zahtjev je obrađen, odgovor je bez sadržaja
• 400 Bad Request – zahtjev nije valjan – parametri mogu nedostajati ili su nevažeći u odnosu na specifikaciju
• 403 Forbidden – autorizacija klijenta nije uspjela
• 404 Not Found – krajnja točka ili potrebni podaci nisu pronađeni
• 405 Method Not Allowed – krajnja točka ne podržava ovu HTTP metodu
• 422 Unprocessable Entity – očekivana pogreška tijekom obrade zahtjeva (pogledajte odjeljak Uvjeti pogreške )
• 500 Internal Server Error – došlo je do greške na strani poslužitelja
• 502 Bad Gateway – došlo je do pogreške na strani poslužitelja
• 503 Service Unavailable – poslužitelj je u načinu rada za održavanje (implementacija nove verzije može biti u tijeku ili planirani zastoj)
• 504 Gateway Timeout – došlo je do pogreške na strani poslužitelja

HTTP 5×x odgovori možda neće koristiti JSON format.

U slučaju4xx pogreške, odlazni zahtjev je pogrešan i treba ga ispraviti prije ponovnog pokušaja.

Greške5xx ukazuju na pogreške poslužitelja i zahtjev se može ponoviti bez promjene. U slučaju503 , pozivatelj treba poštovatiRetry-After zaglavlje odgovora i pokušajte ponovno tek nakon što istekne vrijeme navedeno u zaglavlju.

Statusi narudžbi

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

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

Narudžba ne mora nužno proći sve statuse za uspješnu isporuku, iz "Nova narudžba plaćena" moguće je ići ravno na "Roba otpremljena" / "Spremno za osobno preuzimanje" pa na "Isporučeno kupcu – čeka se potvrda kupca" ". Korištenje svih statusa, međutim, vodi boljem informiranju kupca o tijeku narudžbe i preporučuje se.

Stanja pogreške

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

Primjer:

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

Vrste podataka

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

Komunikacijski Slevomat ⇒ Partner

Ovaj dio API-ja implementiran je na strani partnera i Slevomat ga naziva.

Potreban API korijenski URL daje partner i trebao bi biti u obrascu

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

Zahtjev za autorizaciju

Kada je API omogućen, partner primapartner_api_se­cret , što dokazuje da su dolazni zahtjevi doista od Slevomata.

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

Test sučelja

Slevomat uključuje funkcionalnost za pozivanje API-ja na strani partnera i pregled odgovora. Pridodaje se korijenski URL koji je naveo partner kada je API postao dostupan-test , tako da se u testiranju API poziva na npr

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

kako biste izbjegli miješanje testnih podataka sa živim nalozima.

Testiranje partnerskog API-ja vrši se putem POST zahtjeva na sljedeće adrese:

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

   – Novi poredak

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

   – Skupno ažuriranje očekivanih datuma otpreme

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

   – Promijenite status narudžbe u "Isporučeno kupcu – čeka se potvrda kupca"

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

   – Promijenite status narudžbe u "Spremno za osobno preuzimanje"

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

   – Potvrda isporuke

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

   – Odbijanje prihvaćanja

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

   – Otkazivanje

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

Zahtjevi za ovo testno sučelje moraju biti autorizirani zaglavljimaX-PartnerToken iX-ApiSecret .

Prilikom probnog poziva partnerskom API-ju, sustav šaljeX-PartnerApiSecret zaglavlje kao što je to slučaj u radu uživo.

Podaci koji se šalju s novom narudžbom su testni podaci i generiraju se nasumično.

U slučaju slanja otkazivanja narudžbe, morate uključitiitems polje u POST tijelu zahtjeva u JSON-u (u istom formatu kakav je poslao API), koje će sučelje za testiranje potvrditi i proslijediti partnerskom API-ju u istom obliku.

Novi poredak

Zahtjev sadrži podatke novoizrađenog naloga.

Narudžbe uvijek imaju unikatslevomatId . Ako API primi duplikatslevomatId , partnerski API bi trebao zanemariti zahtjev (prvi zahtjev je Slevomat ocijenio kao neuspješan i stoga je ponovljen), a odgovor bi također trebao bitiHTTP 204 .

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

productId sadrži ID događaja, variantId ID kupljene varijante.

NeobaveznointernalId označava interni ID unesen za varijantu radnje kada je kreirana u partnerskom sučelju. Koristi se za identifikaciju proizvoda u sustavu partnera.

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

UshippingAddress (adresa za dostavu) tvrtka (company ) nije obavezan. U slučaju dostave doshippingAddress sadrži adresu kupca, au slučaju osobnog preuzimanja adresu poslovnice u kojoj će kupac preuzeti robu.

Ključdelivery .type može uzeti vrijednostaddress (dostava na adresu) odnpickup (osobno preuzimanje).delivery .name sadrži naziv prijevoza ili naziv ustanove.

delivery .expec­tedShippingDa­te (procijenjeni datum otpreme) idelivery .expec­tedDeliveryDa­te (predviđeni datum isporuke) su podaci u formatuYYYY-MM-DD .

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

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

Masovno ažuriranje očekivanih datuma otpreme

Ako voditelj poslova, na zahtjev partnera, pomiče datume otpreme odabranih narudžbi, sustav obavještava API partnera o ovom ažuriranju.

Poslani podaci sadrže polje ID narudžbe i novi očekivani datum otpreme.

POST /update-shipping-dates

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

Otkazivanje

Otkazi se mogu kreirati i na strani Slevomat i na partnerskom sustavu. Ova krajnja točka upravlja kreiranjem otkaza na strani Slevomat i njegovim prijenosom u sustav partnera.

Stvara otkazivanje stavki narudžbe u navedenoj količini. Ako se cijela narudžba poništava, navedeni su svi artikli s odgovarajućom količinom.

Pojedinačne artikle moguće je i djelomično stornirati (npr. 1 od 2).

Napomena o otkazu (note ) nije obavezan.

POST /order/$slevo­matId/cancel

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

Potvrda isporuke

Nakon što narudžbu označite kao "Isporučeno kupcu", od kupca ćemo tražiti potvrdu da ju je stvarno primio. Kada je nalog označen kao primljen, ova krajnja točka će biti pozvana.

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 će krajnja točka biti pozvana ako je postavljen prethodni status "Spremno za osobno preuzimanje".autoMarkRea­dyForPickuptrue a narudžba je automatski prebačena na "Spremno za osobno preuzimanje" na strani Slevomat.

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

{}

Promijenite status narudžbe u "Isporučeno kupcu – čeka se potvrda kupca"

Ova se krajnja točka poziva ako je prethodni status "Na putu", "Spremno za osobno preuzimanje" ili "Spremno za osobno preuzimanje" postavljen sautoMarkDeli­veredtrue te je narudžba automatski prebačena u status "Isporučeno kupcu – čeka se potvrda kupca" na strani Slevomat.

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

{}

Komunikacijski partner ⇒ Slevomat

Ovaj dio API-ja implementiran je na strani Slevomat i poziva ga partnerski sustav.

Korijenski URL API-ja je

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

PHP biblioteka

Za implementaciju ove strane API-ja, možete koristiti pripremljenu PHP biblioteku. Biblioteka trenutno zahtijeva PHP 5.4 ili noviji i zahtijeva upotrebu Composer-a.

Upute za korištenje knjižnice i izvornog koda nalaze se na GitHubu .

Zahtjev za autorizaciju

Kada je API omogućen, partner primapartner_token iapi_secret , koji se koriste za autentifikaciju prilikom pozivanja Slevomat API-ja.

Ovi parametri se prosljeđuju uX-PartnerToken iX-ApiSecret zaglavlja.

Test sučelja

Korijenski URL testnog sučelja je

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

Na njemu se mogu pozivati ​​sve akcije kao na sučelju uživo.

Testno sučelje provjerava autorizaciju zahtjeva (ispravnost partnerskog tokena i API tajne) i valjanost tijela dolaznih zahtjeva (JSON). U tom smislu, ponaša se identično kao API uživo.

Međutim, sučelje za testiranje ne radi sa stvarnim narudžbama. Stoga ne provjerava prelazi li narudžba između točnih stanja i sadrži li stavke s danim ID-ovima. Nakon što prođe autorizacija i provjera obrasca zahtjeva, testno sučelje uvijek odgovara kodu uspjeha 200 ili 204.

Izrada otkaza

Kreira otkazivanje stavki narudžbe u navedenoj količini. Ako se narudžba u cijelosti poništava, navedeni su svi artikli s odgovarajućom količinom.

Pojedinačne artikle moguće je i djelomično stornirati (npr. 1 od 2).

Napomena o otkazu (note ) nije obavezan.

POST /order/$slevomatId/cancel

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

Promjena statusa narudžbe u "Na čekanju"

POST /order/$slevomatId/mark-pending

{}

Promjena statusa narudžbe u "Roba poslana"

Za narudžbu, autoMarkDelivered Parametar se može koristiti za određivanje treba li se automatski prebaciti u status "Isporučeno kupcu – čeka potvrdu kupca" nakon postavljenog vremena otpreme ("Vrijeme od otpreme do isporuke").

Odgovor sadrži 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 "Spremno za osobno preuzimanje"

Možete koristiti parametarautoMarkReady­ForPickup kako biste odredili treba li se narudžba automatski prebaciti u status "Spremno za osobno preuzimanje" nakon vremena od otpreme do isporuke za određenu vrstu sabirnog mjesta.

Za narudžbu, autoMarkDelivered Parametar se može koristiti za određivanje treba li se automatski prebaciti iz statusa "Spremno za osobno preuzimanje" u status "Isporučeno kupcu – čeka se potvrda kupca" nakon određenog broja dana za preuzimanje na danoj vrsti sabirnog mjesta.

Kombinacija parametaraautoMarkReady­ForPickup lažno iautoMarkDelivered istinito nije dopušteno. U tom će slučaju biti vraćen kod pogreške 9.

Odgovor sadrži ažurirani očekivani datum isporuke.

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

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

Odgovor 200

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

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

TheautoMarkDelivered Parametar se može koristiti za određivanje treba li se narudžba automatski prebaciti u status "Isporučeno kupcu – čeka potvrdu kupca" nakon određenog broja dana za preuzimanje na danoj vrsti sabirnog mjesta.

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

{ "autoMarkDeli­vered": true }

Promijenite status narudžbe u "Isporučeno kupcu – čeka se potvrda kupca"

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

{}

Promjena adrese za dostavu

Adresa dostave se može promijeniti samo za dostavu na adresu (tj. ne može se promijeniti mjesto osobnog preuzimanja).

Svi ključevi osimcompany su potrebni.

Važeće vrijednosti zastate ključni 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" }

Dnevnik promjena