Vlastné napojenie objednávok cez API Mergado Marketplaces#
Mergado Marketplaces má hotové napojenia objednávok na systémy ako POHODA, Shoptet Premium, WooCommerce, UNAS alebo Upgates. Ak objednávky vybavujete v inom systéme, napríklad vo vlastnom ERP, skladovom programe alebo internej aplikácii, môžete si ich napojiť sami cez API Mergado Marketplaces. Stačí vývojár, ktorý napojenie naprogramuje na strane vášho systému.
Cez API môžete:
- sťahovať objednávky zo všetkých marketplaces napojených v Mergado Marketplaces (Allegro, Kaufland, Amazon) vrátane všetkých údajov, ktoré obsahuje export objednávok do CSV: zákazník, fakturačná a doručovacia adresa, platba, doprava, položky objednávky, dokumenty a poznámky,
- označiť objednávky ako naimportované zápisom ich ID z vášho systému, takže pri ďalšom stiahnutí dostanete len tie nové,
- meniť stav objednávky vrátane čísla zásielky a dopravcu. Zmena sa odošle priamo na Allegro alebo Kaufland,
- nahrať faktúru k objednávke na Allegre alebo Kauflande.
Kompletná technická dokumentácia je v dokumentácii API Mergado Marketplaces. Nájdete v nej všetky endpointy, ich parametre a podobu odpovedí. Volania si v nej môžete vyskúšať priamo na dátach vášho e-shopu.
📝 Dobré vedieť:
- Dokumentácia API aj chybové hlášky sú v angličtine.
- API je určené pre vývojárov. Ak chcete objednávky napojiť bez programovania, pozrite sa, či váš systém nájdete medzi pripravenými napojeniami v Mergado Marketplaces.
Čo budete potrebovať#
- Aktívne rozšírenie Mergado Marketplaces s napojením aspoň jedného marketplace.
- Osobný prístupový token (PAT) z vášho konta v Mergade s oprávnením Čítanie dát e-shopu.
- ID e-shopu v Mergade.
- Vývojára, ktorý napojenie naprogramuje vo vašom systéme.
⚠️ Používajte buď API, alebo hotové napojenie na e-shop, nie oboje naraz. Ak máte v Mergado Marketplaces aktívne napojenie objednávok na e-shopovú platformu (napríklad Shoptet Premium, Upgates alebo WooCommerce) a zároveň rovnaké objednávky spracúvate cez API, môžu si oba systémy navzájom prepisovať stavy objednávok.
Ako napojenie nastaviť#
1. Vytvorte osobný prístupový token#
- V Mergado Editore kliknite vpravo hore na svoj profil a otvorte API a prístupy.
- Kliknite na + Vytvoriť token, token pomenujte (napríklad „Napojenie objednávok do ERP") a nastavte jeho platnosť.
- V oprávneniach zaškrtnite v skupine E-shop možnosť Čítanie dát e-shopu. Iné oprávnenia API Mergado Marketplaces nepotrebuje.
- Token vytvorte, skopírujte a bezpečne uložte. Po opustení stránky sa už znovu nezobrazí.
Podrobný postup nájdete v článku Osobný prístupový token (PAT).
⚠️ Nezamieňajte Čítanie dát e-shopu (skupina E-shop) s oprávnením Čítanie e-shopov používateľa (skupina Používateľ). API Mergado Marketplaces potrebuje to prvé.
Token má prístup k rovnakým e-shopom ako váš konto. Na čítanie objednávok stačí, keď máte k e-shopu prístup na čítanie. Na zmenu stavu objednávky, nahranie faktúry alebo zápis vlastného ID objednávky potrebuje vaše konto k e-shopu prístup na zápis.
2. Zistite ID e-shopu#
Každé volanie API obsahuje číselné ID e-shopu v Mergade. Najjednoduchšie ho zistíte tak, že si v nastavení API a prístupy zapnete zobrazovanie interných ID. ID e-shopu sa potom zobrazí v zátvorkách vedľa jeho názvu. Postup je v článku Zobrazenie interných ID entít.
3. Vyskúšajte API v dokumentácii#
- Otvorte dokumentáciu API Mergado Marketplaces.
- Kliknite na Authorize a vložte svoj osobný prístupový token.
- Vyberte napríklad endpoint pre výpis objednávok, zadajte ID e-shopu a kliknite na Try it out a Execute.
Dokumentácia vám ukáže skutočnú odpoveď s dátami vašich objednávok aj presnú adresu požiadavky, ktorú môže váš vývojár priamo použiť.
4. Napojte svoj systém#
Všetky volania idú cez Mergado API na adrese https://api.mergado.com/apps/ordelogyproducts/proxy. Token sa posiela v hlavičke Authorization: Bearer <váš token>. Konkrétne endpointy a parametre nájde vývojár v dokumentácii.
Odporúčaný postup synchronizácie objednávok#
Na pravidelné preberanie objednávok do vášho systému odporúčame tento postup:
- Sťahujte zmeny v pravidelnom intervale. Pri výpise objednávok použite parameter
updated_sinces časom posledného stiahnutia. Dostanete nové objednávky aj tie, u ktorých sa odvtedy niečo zmenilo, napríklad stav, údaje, chyba synchronizácie alebo nahraná faktúra. - Po importe si objednávku označte. Uložte k nej ID, ktoré má objednávka vo vašom systéme. Parametrom
imported=falsepotom vypíšete len objednávky, ktoré ste ešte neimportovali. - Vracajte zmeny späť. Keď objednávku vo svojom systéme odošlete, pošlite cez API stav SENT s číslom zásielky. Zmena sa prepíše priamo na marketplace. Rovnako tak môžete nahrať faktúru.
Časy bez uvedeného časového pásma API berie ako stredoeurópsky čas (Europe/Prague). V rovnakom časovom pásme sú aj všetky časy v odpovediach.
Stavy objednávok#
Mergado Marketplaces prevádza stavy z jednotlivých marketplaces na jednotné stavy. V API sa zobrazujú takto:
| Stav v API | Stav v Mergado Marketplaces |
|---|---|
OPEN |
otvorené |
READY |
neodoslané |
PROCESSING |
spracúva sa |
SENT |
odoslané |
ONHOLD |
pozastavené |
RETURNED |
vrátené |
CANCELLED |
zrušené |
UNKNOWN |
neznáma |
Cez API môžete nastaviť tieto stavy:
| Marketplace | Stavy, ktoré možno nastaviť |
|---|---|
| Allegro | PROCESSING, SENT, CANCELLED, ONHOLD |
| Kaufland | PROCESSING, SENT, CANCELLED |
U Amazonu možno objednávky cez API len čítať.
Stav v Mergado Marketplaces sa zmení až vo chvíli, keď ho marketplace prijme. Ak ho odmietne, API vráti chybu s dôvodom od marketplace a chyba sa zobrazí aj pri objednávke v Mergado Marketplaces. Neúspešná zmena sa automaticky neopakuje. Stav, ktorý už objednávka má, môžete poslať znovu, napríklad keď k odoslanej objednávke dodatočne dopĺňate číslo zásielky.
Faktúry#
K objednávke na Allegre alebo Kauflande môžete cez API nahrať faktúru vo formáte PDF o veľkosti najviac 5 MB spolu s číslom faktúry. Výsledok nahratia uvidíte v histórii objednávky v Mergado Marketplaces.
Limity#
- Na API môžete z jednej IP adresy poslať najviac 60 požiadaviek za minútu.
- Jedno volanie vráti najviac 1 000 objednávok. Ďalšie objednávky načítate po stránkach.
FAQ#
Potrebujem pre API nejaké špeciálne napojenie v Mergado Marketplaces?#
Nie. Stačí osobný prístupový token a ID e-shopu. V sekcii Napojenia len skontrolujte, že máte pri marketplaces zapnutú synchronizáciu objednávok. Nič ďalšie kvôli API nastavovať nemusíte.
API vracia chybu 403 „Missing required scope: shop.read". Čo s tým?#
Token nemá oprávnenie Čítanie dát e-shopu. Vytvorte nový token a toto oprávnenie v skupine E-shop zaškrtnite.
API vracia chybu 403 „Access denied for this eshop". Čo s tým?#
Vaše konto nemá k e-shopu potrebný prístup, alebo sa ID e-shopu nezhoduje. Skontrolujte ID e-shopu a prístup k nemu. Na zmenu stavu, nahranie faktúry a zápis ID objednávky potrebujete prístup na zápis. Nový udelený prístup sa môže prejaviť až za 5 minút.
API vracia chybu 401. Čo s tým?#
Požiadavka neobsahuje token, alebo je token neplatný. Skontrolujte, že token posielate v hlavičke Authorization celý a že nevypršala jeho platnosť ani nebol zneplatnený.
Prečo mi pri sťahovaní podľa dátumu chýbajú zmeny starších objednávok?#
Parametre date_from a date_to filtrujú podľa dátumu, keď zákazník objednávku vytvoril. Zmeny stavu starších objednávok, napríklad zrušenie, tak nezachytia. Na pravidelnú synchronizáciu použite parameter updated_since.
Môžem API používať zároveň s napojením objednávok na e-shopovú platformu?#
Neodporúčame to. Ak by objednávky súbežne spracúvalo napojenie na e-shop (napríklad Shoptet Premium alebo Upgates) aj váš systém cez API, môžu si navzájom prepisovať stavy objednávok. Na prenos objednávok používajte buď API, alebo hotové napojenie.
Môžem cez API pracovať s viacerými e-shopmi?#
Áno. Token funguje pre všetky e-shopy, ku ktorým má vaše konto v Mergade prístup. V každom volaní uvádzate ID e-shopu, s ktorým chcete pracovať.
Pomôžete nám s napojením?#
Samotné napojenie programuje váš vývojár podľa dokumentácie. Ak pri napojovaní narazíte na problém alebo vám v API chýba údaj, ktorý potrebujete, napíšte na podporu Mergada.