API roba treće strane

API se koristi za prijenos podataka o narudžbi između Discountomata i sustava trgovačkog partnera. API zahtijeva implementaciju dvostrane komunikacije – partnerski API poziva sustav Discount, a partner API popust.

S narudžbama izvezenim u partnerski API više nije moguće manipulirati u sučelju partnera, samo ih pregledavati. Manipulacija izvezenim narudžbama može se izvršiti samo putem API -ja.

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

Pristupačnost API -ja

API -ju možete pristupiti s kartice Postavke na vašem sučelju za partnere. Za dobivanje podataka trebate unijeti URL korijenskog koda partnerskog dijela API -ja za upotrebu u smjeru Zlevomat → Partner, npr.

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

Pristupni podaci bit će prikazani samo kada se pristupi API -ju, pažljivo ih pročitajte i pažljivo ih zadržite.

Nakon pristupa API -ju, sustav će unijeti u njega novonastale narudžbe koje će početi izvoziti naloge u sustav.

Početni izvoz podataka

Za prelijevanje postojećih narudžbi u trenutku kada je API dostupan. Može se koristiti jednokratni izvoz u CSV u partnerskom sučelju.

U trenutku kada imate postojeće narudžbe (stvorene prije pristupa API -ju) u svom 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 radnje 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žaj
• 400 Bad Request – zahtjev nije važeći – mogu nedostajati ili su parametri neispravni u odnosu na specifikaciju
• 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 pri obradi zahtjeva (vidi odjeljak Uvjeti greške )
• 500 Internal Server Error – došlo je do pogreške na poslužitelju stranica
• 502 Bad Gateway – došlo je do pogreške na strani poslužitelja
• 503 Service Unavailable – poslužitelj je u načinu održavanja (moguće je uvođenje nove verzije ili planirano vrijeme zastoja)
• 504 Gateway Timeout – došlo je do pogreške na poslužitelju na strani poslužitelja

HTTP odgovori 5 × x možda ne koriste JSON format.

U slučaju4xx greške, greška je 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 bi trebao poštivatiRetry-After zaglavlje odgovora i sljedeći pokušaj pokušajte ponovno tek nakon isteka vremena navedenog u zaglavlju.

Države reda

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

Kupac je obaviješten o svakoj promjeni statusa putem e -pošte.

Narudžba ne mora nužno proći sve statuse da bi bila uspješna isporuka, moguće je prijeći ravno iz statusa "Nova plaćena narudžba" u "Na putu" / "Spremno za preuzimanje", a zatim u "Isporučeno kupcu – čeka potvrdu klijenta ". Korištenje svih statusa, međutim, vodi do boljih informacija o napretku obrade narudžbe i preporučujemo je.

Stanja grešaka

U slučaju 4 × x HTTP kodova, odgovor uvijek sadrži ključstatus (pogledajte donji popis kodova) i poljemessages s opisom grešaka u tekstu.

Primjer:

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

Vrste podataka

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

Komunikacijski popust mat Partner

Ovaj dio API -ja implementiran je na strani partnera i koristi se pozivima Zlevomat.

Potrebni korijenski URL API -ja dijeli partner, trebao bi biti u obliku

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

Zatražite autorizaciju

Kad je API omogućen, partner primapartner_api_se­cret , kojima se dolazni zahtjevi provjeravaju da li zaista dolaze s Popust.

Ovaj se parametar prenosi u HTTP zaglavljuX-PartnerApiSecret .

Testno sučelje

Discountomat uključuje funkcionalnost za pozivanje API -ja na strani partnera i prikaz odgovora. Na korijenski URL koji je odredio partner prilikom pristupa API -ju-test je pridružen URL -u partnera, tako da se pri testiranju naziva API na npr

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

kako bi se izbjeglo miješanje testnih podataka s aktivnim nalozima.

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

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

   – Novi poredak

• 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

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

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

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

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

   – Potvrda isporuke

• 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

   – Otkazivanje

Zamijenite<orderId> dio URL -a s bilo kojim brojem narudžbe s brojem, pri čemu se zahtjevi za broj narudžbe prenose API partneru.

Zahtjevi za ovo testno sučelje moraju se autorizirati zaglavljimaX-PartnerToken iX-ApiSecret .

Kad se uputi probni poziv na partnerski API, sustav šalje zaglavljeX-PartnerApiSecret zaglavlje isto kao i pri radu uživo.

Podaci poslani novom narudžbom testni su podaci i generirani nasumično.

U slučaju slanja otkazivanja narudžbe, tijelo POST zahtjeva, uključite u polje JSONitems (u istom formatu koji je poslao API), koji će biti potvrđen sučeljem za testiranje i poslan partnerskom API -ju API -ja, proslijedit će ga u istom formatu.

Novi poredak

Zahtjev sadrži podatke o novonastaloj narudžbi.

Narudžbe uvijek imaju jedinstvenezlavomatId . Ako je API duplikatzlavomatId stiže, zahtjev treba zanemariti (Discountomat je prvi pretvoreni zahtjev ocijenio neuspjelim pa ga ponavljamo) i odgovoriti također s HTTP 204.

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

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

IzbornointernalId označava interni ID koji se unosi prilikom varijante radnje kada je stvorena u partnerskom sučelju. Služi za identifikaciju proizvoda u partnerskom sustavu.

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

UshippingAddress (adresa za isporuku) tvrtka nije obavezna (company ). U slučaju dostave doshippingAddress sadrži adresu kupca, u slučaju osobne dostave, adresu ustanove u kojoj kupac preuzima robu.

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

delivery .expec­tedShippingDa­te (očekivani 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. U slučaju da ne znamo težinu svih artikala u narudžbi, ona uzima vrijednostnull .

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 }

Skupno ažuriranje očekivanih datuma isporuke

Ako upravitelj ponuda, na zahtjev partnera, gurne datume dostave skupnih podataka za odabrane narudžbe, sustav obavještava partnerski API 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–09–06", "slevomatIds": [ "123456", "45454544" ] }

Otkazivanja

Otkazivanja se mogu izvršiti i na sustavu s popustom i na partnerskom sustavu. Ova krajnja točka upravlja stvaranjem otkazivanja na strani Zlavomat i njegovim prijenosom u partnerski sustav.

On stvara otkazivanje stavki narudžbe u navedenoj količini. Ako se otkaže cijela narudžba, sve stavke su navedene s odgovarajućom količinom.

Pojedine stavke mogu se i djelomično otkazati (npr. 1 komad od dva).

Napomena o otkazu (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 isporuke

Nakon što označite narudžbu kao "Isporučeno kupcu", od klijenta ćemo zatražiti potvrdu da ga je stvarno primio. Kada je narudžba označena kao primljena, pozvat će se ta 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" }

Promijenite status narudžbe u "Spremno za preuzimanje"

Ova će se krajnja točka pozvati ako jeprevious krajnja točka je "Spremno za osobno prikupljanje" status je postavljen saautoMarkRea­dyForPickuptrue a na stranici Popust narudžba je automatski prebačena na "Spremno za osobno preuzimanje"

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

{}

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

Ova će se krajnja točka pozvati ako jeprevious status "Na putu", "Spremno za osobno preuzimanje" ili "Spremno za osobno preuzimanje" postavljeno je sautoMarkDeli­veredtrue a na stranici Popust narudžba je automatski prebačena u status "Isporučeno kupcu – čeka se potvrda kupca".

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

{}

Komunikacijski partner ⇒ Zľavomat

Ovaj dio API -ja implementiran je na strani Discountomat i naziva ga partnerskim sustavom.

Korijenski URL API -ja je

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

PHP biblioteka

Za implementaciju ove strane API -ja moguće je koristiti pripremljenu PHP knjižnicu. Knjižnica trenutno zahtijeva PHP verziju 5.4 ili noviju i pretpostavlja upotrebu alata Composer.

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

Zahtjevi za autorizaciju

Kad je API omogućen, partner primapartner_token iapi_secret , koji se koriste za provjeru autentičnosti Zlavomat API poziva.

Ovi parametri se prenose u zaglavljaX-PartnerToken iX-ApiSecret .

Testno sučelje

Korijenski URL testnog sučelja je

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

Na njemu je moguće pozvati sve radnje kao i na drugom sučelju.

Testno sučelje provjerava autorizaciju zahtjeva (partnerski token ispravnosti i API tajna) i valjanost dolaznih tijela zahtjeva (JSON). U tom pogledu, ponaša se identično kao oštar API.

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

Stvaranje otkaza

Izradite otkazivanje stavki narudžbe u navedenoj količini. Ako narudžba mora biti poništena u cijelosti, sve stavke navedene su s odgovarajućom količinom.

Pojedine stavke mogu se i djelomično otkazati (npr. 1 od dvije stavke).

Napomena o otkazu (note ) nije obavezno.

POST/order/$ slevomatId/cancel

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

Promijenite status narudžbe u "U tijeku"

POST/order/$ slevomatId/mark-pending

{}

Promijenite status narudžbe u "Na putu sam"

Prilikom naručivanja, autoMarkDelivered parametar se koristi za određivanje treba li se nakon postavljenog razdoblja isporuke ("Vrijeme od otpreme do isporuke") automatski prebaciti u status "Dostavljeno kupcu – čeka se potvrda kupca".

Odgovor sadrži ažurirani predviđeni datum isporuke.

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

{ "autoMarkDeli­vered": true }

Odgovor 200

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

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

Kad narudžba prođe krozautoMarkReady­ForPickup parametar za određivanje, treba li se vrijeme od otpreme do isporuke za datu vrstu zbirnog mjesta automatski prebaciti u status "Spremno za isporuku". za osobno prikupljanje ".

Prilikom naručivanja, autoMarkDelivered parametar određuje treba li nakon postavljenog broja dana preuzimanja za datu vrstu zbirnog mjesta automatski preći iz statusa "Spremno za osobno preuzimanje" u "Isporučeno kupcu – čeka se potvrda od strane kupca".

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

Odgovor sadrži ažurirani predviđeni datum isporuke.

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

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

Odgovor 200

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

Promijenite status narudžbe u "Spremno za preuzimanje"

Prilikom naručivanja, autoMarkDelivered parametar se koristi za određivanje treba li nakon postavljenog broja dana preuzimanja za određeno mjesto preuzimanja vrste preuzimanja automatski preći u status "Dostavljeno kupcu – čeka se potvrda kupca".

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

{}

Promijenite adresu za dostavu

Adresa za dostavu može se promijeniti samo prilikom dostave na adresu (tj. Ne možete promijeniti mjesto 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" }