Vlastní napojení objednávek přes API Mergado Marketplaces#

Mergado Marketplaces má hotová napojení objednávek na systémy jako POHODA, Shoptet Premium, WooCommerce, UNAS nebo Upgates. Pokud objednávky vyřizujete v jiném systému, třeba ve vlastním ERP, skladovém programu nebo interní aplikaci, můžete si je napojit sami přes API Mergado Marketplaces. Stačí vývojář, který napojení naprogramuje na straně vašeho systému.

Přes API můžete:

  • stahovat objednávky ze všech marketplaces napojených v Mergado Marketplaces (Allegro, Kaufland, Amazon) včetně všech údajů, které obsahuje export objednávek do CSV: zákazník, fakturační a doručovací adresa, platba, doprava, položky objednávky, dokumenty a poznámky,
  • označit objednávky jako naimportované zápisem jejich ID z vašeho systému, takže při dalším stažení dostanete jen ty nové,
  • měnit stav objednávky včetně čísla zásilky a dopravce. Změna se odešle rovnou na Allegro nebo Kaufland,
  • nahrát fakturu k objednávce na Allegru nebo Kauflandu.

Kompletní technická dokumentace je v dokumentaci API Mergado Marketplaces. Najdete v ní všechny endpointy, jejich parametry a podobu odpovědí. Volání si v ní můžete vyzkoušet rovnou na datech svého e-shopu.

📝 Dobré vědět:

Co budete potřebovat#

  • Aktivní rozšíření Mergado Marketplaces s napojeným alespoň jedním marketplacem.
  • Osobní přístupový token (PAT) z vašeho účtu v Mergadu s oprávněním Čtení dat e-shopu.
  • ID e-shopu v Mergadu.
  • Vývojáře, který napojení naprogramuje ve vašem systému.

⚠️ Používejte buď API, nebo hotové napojení na e-shop, ne obojí naraz. Pokud máte v Mergado Marketplaces aktivní napojení objednávek na e-shopovou platformu (například Shoptet Premium, Upgates nebo WooCommerce) a zároveň stejné objednávky zpracováváte přes API, mohou si oba systémy navzájem přepisovat stavy objednávek.

Jak napojení nastavit#

1. Vytvořte osobní přístupový token#

  1. V Mergado Editoru klikněte vpravo nahoře na svůj profil a otevřete API a přístupy.
  2. Klikněte na + Vytvořit token, token pojmenujte (například „Napojení objednávek do ERP") a nastavte jeho platnost.
  3. V oprávněních zaškrtněte ve skupině E-shop možnost Čtení dat e-shopu. Jiná oprávnění API Mergado Marketplaces nepotřebuje.
  4. Token vytvořte, zkopírujte a bezpečně uložte. Po opuštění stránky se už znovu nezobrazí.

Podrobný postup najdete v článku Osobní přístupový token (PAT).

⚠️ Nezaměňujte Čtení dat e-shopu (skupina E-shop) s oprávněním Čtení e-shopů uživatele (skupina Uživatel). API Mergado Marketplaces potřebuje to první.

Token má přístup ke stejným e-shopům jako váš účet. Pro čtení objednávek stačí, když máte k e-shopu přístup pro čtení. Pro změnu stavu objednávky, nahrání faktury nebo zápis vlastního ID objednávky potřebuje váš účet k e-shopu přístup pro zápis.

2. Zjistěte ID e-shopu#

Každé volání API obsahuje číselné ID e-shopu v Mergadu. Nejsnáze ho zjistíte tak, že si v nastavení API a přístupy zapnete zobrazování interních ID. ID e-shopu se pak zobrazí v závorce vedle jeho názvu. Postup je v článku Zobrazení interních ID entit.

3. Vyzkoušejte API v dokumentaci#

  1. Otevřete dokumentaci API Mergado Marketplaces.
  2. Klikněte na Authorize a vložte svůj osobní přístupový token.
  3. Vyberte například endpoint pro výpis objednávek, zadejte ID e-shopu a klikněte na Try it out a Execute.

Dokumentace vám ukáže skutečnou odpověď s daty vašich objednávek i přesnou adresu požadavku, kterou může váš vývojář rovnou použít.

4. Napojte svůj systém#

Všechna volání jdou přes Mergado API na adrese https://api.mergado.com/apps/ordelogyproducts/proxy. Token se posílá v hlavičce Authorization: Bearer <váš token>. Konkrétní endpointy a parametry najde vývojář v dokumentaci.

Doporučený postup synchronizace objednávek#

Pro pravidelné přebírání objednávek do vašeho systému doporučujeme tento postup:

  1. Stahujte změny v pravidelném intervalu. Při výpisu objednávek použijte parametr updated_since s časem posledního stažení. Dostanete nové objednávky i ty, u kterých se od té doby cokoli změnilo, například stav, údaje, chyba synchronizace nebo nahraná faktura.
  2. Po importu si objednávku označte. Uložte k ní ID, které má objednávka ve vašem systému. Parametrem imported=false pak vypíšete jen objednávky, které jste ještě neimportovali.
  3. Vracejte změny zpět. Když objednávku ve svém systému odešlete, pošlete přes API stav SENT s číslem zásilky. Změna se propíše přímo na marketplace. Stejně tak můžete nahrát fakturu.

Časy bez uvedeného časového pásma API bere jako středoevropský čas (Europe/Prague). Ve stejném časovém pásmu jsou i všechny časy v odpovědích.

Stavy objednávek#

Mergado Marketplaces převádí stavy z jednotlivých marketplaces na jednotné stavy. V API se zobrazují takto:

Stav v API Stav v Mergado Marketplaces
OPEN otevřeno
READY neodesláno
PROCESSING zpracovává se
SENT odesláno
ONHOLD pozastaveno
RETURNED vráceno
CANCELLED zrušeno
UNKNOWN neznámá

Přes API můžete nastavit tyto stavy:

Marketplace Stavy, které lze nastavit
Allegro PROCESSING, SENT, CANCELLED, ONHOLD
Kaufland PROCESSING, SENT, CANCELLED

U Amazonu lze objednávky přes API jen číst.

Stav v Mergado Marketplaces se změní až ve chvíli, kdy ho marketplace přijme. Pokud ho odmítne, API vrátí chybu s důvodem od marketplace a chyba se zobrazí i u objednávky v Mergado Marketplaces. Neúspěšná změna se automaticky neopakuje. Stav, který už objednávka má, můžete poslat znovu, například když k odeslané objednávce dodatečně doplňujete číslo zásilky.

Faktury#

K objednávce na Allegru nebo Kauflandu můžete přes API nahrát fakturu ve formátu PDF o velikosti nejvýše 5 MB spolu s číslem faktury. Výsledek nahrání uvidíte v historii objednávky v Mergado Marketplaces.

Limity#

  • Na API můžete z jedné IP adresy poslat nejvýše 60 požadavků za minutu.
  • Jedno volání vrátí nejvýše 1 000 objednávek. Další objednávky načtete po stránkách.

FAQ#

Potřebuji pro API nějaké speciální napojení v Mergado Marketplaces?#

Ne. Stačí osobní přístupový token a ID e-shopu. V sekci Napojení jen zkontrolujte, že máte u marketplaces zapnutou synchronizaci objednávek. Nic dalšího kvůli API nastavovat nemusíte.

API vrací chybu 403 „Missing required scope: shop.read". Co s tím?#

Token nemá oprávnění Čtení dat e-shopu. Vytvořte nový token a toto oprávnění ve skupině E-shop zaškrtněte.

API vrací chybu 403 „Access denied for this eshop". Co s tím?#

Váš účet nemá k e-shopu potřebný přístup, nebo se ID e-shopu neshoduje. Zkontrolujte ID e-shopu a přístup k němu. Pro změnu stavu, nahrání faktury a zápis ID objednávky potřebujete přístup pro zápis. Nově udělený přístup se může projevit až za 5 minut.

API vrací chybu 401. Co s tím?#

Požadavek neobsahuje token, nebo je token neplatný. Zkontrolujte, že token posíláte v hlavičce Authorization celý a že nevypršela jeho platnost ani nebyl zneplatněn.

Proč mi při stahování podle data chybí změny starších objednávek?#

Parametry date_from a date_to filtrují podle data, kdy zákazník objednávku vytvořil. Změny stavu starších objednávek, například zrušení, tak nezachytí. Pro pravidelnou synchronizaci použijte parametr updated_since.

Můžu API používat zároveň s napojením objednávek na e-shopovou platformu?#

Nedoporučujeme to. Pokud by objednávky současně zpracovávalo napojení na e-shop (například Shoptet Premium nebo Upgates) i váš systém přes API, mohou si navzájem přepisovat stavy objednávek. Pro přenos objednávek používejte buď API, nebo hotové napojení.

Můžu přes API pracovat s více e-shopy?#

Ano. Token funguje pro všechny e-shopy, ke kterým má váš účet v Mergadu přístup. V každém volání uvádíte ID e-shopu, se kterým chcete pracovat.

Pomůžete nám s napojením?#

Samotné napojení programuje váš vývojář podle dokumentace. Pokud při napojování narazíte na problém nebo vám v API chybí údaj, který potřebujete, napište na podporu Mergada.

Byl tento článek užitečný?