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.
Testovací prostředí: Pro testování i pro reálný prodej existuje pouze jedno prostředí, a to produkční. API klíč, který získáte po registraci je proto neměnný a finální. I přesto lze nejdříve napojení testovat. Váš účet je až do doby jeho aktivace pouze v testovacím módu. Finální zobrazení vaší nabídky na web proběhne ale až po schválení oddělení onboardingu, pro více informací kontaktujte svého onboarding specialistu.
Je velmi důležité dodržovat následující doporučení. Dopady nedodržení doporučených postupů mohou být limitující pro fungování API volání vaší společnosti, a to s ohledem na zátěž pro systém MALL. S ohledem na tyto skutečnosti funguje v rámci platformy MALL rate limiter, více o něm se dozvíte v článku zde. Jakákoliv překročení SLA způsobená nesprávnou implementací API a překročení rate limitů jdou k tíži 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“.
Obsah
Objednávky
V rámci endpointů pro objednávky je důležité věnovat pozornost především posloupnosti jednotlivých kroků. Ta se dělí na dvě základní možnosti podle toho, zda využíváte webhook pro získávání informací o změnách v objednávkách. Více o webhooku se dočtete zde.
V tomto článku se dozvíte jak správně navazovat jednotlivé metody a přepínat jednotlivé stavy v rámci API, doporučujeme též pročíst článek vysvětlující detailně jednotlivé stavy, kterých může objednávka nabývat a co znamenají zde.
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.
Důležité: Jakékoliv aktualizace stavů objednávek zasílejte pouze v případě změn v objednávkách. Opakované zasílání téže informace je vysoce nežádoucí a zatěžující pro 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. Dostáváte notifikaci z webhooku s číslem objednávky, u které došlo ke změně.
2. Volejte Get order detail u objednávek ve stavu BLOCKED pro rezervaci zboží. Jedná se o objednávky, ke kterým vám přišla první notifikace. Přebírejte pouze informace o zboží. Finanční informace získávejte až u objednávek ve stavu OPEN. Rezervace zboží není povinná, je však vysoce doporučovaná u zboží s vysokou prodejností a s tím spojeným rizikem vyprodání.
3. Dostáváte webhook notifikaci u objednávky, u které došlo ke změně do stavů OPEN nebo CANCELLED.
4. Volejte Update order s confirmed = true pro OPEN nebo CANCELLED objednávky, u kterých došlo dle informací z webhooku ke změně. Možná je změna stavu z BLOCKED do OPEN nebo CANCELLED (toto je finální stav a již není možné objednávku znovu otevřít).
5. Volejte Get order detail na objednávky z kroku 4., u CANCELLED objednávek zrušte rezervaci. U OPEN objednávek využijte volání na potvrzené objednávky pro import finálních dat do vašeho systému. V tomto bodě již není možné z žádné strany do objednávky zasáhnout, všechny informace například o adrese a výši dobírky tak jsou v tomto bodě finální.
6. Volejte Update order objednávky ze stavu OPEN do SHIPPING pro veškeré objednávky, u kterých jste začali proces expedice. Pokud jste zjistili, že objednávku nebude možné expedovat, je v tomto bodě možné změnit objednávku do stavu CANCELLED.
7a. Při využití MALL Delivery volejte Generate labels for selected MDP orders pro tisk štítků pro MALL Delivery objednávky.
7b. Pokud nevyužíváte MALL Delivery, je třeba splnit podmínky pro expedici určené vaším dopravcem.
8. Předání zásilky přepravní společnosti.
9a. Při využití MALL Delivery, volejte Update order pro změnu stavu objednávky z SHIPPING na SHIPPED (změna stavu na SHIPPED musí vždy proběhnout až po předání zásilky přepravní společnosti).
9b. Pokud nevyužíváte MALL Delivery, volejte Update order objednávek z SHIPPING na SHIPPED, a to včetně tracking URL a čísla zásilky dopravce. Všechny informace je třeba zaslat v rámci jednoho volání, aby byla splněna kritéria Kvality služeb – Tracking rate.
Volitelné: Při využití MALL Delivery, můžete na základě webhook notifikace o změně v objednávce volat GET order detail pro objednávky ve stavu DELIVERED/RETURNED/LOST, a to za účelem dotažení finální stavu objednávek do vašeho systému.
10. Pokud nevyužíváte MALL DELIVERY volejte Update order z SHIPPED na DELIVERED s přesným datem doručení na základě informací od vašeho dopravce. Pokud máte od dopravce k dispozici informaci o první pokusu o doručení, je možné ji též doplnit, tato informace je nepovinná. Update je třeba zasílat v jednom volání. Pokud se objednávku nepodařilo doručit a došlo k jejímu vrácení odesílateli, změňte stav objednávky ze stavu SHIPPED na RETURNED.
SLA a zákaznická zkušenost: U obou dvou forem napojení objednávek je směrem k zákazníkovi žádoucí a je to zároveň i finálním SLA, aby se zasílání stavů objednávek zakládalo na pravdě a bylo co nejaktuálnější. Chybnou implementací zasílání stavů může dojít k negativní zákaznické zkušenosti a rušení objednávek.
Posloupnost objednávkových volání bez využití webhooku
1. Volejte Get list of unconfirmed orders s pravidelnou frekvencí, doporučujeme frekvenci přizpůsobit průměrnému počtu objednávek. Frekvenci 1x za hodinu překračujte pouze v případě více než 100 objednávek denně. Při volání použijte filter=basic.
2. Na základu List of unconfirmed orders volejte Get order detail u objednávek ve stavu BLOCKED pro rezervaci zboží. Přebírejte pouze informace o zboží. Finanční informace získávejte až u objednávek ve stavu OPEN. Rezervace zboží není povinná, je však vysoce doporučovaná u zboží s vysokou prodejností a s tím spojeným rizikem vyprodání.
3. Volejte Update order s confirmed = true pro OPEN/CANCELLED objednávky které byly zaregistrovány vaším systémem ve volání.
4. Volejte Get order detail na OPEN potvrzené objednávky pro import finálních dat do vašeho systému. V tomto bodě již není možné z žádné strany do objednávky zasáhnout, všechny informace například o adrese a výši dobírky tak jsou v tomto bodě finální.
5. Volejte Update order objednávky ze stavu OPEN do SHIPPING pro veškeré objednávky, u kterých jste začali proces expedice. Pokud jste zjistili, že objednávku nebude možné expedovat, je v tomto bodě možné změnit objednávku do stavu CANCELLED.
6a. Při využití MALL Delivery volejte Generate labels for selected MDP orders pro tisk štítků pro MALL Delivery objednávky.
6b. Pokud nevyužíváte MALL Delivery, je třeba splnit podmínky pro expedici určené vaším dopravcem.
Doporučení: Před odeslání objednávky doporučujeme zkontrolovat stav objednávku. Ve stavu SHIPPING je možné ze strany zákazníka objednávku zrušit. Taková objednávka bude pak systémem změněna do stavu CANCELLED. I tato změna se pak objeví v seznamu Get list of unconfirmed orders a je třeba jí potvrdit skrze krok 3.
7. Předání zásilky přepravní společnosti.
8a. Při využití MALL Delivery volejte Update order pro změnu stavu objednávky z SHIPPING na SHIPPED (změna stavu na SHIPPED musí vždy proběhnout až po předání zásilky přepravní společnosti).
8b. Pokud nevyužíváte MALL Delivery, volejte Update order objednávek z SHIPPING na SHIPPED, a to včetně tracking URL a čísla zásilky dopravce. Všechny informace je třeba zaslat v rámci jednoho volání, aby byla splněna kritéria Kvality služeb – Tracking rate.
Volitelné: Při využití MALL Delivery můžete využít volání Get list of orders by status s použitím časového filtru pro DELIVERED/RETURNED/LOST objednávky za účelem dotažení finální stavu objednávek do vašeho systému.
9. Pokud nevyužíváte MALL Delivery, volejte Update order z SHIPPED na DELIVERED s přesným datem doručení na základě informací od vašeho dopravce. Pokud máte od dopravce k dispozici informaci o první pokusu o doručení, je možné ji též doplnit, tato informace je nepovinná. Update je třeba zasílat v jednom volání. Pokud se objednávku nepodařilo doručit a došlo k jejímu vrácení odesílateli, změňte stav objednávky ze stavu SHIPPED na RETURNED.
Zpětná validace dat: Pokud nastane případ, ve kterém je třeba získat zpětně data o objednávkách, volejte vždy jednotlivé objednávky, jejichž data potřebujete. Pokud je i přesto nutné vyvolat seznam objednávek, využijte filtry časového období a vyvarujte se volání celé historie objednávek najednou. Pro účely fakturace a vyúčtování při využití služby MALL Self-Billing využívejte příslušné endpointy.
Produkty
U produktů je třeba se zaměřit na dva druhy volání, zakládání produktů a jejich aktualizaci.
Zakládání produktů a variant
Při zakládání produktů prosím vždy dbejte na naše podmínky obsahu produktů, detaily naleznete zde. Dále pak pozorně prostudujte podmínky zobrazení produktů v jednotlivých kategoriích v článku zde pro prevenci nutnosti následovné opravy produktů skrze další volání.
Důležité: Pokud mají vaše produkty varianty, vždy tvořte variantní produkty na základě parametrů dostupných v dané kategorii. Zasílání variantní produktů jako jednotlivé záznamy je nežádoucí a může vézt ke stažení nabídky z webu.
Produkty bez variant zakládejte za pomocí volání Create new product, při chybě u tohoto volání jsme pro vás připravili článek vysvětlující jednotlivé chyby a případné způsob, jak těmto chybám předejít a opravit je. Článek naleznete pod odkazem zde. Struktura volání je povinná kromě elementů, u kterých je to v dokumentaci výslovně řečeno. Takto vytvořený produkt pak naleznete v seznamu produktů v portálu a také na webu na výpisu produktů, pro zobrazení můžete použít sandbox účet.
U variantních produktů nejdříve použijte metodu Create new product pro vytvoření hlavního produktu. Poté do tohoto produktu za pomocí metody Create new variant přidejte varianty. Varianty je třeba odlišit za pomocí variantních parametrů. Je možné využít až dva z parametrů dostupných v dané kategorii. Varianty přiřazené do hlavní produktu se pak zobrazení vždy na detailu produktu s příslušným parametrem jako volitelnou proměnnou ze strany zákazníka.
U produktů vyplňujte prioritu hodnotou 1. Systém automaticky řadí produkty pomocí algoritmu, který funguje na principu počtu prokliků, návštěvnosti a prodejnosti daného produktu.
Jedná se o zastaralý prvek, který je stále potřebné vyplnit, ale není vůbec zohledňován. V současnosti pracujeme na jeho odstranění.
U produktů je důležité uvádět EAN (GTIN), má přesně definovaný tvar – 13 numerických znaků. EAN má zásadní vliv na párování produktů na Google Ads, Heureku a Zboží.cz a tedy možnost oslovit vašimi produkty daleko více zákazníků.
V případě, že má váš EAN 14 numerických znaků, vložte ho jako 13místný bez 0 na začátku. Pokud máte kratší 8místný EAN doplňte na začátek tolik 0 kolik chybí do 13 znaků (5).
Aktualizace produktů
U produktů rozdělujeme aktualizaci do několika druhů.
- Aktualizace produktových dat (popisky, obrázky, parametry,..)
- Aktualizace ceny
- Aktualizace dostupnosti
Důležité: Jakékoliv aktualizace produkt zasílejte pouze v případě změn. Opakované zasílání téže informace je vysoce nežádoucí a zatěžující pro platformu.
Aktualizace produktových dat
Při aktualizaci produktových dat využívejte příslušnou UPDATE metodu nevariantního produktu nebo varianty. Data měňte pouze v případě jejich změny, nebo potřeby o doplnění. Při jakékoliv aktualizaci produktu je vždy třeba zasílat všechny elementy, ne pouze ty, u kterých došlo ke změně.
Aktualizace ceny
Pro aktualizaci ceny nepoužívejte metodu na update produktu či varianty popsanou výše. Pro změnu ceny je dostupné samostatné volání skrze které změnu zasílejte a to jak pro nevariantní produkt, tak pro varianty. Při aktualizaci ceny o více než 30% je třeba změnu ceny potvrdit skrze force token. Více informací o této funkci se dozvíte v naší dokumentaci zde.
Aktualizace dostupnosti
Pro aktualizaci dostupnosti nepoužívejte metodu na update produktu či varianty popsanou výše. Pro změnu dostupnosti používejte metodu na hromadnou změnu dostupnosti produktů skrze Batch update of product/variant availability. Využívejte prosím tuto možnost aktualizace v maximální možné míře, skrze hromadný update je možné aktualizovat až 1000 produktů/variant najednou.
Eventuelně je při nutnosti změn u jednotek kusů možné využít metodu na aktualizaci skladové dostupnosti produktu či varianty.
Zpětná validace dat: Pokud nastane případ, ve kterém je třeba získat zpětně data o produktech, volejte je pouze v případě nutnosti a to přes příslušné endpoint na cenu či dostupnost. Jakékoliv pravidelné hromadné či jednotlivé volání o produktových datech je vysoce nežádoucí a zatěžující pro náš systém a může vést k omezení vašeho napojení na MALL.
Batch (hromadné) endpointy
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.
Dostupné batch endpointy jsou:
- Batch availability update – Jak bylo popsáno výše u aktualizace dostupnosti, jedná se o hromadný update dostupnosti produktů a variant. Tato metoda umožňuje update až 1000 změn v jednom volání.
- Active selected products – Hromadná změna vybraných produktů z draft do live.
- Activate products – Hromadná změna všech produktů z draft do live.
Deaktivace a mazání produktů
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.
- Dočasné vyprodání produktu, který bude znovu naskladněn – v takovém případě v rámci aktualizace dostupnosti produktu stačí snížit skladovou dostupnost produktu na „0“, tento pak nebude možné na webu pořídit, zákazníci pak stále po nějakou dobu budou mít možnost sledovat, zda se produkt znovu objeví v nabídce.
- Dočasná potřeba stažení produktu z webu – opět skrze aktualizaci dostupnosti produktu je možné využít pole status, kde nastavení hodnoty „N“ se produkt či varianta stává „neaktivní“.
- Mazání produktu – pokud víte, že daný produkt nebo varianta nebude naskladněn více než 2 měsíce, doporučujeme produkt či variantu skrze příslušný endpoint smazat. MALL udržuje historizovaná data prodejů vašich produktů, pokud pak produkt nahrajete pod stejným ID, budou mu data prodejů opět napárována.
Důležité: Jakýkoliv produkt, který je neaktivní neaktualizujte. Opakované zasílání updatu neaktivních produktů je vysoce nežádoucí a zatěžující pro platformu. Při přesáhnutí limitu může dojít k zahlcení systému, pouze k částečné akceptaci dat, která může mít za následek jak negativní zákaznickou zkušenost tak i potenciální ztrátu na straně partnera.
Kategorie
V rámci naší API využívejte pro získávání dat o kategoriích dva základní endpointy. V prvním z nich Category tree by country získáte strom kategorií dostupný pro danou zemi. Změnou kódu země v URL adrese volání pak při použití téhož API klíče můžete získat informace o stromech kategorií dalších zemí.
Výsledkem API volání pak je vždy několik údajů zásadních pro vaši integraci.
- menu item ID (=“menuItemId“) – unikátní kód kategorie jehož použitím můžete voláním Category Detail získat seznam všech parametrů a hodnot, volání je popsáno níže.
- Product Type ID (=“productTypeId“) – technický kód kategorie potřebný pro zařazení produktu, tento kód se může shodovat napříč více menuitemID.
- Menu Constraints (=“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 zde.
Validace zobrazení na webu: Produkt, který jste nahráli do systému, který nesplňuje Menu Constraints, může vykazovat error při zobrazení a nebude jej tak možné pořídit zákazníky.
Skrze API volání Category detail pak získáte seznam údajů. V první části jsou podmínky zobrazení v dané kategorii.
- SAP ID (=“sapId“) – technický kód kategorie, jedná se o tentýž kód, který byl v předchozím volání uveden jako Product Type ID, jedná se o technický kód kategorie potřebný pro zařazení produktu.
- Category Conditions (=“categoryConditions“) – zde najdete tytéž údaje jako v Menu Constraints v předchozím volání. Pro zařazení produktu do jakékoliv kategorie je vždy třeba tyto podmínky bezchybně zadat.
Validace zobrazení na webu: Produkt, který jste nahráli do systému, který nesplňuje Category Conditions, může vykazovat error při zobrazení a nebude jej tak možné pořídit zákazníky.
- Other parameters (=“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 „value“. Hodnoty vždy uvádějte v názvu cílové země prodeje, tj. hodnoty z pole „text“. V případě numerických hodnot vždy vycházejte z jednotky uvedené v poli „unit“. Pokud daný parametr neobsahuje hodnoty, které potřebujete, zašlete nám žádost skrze Centrum nápovědy.
Značky
Použitím volání Get all brands získáte kompletní seznam dostupných značek napříč všemi zeměmi. Seznam není unikátní pro každou zemi zvlášť, můžete jej proto využívat pro napojení na kterýkoliv z trhů programu MALL Partner. K produktům vždy přidávejte údaj z pole „brand_id“ a to ve 100% shodě včetně velkých písmen.
Pro přidání značky využijte příslušnou záložku v partnerském portálu dle návodu zde.
Štítky
Použitím volání Get all labels získáte vždy kompletní seznam štítků v naší databázi. Štítky slouží k marketingovým kampaním a dalším interním procesům. Bez předchozího schválení vašeho obchodního zástupce v MALL je možné používat tyto štítky.
- FDEL – doprava zdarma
- SALE – výprodej
- NEW – novinka
Čeština 
English 
Slovenščina 
Magyar