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 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.
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“.
Kazalo vsebine
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.
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.
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.
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. 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 CANCELLED.
4. Uporabite API klic Update order z vrednostjo confirmed = true for OPEN za odprta ali preklicana naročila CANCELLED naročila, ki so bila spremenjena glede na informacije iz spletne kljuke. Možna sprememba statusa iz BLOCKED do OPEN ali CANCELLED (to je končno stanje in naročila ni več mogoče ponovno odpreti).
5. Uporabite API klic Get order detailza naročila iz koraka številka 4., za preklicana CANCELLED 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 CANCELLED.
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 orderza 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 naročilo iz 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 DELIVERED/RETURNED/LOST za dokončno potrditev končnega stanja naročil v vašem sistemu.
10. Če ne uporabljate možosti MALL DELIVERY, uporabite klic Update orderiz 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.
Posloupnost objednávkových volání bez využití webhooku
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 BLOCKEDnaroč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/CANCELLED 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 CANCELLED.
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 orderza 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 Get list of orders by status z uporabo časovnega filtra za naročila s statusom DELIVERED/RETURNED/LOST 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 (endpoints).
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 Create new product č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 account.
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.
Sistem samodejno razvršča izdelke s pomočjo algoritma, ki deluje na podlagi števila klikov, prometa in prodaje določenega izdelka.
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
- Posodobitve 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.
Posodobitve 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.
Množične končne točke (batch endpoints)
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.
Razpoložljive množične končne točke so:
- Batch availability update - Kot je opisano zgoraj za posodobitev razpoložljivosti, gre za množično posodabljanje razpoložljivosti izdelkov in različic. Ta metoda omogoča posodobitev do 1000 sprememb v enem klicu.
- Active selected products - množična sprememba izbranih izdelkov iz osnutka v živo.
- Activate products - Množična sprememba vseh izdelkov iz ugreza v živo.
Deaktivacija in brisanje izdelkov
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.
- 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.
Kategorije
V našem vmesniku API za pridobivanje podatkov o kategorijah uporabljamo dve osnovni končni točki. V prvem Category tree by country boste dobili drevo kategorij, ki je na voljo za državo. Če v URL-ju klica spremenite kodo države, lahko z istim ključem API pridobite informacije o drevesih kategorij za druge države.
Rezultat klica API je vedno nekaj podatkov, ki so bistveni za vašo integracijo.
- ID elementa menija (=“menuItemId“) – unikátní kód kategorie jehož použitím můžete voláním Podrobno o kategoriji dobite seznam vseh parametrov in vrednosti, klic je opisan v nadaljevanju.
- ID tipa izdelka (=“productTypeId“) – technický kód kategorie potřebný pro zařazení produktu, tento kód se může shodovat napříč více menuitemID.
- Omejitve menija (=“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 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 nato boste dobili seznam podatkov. Prvi del vsebuje pogoje za prikaz kategorije.
- SAP ID (=“sapId“) – technický kód kategorie, jedná se o tentýž kód, který byl v předchozím volání uveden jako ID tipa izdelkaTo je oznaka tehnične kategorije, ki je potrebna za razvrstitev izdelka.
- Kategorija Pogoji (=“categoryConditions“) – zde najdete tytéž údaje jako v Omejitve menija v předchozím volání. Pro zařazení produktu do jakékoliv kategorie je vždy třeba tyto podmínky bezchybně zadat.
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.
- Drugi 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 "vrednost". Hodnoty vždy uvádějte v názvu cílové země prodeje, tj. hodnoty z pole "besedilo". V případě numerických hodnot vždy vycházejte z jednotky uvedené v poli "enota". Pokud daný parametr neobsahuje hodnoty, které potřebujete, zašlete nám žádost skrze FAQ, Centra za pomoč.
Brands
Z API klicemGet all brands dobite popoln seznam razpoložljivih blagovnih znamk v vseh državah. Seznam ni edinstven za vsako državo, zato ga lahko uporabite za povezavo s katerim koli partnerskim trgom MALL. Izdelkom v ujemanju 100%, vključno z velikimi črkami, vedno dodajte podatke iz polja "brand_id".
Za dodajanje blagovne znamkeuporabite 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