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 za dejansko prodajo, in sicer proizvodnja (production). Ključ API, ki ga dobite pri registraciji, je dokončen in ga ni mogoče spreminjati. Kljub temu je mogoče najprej preizkusiti povezavo. Vaš račun je v preskusnem načinu samo dokler ni aktiviran. Končni prikaz vaše ponudbe na spletnem mestu bo potekal šele po odobritvi oddelka za onboarding. Za več informacij se obrnite na svojega strokovnjaka za onboarding.

Zelo pomembno je upoštevati naslednja priporočila. Rezultat neupoštevanja priporočil je lahko omejeno delovanje klicev API vašega podjetja, saj lahko klici preobremenijo sistem MALL. Zato na platformi 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


Naročila

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 vzpostaviti posamezne metode in preklopiti posamezna stanja naročil znotraj API-ja. Priporočamo tudi branje članka, ki podrobno razloži posamezna stanja, ki jih lahko ima naročilo in kaj ta pomenijo tukaj.

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 spletni kavelj in v ustrezen zavihek na partnerskem portalu v meniju Partner vstaviti URL, ki ste ga pripravili sami, nato pa lahko v dnevniku spodaj vidite posamezna odhodna 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. Prevzamite le informacije o blagu. Finančne informacije prevzemajte 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. Obvestilo spletnega kavlja prejmete za naročila, katererih stanje se je spremenilo v odprto OPEN ali CANCELED.

Uporabite API klic Update order z vrednostjo confirmed = true za odprta naročila (OPEN) ali preklicana naročila (CANCELED), samo za naročila, ki so bila spremenjena glede na informacije iz spletnega kavlja. Možna je sprememba stanja iz blokiranega (BLOCKED) v odprto (OPEN) ali preklicano (CANCELED) (to so končna stanja 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 za potrjena naročila za uvoz končnih podatkov v svoj sistem. Na tej točki v naročilo ni več mogoče posegati z nobene strani, vsi podatki, kot sta naslov in znesek nakupa, so na tej točki dokončni.

6. Uporabite API klic Update order za spremembo naročil z odprtim stanjem OPEN v stanje 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 možnosti MALL Delivery, morate izpolniti pogoje za odpremo, ki jih je določil vaša dostavna služba.

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 poslano 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 poslano 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 (DELIVERED), vrnjeno (RETURNED) ali izgubljeno (LOST) in s tem uredite končno stanje naročila 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 poslano DELIVERED z natančnim datumom dostave na podlagi informacij vaše dostavne službe. Če imate informacije dostavne službe o prvem poskusu dostave, jih je mogoče dodati 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 poslano 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. Uporabite API klic Get list of unconfirmed orders z redno frekvenco. Priporočamo prilagoditev frekvence na povprečno število naročil. Frekvenco presegajte le enkrat na uro za 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 (OPEN) ali preklicana (CANCELLED) naročila, ki jih je vaš sistem registriral v klicu.

4. Uporabite API klic Get order detail za odprta (OPEN) naročila in s tem prenesite končne informacije v vaš sistem. V tem trenutku ni več mogoče posegati v naročilo s katere koli strani, vsi podatki, kot sta naslov in znesek plačila po povzetju, so dokončni.

5. Uporabite API klic Update order za spremembo naročil z odprtim stanjem OPEN v stanje 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 možnosti MALL Delivery, morate izpolniti pogoje za odpremo, ki jih je določil vaša dostavna služba.

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 poslano 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 poslano 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 Get list of orders by status z uporabo časovnega filtra za naročila s stanjem dostavljeno (DELIVERED), vrnjeno (RETURNED) ali izgubljeno (LOST) in s tem uredite 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 dostavljeno (DELIVERED) z natančnim datumom dostave na podlagi informacij vaše dostavne službe. Če imate informacije dostavne službe o prvem poskusu dostave, jih je mogoče dodati 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 vrnjeno (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 ne kličite celotne zgodovine naročil naenkrat. Za namene zaračunavanja in izdajanja računov pri uporabi storitve 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 variantne izdelke na podlagi parametrov, ki so na voljo v dani kategoriji. Pošiljanje različic izdelkov kot posameznih zapisov je nezaželeno in lahko vodi do tega, da vaše ponudbe ne bodo prikazane na spletu.

Izdelke brez različic ustvarite z API klicem Create new product. V primeru napak pri tem klicem smo za vas pripravili članek z razlago posameznih napak in načinom, kako te napake preprečiti in odpraviti. Članek najdete 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.

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 pridobiti podatke o izdelku, uporabite API klic le po potrebi in le prek ustrezne končne točke (endpoint) za ceno ali razpoložljivost. Redni množični ali posamični klici za podatke o izdelkih so zelo nezaželeni in obremenjujoči za naš sistem ter lahko privedejo do omejitev vaše povezave z MALL.

Nazaj na vrh

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

Znotraj API-ja MALL se nekatera dejanja lahko izvajajo v velikem obsegu, za veliko število izdelkov. Z uporabo množičnih končnih točk boste znatno zmanjšali uporabo omejitve klicev API znotraj omejevalnika hitrosti, zato je priporočljivo, da jih uporabite čim bolj pogosto.

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šete prek ustrezne končne točke. MALL hrani podatke o zgodovini prodaje vaših izdelkov, zato se bodo podatki o prodaji ponovno združili, če boste izdelek kasneje naložili pod istim ID-jem.

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


Kategorija

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 sestavljen iz več 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 boste našli vse ostale parametre z vrednostmi, ki jih lahko uporabite in dodate svojim izdelkom. Za parametre je vedno treba uporabiti seznam vrednosti, ki ga najdete tukaj, saj v parametre ni mogoče vnesti lastnih vrednosti. Izdelku v tehničnih poljih vedno dodajte ime parametra „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 potrebnih vrednosti, pošljite zahtevo na onboarding@mallgroup.com.

Nazaj na vrh


Blagovne znamke

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 dobili popoln seznam nalepk v naši bazi podatkov. Nalepke se uporabljajo za tržne kampanje in druge notranje procese. Spodaj navedene nalepke se lahko uporabljajo brez predhodne odobritve prodajnega zastopnika podjetja 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.