V následujícím článku si podrobně ukážeme doporučený způsob, jak napojit jednotlivé toky dat v rámci API napojení Vaší společnosti.
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.
Berte prosím v potaz, že API MALL má povahu zdroje informací v moment jejich potřeby, nejedná se o databázi, která by sloužila k uchovávání historizovaných dat. API volání této povahy mohou být omezena.
Pro autorizaci všech API volání v rámci napojení na MALL využíváte client ID, neboli „API klíč“. API klíč má kombinaci znaků, které jsou unikátní pro každý účet a je potřeba jej přiložit ke každému jednotlivému API volání. Pokud máte na MALL více účtů, pro každý účet bude klíč unikátní. API klíč naleznete v MALL Partner portálu v sekci „Firemní profil“ na kartě „Informace“.
Sadržaj
- Narudžbe
- Proizvodi
- Kategorija
- 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 .
Berte prosím zároveň v potaz, že pokud využíváte služeb MALL Delivery, proces se v rámci vychystávání zásilky a aktualizace stavů v pozdějších krocích odlišuje.
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.
Posloupnost objednávkových volání s využitím webhooku
Nejprve je třeba zapnout webhook a vložit vámi připravenou URL do příslušné záložky v partnerském portálu v nabídce Partner, v logu pak vidíte jednotlivé odchozí notifikace.
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.
Posloupnost objednávkových volání bez využití webhooku
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 .
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.
Krajnje točke serije
V rámci API MALL je možné některé akce provádět hromadnými změnami. Využitím batch endpointů výrazně snížíte využívání vašeho limitu API volání v rámci rate limiteru a tak je doporučeno využívat tyto v maximální možné míře.
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
Pro stažení produktu z webu je možné využít několik metod, které závisí na důvodu potřeby stažení produktu.
- 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.
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 (=“menuItemId“) – unikátní kód kategorie jehož použitím můžete voláním Detalji kategorije Za dobivanje popisa svih parametara i vrijednosti, poziv je opisan u nastavku.
- ID vrste proizvoda (=“productTypeId“) – technický kód kategorie potřebný pro zařazení produktu, tento kód se může shodovat napříč více menuitemID.
- Izbornik ograničenja (=“menuCosntraints“) – povinné parametry s hodnotami potřebné k zařazení produktů do dané menuitemID, pro detail o podmínkách kategoriích prosím pročtěte detailní článek 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“) – technický kód kategorie, jedná se o tentýž kód, který byl v předchozím volání uveden jako ID vrste proizvoda, ovo je tehnički kod kategorije potreban za klasifikaciju proizvoda.
- Uvjeti kategorije (=“categoryConditions“) – zde najdete tytéž údaje jako v Izbornik ograničenja v předchozím volání. Pro zařazení produktu do jakékoliv kategorie je vždy třeba tyto podmínky bezchybně zadat.
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 (=“otherParameters“): Zde najdete všechny další parametry s hodnotami, které je možné využít a přidat k vašim produktům. U parametrů je vždy třeba využívat seznamu hodnot, který zde naleznete, zadávání vlastních hodnot do parametrů není možné. Název parametrů vždy přidávejte k produktu v technických názvech, pole "vrijednost". Hodnoty vždy uvádějte v názvu cílové země prodeje, tj. hodnoty z pole "tekst". V případě numerických hodnot vždy vycházejte z jednotky uvedené v poli "jedinica". Pokud daný parametr neobsahuje hodnoty, které potřebujete, zašlete nám žádost skrze FAQ, Centra za pomoč.
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.
- FDEL – besplatna dostava
- RASPRODAJA – rasprodaja
- NOVO – novo