V spodnjem članku bomo podrobno prikazali priporočeni način povezovanja posameznih podatkovnih virov v okviru povezave API vašega podjetja.

Testno okolje: Obstaja samo eno okolje za testiranje in pravo prodajo - produkcijsko okolje. Ključ API, ki ga dobite po registraciji, je zato nespremenljiv in dokončen. Kljub temu lahko povezavo najprej preizkusite. Vaš račun je v testnem načinu le, dokler ga ne aktivirate. Vendar bo vaša ponudba na spletnem mestu dokončno prikazana šele, ko jo bo odobril oddelek za vkrcavanje, zato se za več informacij obrnite na strokovnjaka za vkrcavanje.

Zelo pomembno je upoštevati naslednja priporočila. Posledice neupoštevanja priporočenih praks so lahko omejujoče za delovanje klicev API vašega podjetja, saj obremenjujejo sistem MALL. Glede na to platforma deluje "MALL rate limiter". Več o tem si lahko preberite v članku tukaj. Za morebitne prekoračitve SLA zaradi nepravilne izvedbe API-ja in prekoračitve API omejitev odgovarja partner.

Upoštevajte, da je API MALL vir trenutnih informacij in ni baza podatkov, ki bi se uporabljala za shranjevanje zgodovinskih podatkov. Tovrstni API klici so lahko omejeni.


Vsebina


Orders

Pri končnih točkah (endpoints) za naročila je potrebno posebno pozornost nameniti zaporedju korakov. Ta je razdeljena na dve osnovni možnosti, odvisno od tega, ali uporabljate spletni kavelj (webhook) za pridobivanje informacij o spremembah naročil. Več o spletnih kavljih si lahko preberete tukaj.

V tem članku boste izvedeli, kako pravilno vezati vsako metodo in preklopiti vsako stanje v API, priporočamo pa tudi, da si preberete članek, v katerem so podrobno pojasnjena posamezna stanja, ki jih lahko zavzame naročilo in kaj pomenijo od tu.

Upoštevajte tudi, da če uporabljate storitve dostave MALL, se postopek razlikuje pri korakih predaje pošiljke in posodobitvi stanja.

Pomembno: Posodobitve stanja naročil pošiljajte samo kadar pride do dejanske spremembe stanja naročil. Večkratno pošiljanje istih informacij je za platformo zelo nezaželeno in obremenjujoče.


Zaporedje klicev naročil preko spletnega kavlja

Najprej morate vklopiti spletno kljuko in v ustrezen zavihek partnerskega portala v meniju Partner vstaviti naslov URL, ki ste ga pripravili, nato pa lahko v dnevniku vidite posamezna izhodna obvestila.

1. Preko spletnega kavlja prejmete obvestilo s številko naročila, ki je bilo spremenjeno.

2. Uporabite API klic Get order detail za blokirana (BLOCKED) za rezervacijo blaga. To so naročila, za katera ste prejeli prvo obvestilo. Prejmite le informacije o blagu. Prejemanje finančnih informacij samo za naročila v statusu OPEN. Rezervacija blaga ni obvezna, vendar je zelo priporočljiva za blago z visoko prodajnostjo in z njo povezanim tveganjem za razprodajo.

3. Obvestilo spletnega kavlja prejmete za naročila, katererih stanje se je spremenilo v odprto OPEN ali CANCELED.

4. Uporabite API klic Update order z vrednostjo confirmed = true za odprta ali preklicana naročila OPEN ali CANCELED naročila, ki so bila spremenjena glede na informacije iz spletne kljuke. Možna sprememba statusa iz (BLOCKED) do OPEN ali CANCELED (to je končno stanje in naročila ni več mogoče ponovno odpreti).

5. Uporabite API klic Get order detail za naročila iz koraka številka 4., za preklicana CANCELED naročila, da prekličite rezervacije izdelkov. Za odprta OPEN naročila, uporabite klic na potrjena naročila za uvoz končnih podatkov v svoj sistem. Na tej točki ni več mogoče posredovati z nobene strani naročila, zato so vsi podatki, kot so naslov in znesek nakupa, na tej točki dokončni.

6. Uporabite API klic Update order za spremembo naročil z odprtim stanjem OPEN do SHIPPING za vsa naročila, za katera ste začeli postopek pošiljanja. Če ugotovite, da naročila ni mogoče poslati, lahko prekličete naročilo s spremembo stanja naročila v CANCELED.

7a. Če uporabljate MALL Delivery, uporabite API klic Generate labels for selected MDP orders za tiskanje nalepk za naročila MALL Delivery.

7b. Če ne uporabljate storitve MALL Delivery, morate izpolnjevati zahteve za pošiljanje, ki jih določi vaš prevoznik.

8. Predaja pošiljke dostavni službi.

9a. Če uporabljate MALL Delivery, uporabite API klic Update order za spremembo stanja naročila iz odprema SHIPPING v SHIPPED za uvoz končnih podatkov v vaš sistem (sprememba v stanje SHIPPED nastopi šele po predaji pošiljke dostavni službi).

9b. Če ne uporabljate storitve MALL Delivery, uporabite API klic Update order za spremembo stanja naročila iz odprema SHIPPING v SHIPPED, vključno z URL-jem za sledenje in številko pošiljke dostavne službe. Vse informacije je potrebno poslati v enem klicu,da izpolnjujejo merila kakovosti storitve - stopnja sledenja.

Neobvezno: Če uporabljate storitev MALL Delivery, lahko uporabite klic GET order detail na podlagi obvestila spletnega kavlja o spremembi stanja naročila v DOSTAVLJENO / VRNJENO / IZGUBLJENOza dokončno potrditev končnega stanja naročil v vašem sistemu.

10. Če ne uporabljate možosti MALL DELIVERY, uporabite klic Update order za naročila, katerih stanje se je spremenilo iz odpreme SHIPPED v DELIVERED s točnim datumom dostave na podlagi informacij vašega prevoznika. Če imate od prevoznika podatke o prvem poskusu dostave, lahko dodate tudi te, vendar ti podatki niso obvezni. Posodobitev je potrebno poslati v enem klicu. Če naročila ni bilo mogoče dostaviti in je bilo vrnjeno pošiljatelju, spremenite stanje naročila iz poslano SHIPPED v RETURNED.


SLA in izkušnje strank: Pri obeh oblikah povezovanja naročil je pomembno, da nastaviteve stanj naročil temeljo na dejanskem stanju in so čim bolj ažurne. To je pomembno za zadovoljstvo stranke in hkrati za izpolnjevanje pogojev SLA. Nepravilne nastavitve stanj naročil lahko privedejo do negativne izkušnje strank in preklica naročil.


Zaporedje klicev naročil brez uporabe spletnega kavlja

1. Pokličite Za seznam nepotrjenih naročil z redno frekvenco, priporočamo, da frekvenco prilagodite povprečnemu številu naročil. Pogostost 1x na uro lahko prekoračite le, če je več kot 100 naročil na dan. Pri klicu uporabite filter=basic.

2. Glede na List of unconfirmed orders uporabite API klic Get order detail za blokirana (BLOCKED) naročila za rezervacijo blaga. Prevzemite samo podatke o blagu. Finančne podatke pridobite samo za odprta naročila OPEN. Rezervacija blaga ni obvezna, vendar je zelo priporočljiva za blago z visoko prodajnostjo in z njo povezanim tveganjem za razprodajo.

3. Uporabite API klic Update order z vrednostjo confirmed = true za odprta ali preklicana naročila OPEN/CANCELED naročila, ki jih je vaš sistem registriral v klicu.

4. Uporabite API klic Get order detail v OPEN potrjena naročila za uvoz končnih podatkov v vaš sistem. Na tej točki v naročilo ni več mogoče posegati z nobene strani, vsi podatki, kot so naslov in znesek po povzetju, so v tem trenutku dokončni.

5. Uporabite API klic Update order za spremembo naročil z odprtim stanjem OPEN do SHIPPING za vsa naročila, za katera ste začeli postopek pošiljanja. Če ugotovite, da naročila ni mogoče poslati, lahko prekličete naročilo s spremembo stanja naročila v CANCELED.

6a. Če uporabljate MALL Delivery, uporabite API klic Generate labels for selected MDP orders za tiskanje nalepk za naročila MALL Delivery.

6b. Če ne uporabljate storitve MALL Delivery, morate izpolnjevati zahteve za pošiljanje, ki jih določi vaš prevoznik.

Priporočilo: Pred pošiljanjem naročila priporočamo, da preverite stanje naročila. V stanju odprema (SHIPPING) lahko kupec naročilo prekliče. Takšnemu naročilu bo sistem dodelil stanje CANCELLED. Ta sprememba bo prikazana tudi na seznamu List of unconfirmed orders in jo je potrebno potrditi v 3. koraku.

7. Predaja pošiljke dostavni službi.

8a. Če uporabljate MALL Delivery, uporabite API klic Update order za spremembo stanja naročila iz odprema SHIPPING v SHIPPED za uvoz končnih podatkov v vaš sistem (sprememba v stanje SHIPPED nastopi šele po predaji pošiljke dostavni službi).

8b. Če ne uporabljate storitve MALL Delivery, uporabite API klic Update order za spremembo stanja naročila iz odprema SHIPPING v SHIPPED, vključno z URL-jem za sledenje in številko pošiljke dostavne službe. Vse informacije je potrebno poslati v enem klicu, za izpolnjevanje meril kakovosti storitve - stopnja sledenja.

Neobvezno: Če uporabljate storitev MALL Delivery, lahko uporabite API klic Pridobite seznam naročil po stanju z uporabo časovnega filtra za naročila s statusom DOSTAVLJENO / VRNJENO / IZGUBLJENO naročil, da bi dokončno potrdili končno stanje naročil v vašem sistemu.

9. Če ne uporabljate storitve MALL Delivery, uporabite API klic Update order za naročila, katerih stanje se je spremenilo iz odpreme SHIPPED v DELIVERED s točnim datumom dostave na podlagi informacij vašega prevoznika. Če imate od prevoznika podatke o prvem poskusu dostave, lahko dodate tudi te, vendar ti podatki niso obvezni. Posodobitev je potrebno poslati v enem klicu. Če naročila ni bilo mogoče dostaviti in je bilo vrnjeno pošiljatelju, spremenite stanje naročila iz poslano SHIPPED v RETURNED.

Povratno preverjanje podatkov: Če potrebujete podatke o naročilu, vedno kličite le posamezna naročila, katerih podatke potrebujete. Če kljub vsemu potrebujete seznam naročil, uporabite filtre za časovno obdobje in se tako izognete takojšnjemu priklicu celotne zgodovine naročil. Za namene obračunavanja in izdajanja računov pri uporabi storitve MALL Self-Billing uporabite ustrezne končne točke.

Nazaj na vrh


Izdelki

Pri izdelkih se morate osredotočiti na dve vrsti klicev, ustvarjanje izdelkov in njihovo posodabljanje.

Ustvarjanje izdelkov in variant

Pri ustvarjanju izdelkov bodite vedno pozorni na naše pogoje izgleda izdelkov, podrobnosti lahko najdete tukaj. Nato natančno preučite pogoje prikaza izdelka v posameznih kategorijah v članku tukaj in s tem preprečite potrebo po naknadnih popravkih izdelkov in se s tem izognete nepotrebnim API klicem.

Pomembno: Če imajo vaši izdelki različice, vedno ustvarite različice izdelkov na podlagi parametrov, ki so na voljo v kategoriji. Posredovanje variantnih izdelkov kot posameznih seznamov je nezaželeno in lahko povzroči, da bo ponudba odstranjena s spletnega mesta.

Izdelke brez različic ustvarite z API klicem Ustvari nov izdelekČe pri tem klicu pride do napake, smo pripravili članek, v katerem so pojasnjene posamezne napake ter kako jih preprečiti in odpraviti. Članek je na voljo na povezavi tukaj. Struktura klica je obvezna, razen za elemente, za katere je to izrecno navedeno v dokumentaciji. Tako ustvarjen izdelek lahko nato najdete na seznamu izdelkov na portalu in tudi na spletu v seznamu izdelkov, pri čemer lahko uporabite vaš račun sandbox.

Pri izdelkih z različicami najprej uporabite metodo Create new product da ustvarite glavni izdelek. Nato uporabite metodo Create new variant za dodajanje različic. Variante je treba razlikovati z uporabo parametrov variante. Uporabite lahko največ dva od parametrov, ki so na voljo v določeni kategoriji. Variante, dodeljene glavnemu izdelku, so nato vedno prikazane v podrobnostih izdelka z ustreznim parametrom kot neobvezno spremenljivko, ki jo določi stranka.

Za izdelke izpolnite prednostno nalogo z 1. Sistem samodejno razvršča izdelke s pomočjo algoritma, ki deluje na podlagi števila klikov, prometa in prodaje določenega izdelka. 
To je zastarel element, ki ga je še vedno treba izpolniti, vendar se sploh ne upošteva. Trenutno se trudimo, da bi jo odstranili.

Pri izdelkih je pomembno navesti EAN (GTIN)ima natančno določeno obliko - 13 številčnih znakov. EAN pomembno vpliva na ujemanje izdelkov v Google Ads, Heureki in Zboží.cz ter s tem na možnost, da s svojimi izdelki dosežete veliko več kupcev.
Če ima vaš EAN 14 številčnih znakov, ga vnesite kot 13 številk brez 0 na začetku. Če imate krajši osemmestni EAN, na začetek dodajte toliko 0, kolikor manjka 13 znakov (5)..

Posodobitve izdelkov

Posodobitve izdelkov delimo na več vrst.

  • Posodobitev podatkov o izdelku (nalepke, slike, parametri, ..)
  • Posodobitev cene
  • Posodobitev razpoložljivosti

Pomembno: Vse posodobitve izdelkov pošiljajte samo v primeru sprememb. Večkratno pošiljanje istih informacij je za platformo zelo nezaželeno in obremenjujoče.

Posodobitev podatkov o izdelku

Pri posodabljanju podatkov o izdelku uporabite ustrezno metodo UPDATE za izdelek brez različic ali različice. Podatke posodobite samo v primeru sprememb ali po dodajanju novih informacij. Vsakič, ko posodobite izdelek, morate vedno poslati vse elemente, ne le tistih, ki ste jih spremenili.

Posodobitev cene

Če želite posodobiti ceno, ne uporabljajte zgoraj opisane metode za posodobitev izdelka ali različice. Za spremembo cene je na voljo ločen klic, prek katerega lahko pošljete spremembo za izdelek brez različic, ali za različice. Pri posodabljanju cene za več kot 30% je treba spremembo cene potrditi s pomočjo t.i. force tokena. Za več informacij o tej funkciji si oglejte našo dokumentacijo tukaj.

Posodobitev razpoložljivosti

Za posodobitev razpoložljivosti ne uporabljajte zgoraj opisane metode za posodobitev izdelka ali različice. Če želite spremeniti razpoložljivost, uporabite način množične spremembe razpoložljivosti izdelkov prek Batch update of product/variant availability. Prosimo, da uporabite to možnost posodobitve, kolikor je le mogoče, saj je z njo mogoče posodobiti do 1000 izdelkov / različic hkrati.

Če so potrebne spremembe enot, je mogoče uporabiti metodo za posodabljanje razpoložljivosti zalog izdelka ali različice.

Povratno preverjanje podatkov: Če morate podatke o izdelku dobiti nazaj, jih pokličite le po potrebi in prek ustrezne končne točke za ceno ali razpoložljivost. Vsako občasno množično ali posamično klicanje po podatkih o izdelkih je zelo nezaželeno in obremenjujoče za naš sistem ter lahko povzroči omejitev vaše povezave z MALL.

Nazaj na vrh

Množične končne točke (batch endpoints)

V vmesniku MALL API je mogoče nekatera dejanja izvesti z množičnimi spremembami. Uporaba paketnih končnih točk bo znatno zmanjšala porabo omejitve klicev API znotraj omejevalnika hitrosti, zato je priporočljivo, da jih uporabljate čim pogosteje.

Razpoložljive množične končne točke so:

  • Batch availability update - Kot je opisano zgoraj pri posodobitvi razpoložljivosti, gre za množično posodobitev razpoložljivosti izdelka in različic. S to metodo lahko v enem klicu posodobite do 1000 sprememb.
  • Active selected products - Množična sprememba izbranih izdelkov iz stanja draft v stanje live.
  • Activate products - Množično spremenite vse izdelke iz stanja draft v stanje live.

Deaktivacija in brisanje izdelkov

Za odstranitev izdelka iz spleta lahko uporabite več načinov, odvisno od razloga, zaradi katerega želite izdelek skriti.

  • Začasna razprodaja izdelka, ki bo kmalu ponovno na zalogi - v tem primeru je dovolj, da v okviru posodobitve razpoložljivosti izdelka nastavite razpoložljivost izdelka na zalogi na "0". Izdelka na spletni strani ne bo mogoče kupiti, vendar bodo stranke lahko spremljale izdelek in preverjale, kdaj bo ta ponovno na voljo.
  • Začasno morate izdelek skriti s spleta - pri posodabljanju razpoložljivosti izdelka je mogoče uporabiti polje stanja, kjer z nastavitvijo vrednosti "N" izdelek ali različica postane "neaktiven".
  • Izbris izdelka - če veste, da izdelka ali različice ne bo na zalogi več kot 2 meseca, priporočamo, da izdelek ali različico izbrišite prek ustrezne končne točke. MALL hrani zgodovinske podatke o prodaji vaših izdelkov; če naložite izdelek pod istim ID, se bodo podatki o prodaji ponovno seznanili.

Pomembno: Neaktivnih izdelkov ne posodabljajte. Pošiljanje posodobitev za neaktivne izdelke je zelo nezaželeno in obremenjujoče za platformo. Preseganje omejitve lahko privede do zastojev sistema in le delno sprejetih podatkov, kar lahko povzroči negativno izkušnjo kupca in potencialno izgubo na strani partnerja.

Nazaj na vrh


Kategorije

V našem vmesniku API lahko za pridobivanje podatkov o kategorijah uporabite dve osnovni končni točki. Preko prve, Drevo kategorij po državah pridobite drevo kategorij, ki je na voljo za to državo. S spremembo kode države v naslovu URL klica lahko z uporabo istega ključa API pridobite informacije o drevesih kategorij drugih držav.

Rezultat klica API je vedno nekaj podatkov, ki so bistveni za vašo integracijo.

  • menu item ID (=“menuItemId“) – edinstvena koda kategorije, ki jo lahko uporabite s klicem Category Detail. Klic za pridobitev seznama vseh parametrov in vrednosti je opisan spodaj.
  • Product Type ID (= "ProductTypeId") - tehnična koda kategorije, potrebna za razvrstitev izdelka. Ta koda se lahko ujema z več menuitemID.
  • Menu Constraints (= "MenuCosntraints") - obvezni parametri z vrednostmi, ki so potrebne za dodelitev izdelkov v podani menuitemID. Podroben članek o podrobnostih pogojev za kategorije si preberite tukaj.

Preverjanje spletnih prikazov: Izdelek, ki ste ga naložili v sistem in ne ustreza Menu Constraints, lahko ob prikazu pokaže napako in strankam ne bo na voljo.

Prek klicev API Category detail pridobite seznam podatkov. Prvi del vsebuje pogoje prikaza v dani kategoriji.

  • SAP ID (= "SapId") - tehnična oznaka kategorije. To je ista koda, ki je bila dana v prejšnjem klicu kot Product Type ID. Je tehnična koda kategorije, ki je potrebna za razvrstitev izdelka.
  • Category Conditions (= "CategoryConditions") - tukaj boste našli enake podatke kot v Menu Constraints v prejšnjem klicu. Če želite izdelek uvrstiti v katerokoli kategorijo, morate te pogoje vedno pravilno vnesti.

Preverjanje spletnih prikazov: Izdelek, ki ste ga naložili v sistem, ki ne izpolnjuje Category Conditions, lahko ob prikazu pokaže napako in strankam ne bo na voljo.

  • Other parameters (= “otherParameters“): Tu so navedeni vsi drugi parametri z vrednostmi, ki jih lahko uporabite in dodate svojim izdelkom. Za parametre morate vedno uporabiti seznam vrednosti, ki ga najdete tukaj, vnos lastnih vrednosti v parametre ni mogoč. Ime parametrov vedno dodajte izdelku v tehnična imena, polje „value“. Vrednosti vedno vnesite z imenom iz ciljne države prodaje, torej vrednosti iz polja „text“. Za številske vrednosti vedno uporabite enoto, navedeno v polju „unit“. Če parameter ne vsebuje vrednosti, ki jih potrebujete, nam pošljite zahtevo prek FAQ, Centra za pomoč.

Nazaj na vrh


Brands

Z API klicem Get all brands boste dobili popoln seznam razpoložljivih blagovnih znamk v vseh državah. Seznam ni edinstven za vsako državo posebej, zato ga lahko uporabite za povezavo s katerimkoli trgom MALL. Izdelkom vedno dodajte natančno zapisano polje "brand_id", vključno z velikimi črkami.

Za dodajanje blagovne znamke uporabite ustrezen zavihek na partnerskem portalu v skladu z navodili tukaj.


Nalepke

Z API klicem Get all labels boste vedno dobili popoln seznam etiket v naši zbirki podatkov. Nalepke se uporabljajo za trženjske kampanje in druge notranje procese. Uporaba teh nalepk ni dovoljena brez predhodne odobritve vašega prodajnega predstavnika v MALL.

  • FDEL - brezplačna dostava
  • SALE - odprodaja
  • NEW - novo

Nazaj na vrh

Kako koristna je bila ta objava?

Kliknite zvezdico, da ocenite objavo!

Povprečna ocena: / 5. Število glasov:

Ni še glasov! Bodite prvi, ki bo ocenil to objavo.

Niste našli, kar ste iskali, pišite nam...