Kako pravilno povezati MALL Partner API

API

U sljedećem članku detaljno ćemo prikazati preporučeni način povezivanja pojedinačnih tokova podataka unutar API veze vaše tvrtke.

Testno okruženje: Postoji samo jedno okruženje za testiranje i stvarnu prodaju, i to produkcija. API ključ koji dobijete nakon registracije stoga je nepromjenjiv i konačan. Međutim, prvo možete testirati vezu. Vaš račun je samo u testnom načinu rada dok se ne aktivira. Međutim, konačni prikaz vaše ponude na web stranici dogodit će se tek nakon odobrenja odjela za uvođenje u posao, za više informacija obratite se svom stručnjaku za uvođenje u posao.

Vrlo je važno slijediti sljedeće preporuke. Posljedice nepoštivanja preporučenih praksi mogu biti ograničavajuće za funkcioniranje API poziva vaše tvrtke, s obzirom na opterećenje MALL sustava. Uzimajući u obzir ove činjenice, unutar MALL platforme djeluje ograničavač brzine , o čemu možete saznati više u članku ovdje . Sva prekoračenja SLA-a uzrokovana neispravnom implementacijom API-ja i prekoračenje ograničenja brzine odgovornost su partnera.

Imajte na umu da je MALL API izvor informacija u trenutku potrebe, a ne baza podataka koja se koristi za pohranu povijesnih podataka. API pozivi ove prirode mogu biti ograničeni.

Za autorizaciju svih API poziva unutar MALL veze koristite ID klijenta ili "API ključ". API ključ ima kombinaciju znakova koji su jedinstveni za svaki račun i moraju biti priloženi svakom pojedinačnom API pozivu. Ako imate više računa na MALL-u, ključ će biti jedinstven za svaki račun. API ključ možete pronaći na MALL partnerskom portalu u odjeljku "Profil tvrtke" na kartici "Informacije".

Sadržaj

Narudžbe
- Narudžbe s webhookom
- Narudžbe bez webhooka
Proizvodi
Kategorija
- Stablo kategorija za pojedinačne zemlje
- Detalji kategorije, vrijednosti i parametri
Robne marke
Oznake

Narudžbe

Unutar krajnjih točaka narudžbe važno je obratiti pozornost na redoslijed pojedinačnih koraka. To je podijeljeno u dvije osnovne opcije ovisno o tome koristite li webhook za dobivanje informacija o promjenama u narudžbama. Više o webhookovima možete pročitati ovdje .

U ovom članku naučit ćete kako ispravno povezati pojedinačne metode i prebaciti pojedinačna stanja unutar API-ja. Također preporučujemo da pročitate članak koji detaljno objašnjava pojedinačna stanja koja narudžba može poprimiti i što ona znače ovdje .

Također imajte na umu da ako koristite usluge dostave putem MALL-a, postupak se razlikuje u smislu preuzimanja pošiljke i ažuriranja statusa u kasnijim koracima.

Važno : Molimo vas da šaljete ažuriranja statusa narudžbe samo ako postoje promjene u vašoj narudžbi. Ponavljano slanje istih informacija je krajnje nepoželjno i opterećuje platformu.

Slijed poziva narudžbi pomoću webhooka

Prvo morate uključiti webhook i umetnuti URL koji ste pripremili u odgovarajuću karticu na partnerskom portalu u izborniku Partner. Zatim možete vidjeti pojedinačne odlazne obavijesti u zapisniku.

1. Primit ćete obavijest od webhooka s promijenjenim brojem narudžbe.

2. Za narudžbe u statusu BLOKIRANA nazovite "Dohvati detalje narudžbe" kako biste rezervirali robu. To su narudžbe za koje ste primili prvu obavijest. Primajte samo informacije o robi. Primajte financijske informacije samo za narudžbe u statusu OTVORENO . Rezervacija robe nije obavezna, ali se toplo preporučuje za robu s visokom prodajom i povezanim rizikom od nestašice zaliha.

3. Primit ćete webhook obavijest za narudžbu koja je promijenila status u OTVORENO ili OTKAZANO .

4. Pozovite Ažuriraj nalog s potvrđeno = true za OTVORENE ili OTKAZANE naloge koji su se promijenili prema informacijama iz webhooka. Moguće je promijeniti status iz BLOKIRAN u OTVOREN ili OTKAZAN (ovo je konačni status i više nije moguće ponovno otvoriti nalog).

5. Nazovite Preuzmi detalje narudžbe za narudžbe iz koraka 4. , za OTKAZANE narudžbe otkažite rezervaciju. Za OTVORENE narudžbe koristite poziv za potvrđene narudžbe kako biste uvezli konačne podatke u svoj sustav. U ovom trenutku više nije moguće intervenirati u narudžbu ni s jedne strane, sve informacije poput adrese i iznosa plaćanja pouzećem su u ovom trenutku konačne.

6. Pozovite Ažuriraj narudžbu iz OTVORENO u DOSTAVA za sve narudžbe za koje ste započeli postupak dostave. Ako ste utvrdili da se narudžba neće moći poslati, u ovom trenutku možete promijeniti narudžbu u OTKAZANO .

7a. Prilikom korištenja MALL dostave, pozovite Generiraj naljepnice za odabrane MDP narudžbe za ispis naljepnica za narudžbe MALL dostave.

7b. Ako ne koristite MALL Delivery, morate ispuniti uvjete dostave koje je odredio vaš prijevoznik.

8. Predaja pošiljke brodarskoj tvrtki.

9a. Prilikom korištenja MALL Delivery, pozovite Ažuriraj narudžbu kako biste promijenili status narudžbe iz OTPREMA u OTPREMLJENO (promjena statusa u OTPREMLJENO uvijek se mora dogoditi nakon što je pošiljka predana dostavnoj tvrtki).

9b. Ako ne koristite MALL Delivery, pozovite Update order sa SHIPPING na SHIPPED , uključujući URL za praćenje i broj pošiljke prijevoznika. Sve informacije moraju se poslati u jednom pozivu kako bi se zadovoljili kriteriji Quality of Service - Tracking rate.

Neobavezno : Prilikom korištenja MALL Delivery, možete pozvati GET detalje narudžbe za narudžbe u statusu ISPORUČENO/VRACENO/IZGUBLJENO na temelju webhook obavijesti o promjeni narudžbe, kako biste ažurirali konačni status narudžbe u svom sustavu.

10. Ako ne koristite DOSTAVU U TRGOVAČKI CENTAR, pozovite Ažuriraj narudžbu iz OTPREMLJENO u DOSTAVLJENO s točnim datumom dostave na temelju informacija od vašeg prijevoznika. Ako imate informacije o prvom pokušaju dostave od prijevoznika, možete ih dodati i njih, te informacije nisu obavezne. Ažuriranje se mora poslati u jednom pozivu . Ako narudžba nije uspjela biti dostavljena i vraćena je pošiljatelju, promijenite status narudžbe iz OTPREMLJENO u VRACENO .

SLA i korisničko iskustvo: Za oba oblika povezivanja narudžbi, poželjno je za kupca, a ujedno je i konačni SLA, da se slanje statusa narudžbe temelji na istini i da je što ažurnije. Nepravilna implementacija slanja statusa može dovesti do negativnog korisničkog iskustva i otkazivanja narudžbi.

Slijed poziva narudžbi bez korištenja webhooka

1. Nazovite Primajte popis nepotvrđenih narudžbi u redovitim intervalima, preporučujemo prilagodbu učestalosti prosječnom broju narudžbi. Prekoračite učestalost samo jednom na sat ako imate više od 100 narudžbi dnevno. Koristite filter=basic prilikom poziva.

2. Na temelju Popisa nepotvrđenih narudžbi, pozovite Preuzmi detalje narudžbe za narudžbe u statusu BLOKIRANA kako biste rezervirali robu. Primajte samo informacije o robi. Primajte financijske informacije samo za narudžbe u statusu OTVORENO . Rezervacija robe nije obavezna, ali se toplo preporučuje za robu s velikim obujmom prodaje i povezanim rizikom od nestašice zaliha.

3. Pozovite Ažuriranje naloga s potvrđeno = true za OTVORENE / OTKAZANE naloge koje je vaš sustav registrirao u pozivu.

4. Pozovite opciju "Dohvati detalje narudžbe" za potvrđenu narudžbu OTVORENO kako biste uvezli konačne podatke u svoj sustav. U ovom trenutku ne mogu se poduzeti daljnje radnje na narudžbi, tako da su svi podaci poput adrese i iznosa plaćanja pouzećem u ovom trenutku konačni.

5. Pozovite Ažuriraj narudžbu iz OTVORENO u DOSTAVA za sve narudžbe za koje ste započeli proces dostave. Ako ste utvrdili da se narudžba neće moći poslati, u ovom trenutku možete promijeniti narudžbu u OTKAZANO .

6a. Prilikom korištenja MALL dostave, pozovite Generiraj naljepnice za odabrane MDP narudžbe za ispis naljepnica za narudžbe MALL dostave.

6b. Ako ne koristite MALL Delivery, morate ispuniti uvjete dostave koje je odredio vaš prijevoznik.

Preporuka: Prije slanja narudžbe preporučujemo provjeru statusa narudžbe. U statusu DOSTAVA , kupac može otkazati narudžbu. Takvu će narudžbu sustav promijeniti u status OTKAZANO . Ova će se promjena pojaviti i na popisu nepotvrđenih narudžbi Preuzmi i mora se potvrditi u koraku 3.

7. Predaja pošiljke brodarskoj tvrtki.

8a. Prilikom korištenja MALL Delivery, pozovite Ažuriraj narudžbu kako biste promijenili status narudžbe iz OTPREMA u OTPREMLJENO (promjena statusa u OTPREMLJENO uvijek se mora dogoditi nakon što je pošiljka predana dostavnoj tvrtki).

8b. Ako ne koristite MALL Delivery, pozovite Update order from SHIPPING to SHIPPED , uključujući URL za praćenje i broj pošiljke prijevoznika. Sve informacije moraju biti poslane unutar jednog poziva kako bi se zadovoljili kriteriji Quality of Service - Tracking rate.

Neobavezno: Kada koristite dostavu u MALL, možete koristiti poziv Dohvati popis narudžbi prema statusu pomoću vremenskog filtera za narudžbe ISPORUČENO/VRACENO/IZGUBLJENO kako biste u svoj sustav učitali konačni status narudžbe.

9. Ako ne koristite dostavu putem MALL-a, pozovite Ažuriraj narudžbu iz OTPREMLJENO u ISPORUČENO s točnim datumom dostave na temelju informacija od vašeg prijevoznika. Ako imate informacije o prvom pokušaju dostave od prijevoznika, možete ih dodati i njih, te informacije nisu obavezne. Ažuriranje se mora poslati u jednom pozivu . Ako narudžba nije uspjela biti dostavljena i vraćena je pošiljatelju, promijenite status narudžbe iz OTPREMLJENO u VRACENO .

Validacija podataka: Ako postoji slučaj u kojem trebate dohvatiti podatke o narudžbi, uvijek pozovite pojedinačne narudžbe čiji su vam podaci potrebni. Ako i dalje trebate pozvati popis narudžbi, koristite filtere vremenskih razdoblja i izbjegavajte pozivanje cijele povijesti narudžbi odjednom. Za potrebe naplate i poravnanja prilikom korištenja usluge samonaplate MALL koristite odgovarajuće krajnje točke .

Natrag na vrh

Proizvodi

Za proizvode se morate usredotočiti na dvije vrste poziva: stvaranje proizvoda i njihovo ažuriranje.

Izrada proizvoda i varijanti

Prilikom kreiranja proizvoda, molimo vas da uvijek obratite pozornost na naše uvjete sadržaja proizvoda, detalje možete pronaći ovdje . Nadalje, pažljivo proučite uvjete za prikazivanje proizvoda u pojedinim kategorijama u članku ovdje kako biste spriječili potrebu za naknadnim ispravcima proizvoda putem dodatnih poziva.

Važno: Ako vaši proizvodi imaju varijante, uvijek kreirajte varijante proizvoda na temelju parametara dostupnih u danoj kategoriji. Slanje varijanti proizvoda kao pojedinačnih zapisa nije poželjno i može dovesti do preuzimanja ponude s web stranice.

Izradite proizvode bez varijanti pomoću poziva Izradi novi proizvod . Ako naiđete na pogrešku s ovim pozivom, pripremili smo članak koji objašnjava pojedinačne pogreške i moguće načine za njihovo sprječavanje i ispravljanje. Članak možete pronaći pod poveznicom ovdje . Struktura poziva je obavezna osim za elemente gdje je to izričito navedeno u dokumentaciji. Proizvod kreiran na ovaj način zatim se može pronaći na popisu proizvoda na portalu, a također i na web stranici u popisu proizvoda. Za pregled možete koristiti sandbox račun .

Za varijante proizvoda, prvo upotrijebite metodu Stvori novi proizvod za stvaranje glavnog proizvoda. Zatim dodajte varijante ovom proizvodu pomoću metode Stvori novu varijantu . Varijante je potrebno razlikovati pomoću parametara varijante. Mogu se koristiti do dva parametra dostupna u danoj kategoriji. Varijante dodijeljene glavnom proizvodu tada se uvijek prikazuju u detaljima proizvoda s odgovarajućim parametrom kao opcionalnom varijablom od strane kupca.

Za proizvode , u polje prioritet upišite vrijednost 1. Sustav automatski rangira proizvode pomoću algoritma koji radi na principu broja klikova, prometa i prodaje zadanog proizvoda.
Ovo je zastarjeli element koji još treba popuniti, ali se uopće ne uzima u obzir. Trenutno radimo na njegovom uklanjanju.

Važno je uključiti EAN (GTIN) za proizvode, on ima precizno definiran format - 13 numeričkih znakova. EAN ima temeljni utjecaj na podudaranje proizvoda na Google Adsu, Heureki i Zboží.czu, a time i mogućnost dosezanja daleko većeg broja kupaca sa svojim proizvodima.
Ako vaš EAN ima 14 numeričkih znakova, unesite ga kao 13 znamenki bez vodeće nule. Ako imate kraći 8-znamenkasti EAN, dodajte onoliko nula na početak koliko nedostaje unutar 13 znakova (5) .

Ažuriranja proizvoda

Za proizvode, ažuriranja dijelimo na nekoliko vrsta.

Ažuriranje podataka o proizvodu (opisi, slike, parametri itd.)
Ažuriranje cijene
Ažuriranje dostupnosti

Važno: Molimo vas da šaljete ažuriranja proizvoda samo ako postoje bilo kakve promjene. Ponavljano slanje istih informacija je krajnje nepoželjno i opterećuje platformu.

Ažuriranja podataka o proizvodu

Prilikom ažuriranja podataka o proizvodu koristite odgovarajuću metodu UPDATE za proizvod koji nije varijanta ili varijanta . Promijenite podatke samo ako su se promijenili ili ih je potrebno dopuniti. Prilikom ažuriranja proizvoda uvijek je potrebno poslati sve elemente, a ne samo one koji su se promijenili.

Ažuriranje cijene

Za ažuriranje cijene nemojte koristiti gore opisanu metodu za ažuriranje proizvoda ili varijante . Za promjenu cijene dostupan je zaseban poziv putem kojeg šaljete promjenu, i za proizvod koji nije varijanta i za varijante . Prilikom ažuriranja cijene za više od 30%, promjena cijene mora se potvrditi putem prisilnog tokena. Više informacija o ovoj funkciji možete pronaći u našoj dokumentacijiovdje .

Ažuriranje dostupnosti

Za ažuriranje dostupnosti nemojte koristiti gore opisanu metodu ažuriranja proizvoda ili varijante. Za promjenu dostupnosti koristite metodu Grupno ažuriranje dostupnosti proizvoda/varijante . Molimo koristite ovu opciju ažuriranja što je više moguće jer je pomoću grupnog ažuriranja moguće ažurirati do 1000 proizvoda/varijanti odjednom.

Alternativno, ako su potrebne promjene u jedinicama komada, moguće je koristiti metodu za ažuriranje dostupnosti zaliha proizvoda ili varijante .

Validacija podataka: Ako postoji slučaj u kojem trebate dohvatiti podatke o proizvodu, pozovite ih samo kada je to potrebno i putem odgovarajuće krajnje točke za cijenu ili dostupnost. Bilo kakvi redoviti skupni ili pojedinačni pozivi o podacima o proizvodu vrlo su nepoželjni i opterećuju naš sustav te mogu dovesti do ograničenja vaše veze s MALL-om.

Natrag na vrh

Krajnje točke serije

Unutar API MALL-a moguće je izvršiti neke radnje skupno. Korištenjem batch krajnjih točaka značajno ćete smanjiti korištenje limita API poziva unutar limitera brzine, stoga se preporučuje njihovo korištenje u najvećoj mogućoj mjeri.

Dostupne krajnje točke serije su:

Ažuriranje dostupnosti u skupnim količinama – Kao što je gore opisano za ažuriranje dostupnosti, ovo je skupno ažuriranje dostupnosti proizvoda i varijanti. Ova metoda omogućuje ažuriranje do 1000 promjena u jednom pozivu.
Aktivni odabrani proizvodi – Masovna promjena odabranih proizvoda iz nacrta u aktivno stanje.
Aktiviraj proizvode – Masovna promjena svih proizvoda iz nacrta u aktivno stanje.

Deaktiviranje i brisanje proizvoda

Postoji nekoliko metoda koje možete koristiti za preuzimanje proizvoda s web stranice, ovisno o razlogu preuzimanja proizvoda.

Privremena prodaja proizvoda koji će biti ponovno dostupan - u ovom slučaju, kao dio ažuriranja dostupnosti proizvoda, jednostavno smanjite dostupnost zaliha proizvoda na "0", tada ga neće biti moguće kupiti na web stranici, ali će kupci i dalje neko vrijeme moći vidjeti hoće li se proizvod ponovno pojaviti u ponudi.
Privremena potreba za uklanjanjem proizvoda s web stranice - ponovno, ažuriranjem dostupnosti proizvoda moguće je koristiti polje statusa, gdje postavljanje vrijednosti "N" čini proizvod ili varijantu "neaktivnim".
Brisanje proizvoda – ako znate da određeni proizvod ili varijanta neće biti na zalihi dulje od 2 mjeseca, preporučujemo brisanje proizvoda ili varijante putem odgovarajuće krajnje točke. MALL čuva povijesne podatke o prodaji za vaše proizvode, ako zatim prenesete proizvod pod istim ID-om, podaci o prodaji će se ponovno uskladiti.

Važno: Nemojte ažurirati nijedan proizvod koji je neaktivan. Ponavljano slanje ažuriranja za neaktivne proizvode je krajnje nepoželjno i opterećuje platformu. Prekoračenje ograničenja može uzrokovati preopterećenje sustava, što rezultira samo djelomičnim prihvaćanjem podataka, što može rezultirati i negativnim iskustvom korisnika i potencijalnim gubitkom za partnera.

Natrag na vrh

Kategorija

Unutar našeg API-ja možete koristiti dvije osnovne krajnje točke za dohvaćanje podataka o kategorijama. U prvoj , Stablo kategorija po državi, dobit ćete stablo kategorija dostupno za određenu državu. Promjenom koda države u URL-u poziva, možete dohvatiti informacije o stablima kategorija za druge države koristeći isti API ključ.

Rezultat API poziva uvijek je nekoliko podataka koji su bitni za vašu integraciju.

ID stavke izbornika (=“IdStavkeIzbornika”) – jedinstveni kod kategorije koji možete koristiti za pozivanje Detalji kategorije Za dobivanje popisa svih parametara i vrijednosti, poziv je opisan u nastavku.
ID vrste proizvoda (=“IdVrsteProizvoda”) – tehnički kod kategorije potreban za klasifikaciju proizvoda, ovaj kod može se podudarati s više ID-ova stavki izbornika.
Izbornik ograničenja (=“ograničenja izbornika”) – obavezni parametri s vrijednostima potrebnim za uključivanje proizvoda u određeni menuitemID, za detalje o uvjetima kategorije pročitajte detaljan članak ovdje.

Validacija prikaza na web stranici: Proizvod koji ste prenijeli u sustav, a koji ne zadovoljava ograničenja izbornika, može pokazati grešku prilikom prikaza i neće biti dostupan za kupnju kupcima.

Putem API poziva Category detail dobit ćete popis podataka. Prvi dio sadrži uvjete prikaza u zadanoj kategoriji.

SAP ID (=“sapId”) – šifra tehničke kategorije, ovo je ista šifra koja je navedena u prethodnom pozivu kao ID vrste proizvoda, ovo je tehnički kod kategorije potreban za klasifikaciju proizvoda.
Uvjeti kategorije (=“uvjetiKategorije”) – ovdje ćete pronaći iste informacije kao u Izbornik ograničenja u prethodnom pozivu. Za klasificiranje proizvoda u bilo koju kategoriju, ovi uvjeti moraju uvijek biti ispravno uneseni.

Validacija prikaza na web stranici: Proizvod koji ste prenijeli u sustav, a koji ne ispunjava Uvjete kategorije, može pokazati grešku prilikom prikaza i neće biti dostupan za kupnju kupcima.

Ostali parametri (=“ostaliParametri”)Ovdje ćete pronaći sve ostale parametre s vrijednostima koje možete koristiti i dodati svojim proizvodima. Za parametre uvijek morate koristiti popis vrijednosti koje možete pronaći ovdje, unos vlastitih vrijednosti u parametre nije moguć. Uvijek dodajte naziv parametra proizvodu u polje za tehničke nazive. "vrijednost"Uvijek unosite vrijednosti u nazivu ciljane zemlje prodaje, tj. vrijednosti iz polja "tekst"Za numeričke vrijednosti uvijek koristite jedinicu navedenu u polju. "jedinica"Ako parametar ne sadrži vrijednosti koje su vam potrebne, pošaljite nam zahtjev putem FAQ, Centra za pomoč.

Natrag na vrh

Robne marke

Pomoću poziva " Dohvati sve marke" dobit ćete potpuni popis dostupnih marki u svim zemljama. Popis nije jedinstven za svaku zemlju, tako da ga možete koristiti za povezivanje s bilo kojim od tržišta MALL partnera. Uvijek dodajte podatke iz polja "brand_id" proizvodima u podudarnosti 100%, uključujući velika slova.

Za dodavanje robne marke upotrijebite odgovarajuću karticu na partnerskom portalu prema uputama ovdje .

Oznake

Korištenjem poziva " Dohvati sve oznake " uvijek ćete dobiti potpuni popis oznaka u našoj bazi podataka. Oznake se koriste za marketinške kampanje i druge interne procese. Moguće je koristiti ove oznake bez prethodnog odobrenja vašeg prodajnog predstavnika u MALL-u.