API klíče, webhooky a napojení

Obsah dokumentace

Napojení obchodu na automatizaci, vlastní systém, účetní aplikaci nebo AI asistenta se nastavuje v Nastavení → API a MCP. Tenhle článek vysvětluje, kdy potřebujete klíč a kdy webhook, a popisuje odchozí webhooky a napojení na Make.com a n8n. Zapnutí ploch, vydání, úprava, výměna a odvolání klíče, využití a protokol volání jsou v článku API a MCP.

Klíč, nebo webhook?

Oddíl Nastavení → API a MCP nabízí dvě cesty a liší se směrem:

Odchozí webhook posílá obchod vám. Když se v obchodě něco stane, odejde na vaši adresu podepsaný HTTP POST. Hodí se na „udělej něco, jakmile přijde objednávka“.
API klíč používá váš scénář, když si sám sáhne pro data. Hodí se na „každé ráno si stáhni stav skladu“.

Většina napojení potřebuje obojí: webhook jako spouštěč a klíč na dotažení podrobností.

Nejdřív zapněte plochu

Nic z toho nefunguje, dokud vlastník obchodu nezapne v Nastavení → API a MCP plochu, kterou napojení potřebuje. Zapíná se přepínačem v kartě Externí přístup a poprvé s potvrzením odpovědnosti: vydaným klíčem si data obchodu odnese program, který provozuje někdo další, a ten není naším zpracovatelem. Zapojujete ho svým jménem a na svou odpovědnost, jak stojí ve smlouvě o zpracování osobních údajů. Externí přístup je součástí placených tarifů, a to včetně jejich zkušebního období: stačí, že obchodu běží zkušební období placeného tarifu a máte u nás uloženou platební kartu. Na bezplatném tarifu Free se zapnout nedá.

Plochy jsou dvě a zapínají se zvlášť:

REST API je jen ke čtení: objednávky, vratky a zásilky, produkty a kategorie, zásoby a skladové pohyby, zákazníci, doklady i s PDF a ISDOC a feedy dodavatelů (odběry, běhy synchronizace, položky ke schválení, cenová pravidla a objednávky u dodavatele). Nic přes něj nezměníte. Patří k němu i odchozí webhooky.
Server MCP je opačný případ. Tudy jdou všechny zápisy zvenčí: asistent přes něj umí posunout stav objednávky (a tím zákazníkovi poslat e-mail), zapsat skladový pohyb, upravit produkt i jeho běžnou cenu nebo stránku a utratit kredity za vygenerovaný obrázek. S oprávněním Předplatné navíc navýší tarif: mimo zkušební období strhne rozdíl z karty uložené u SHOPZI, ve zkušebním období se nestrhne nic. Vždycky až po potvrzení přesné částky. Zrušit objednávku ale neumí, to je vyhrazené člověku v administraci.

Když potřebujete jen vytáhnout objednávky do účetnictví, zapněte jen REST API. Zápisovou plochu kvůli tomu otevírat nemusíte.

O přístup se už nežádáDřív se o otevření rozhraní žádalo formulářem a otevírala ho podpora SHOPZI. Teď si REST API i server MCP zapíná vlastník obchodu sám, takže formulář se žádostí z administrace zmizel.

Klíč pro scénář

Scénář, který si sahá pro data, potřebuje API klíč. Vydává ho vlastník obchodu v kartě API klíče v Nastavení → API a MCP tlačítkem Vytvořit klíč. Klíč dostane název, plochu, platnost, měsíční strop kreditů a oprávnění a ukáže se jednou; potom už v seznamu uvidíte jen jeho začátek. Dávejte mu jen ta oprávnění, která scénář opravdu potřebuje: klíč jen se zásobami nikdy neukáže objednávky ani osobní údaje zákazníků. Celý postup je v článku API a MCP.

Přes REST API /api/v1/… se data jen čtou, s limitem volání za minutu a za den podle tarifu; čísla jsou v článku Chybové odpovědi. Které cesty existují a co vracejí, vypisuje článek Endpointy REST API.

Odchozí webhooky

Odchozí webhooky jsou v části Webhooky oddílu Nastavení → API a MCP, v kartě Odchozí webhooky. Spravovat je smí vlastník i manažer. Založení koncového bodu:

Klikněte na Přidat koncový bod.
Vyplňte Adresu koncového bodu. Přijímáme jen https a adresy do vnitřní sítě odmítáme.
Doplňte nepovinný Popis (nepovinné), ať je za půl roku poznat, komu adresa patří.
Zaškrtejte události ve čtyřech skupinách: Objednávky (vytvořena, zaplacena, vyřízena, odeslána, doručena, zrušena, refundována), Katalog a sklad (produkt vytvořen, upraven, smazán, docházející zásoba), Zákazníci a doklady (nový zákazník, vystaven doklad, žádost o vrácení / reklamace) a Feedy dodavatelů (objednávka odeslána dodavateli, dodavatel ji potvrdil, odeslal zákazníkovi nebo nemůže dodat, synchronizace feedu něco změnila nebo selhala, nové položky ke schválení, dodavatel vyřadil zboží z feedu a souhrnná změna skladu z feedu za jeden běh). Bez aspoň jedné události koncový bod nevznikne.
Klikněte na Přidat koncový bod. Ukáže se Koncový bod byl přidán.

Nastavení, oddíl API a MCP, část Webhooky: karta Odchozí webhooky s tlačítkem Přidat koncový bod a dvěma aktivními koncovými body (n8n a Make), u každého odebírané události a tlačítka Odeslat test, Zobrazit tajemství, Nové tajemství, Pozastavit, Log doručení a Smazat. — Karta Odchozí webhooky: dokud je REST API vypnuté, jsou webhooky pozastavené a tlačítko Přidat koncový bod nejde stisknout.

U hotového koncového bodu je adresa, popis, čas posledního úspěchu, případně počet neúspěchů v řadě, stav (Aktivní, Pozastaveno, nebo Vypnuto pro opakované chyby) a tlačítka:

Odeslat test pošle zkušební zprávu, aby si protistrana načetla strukturu dat. Výsledek najdete v logu doručení.
Zobrazit tajemství ukáže Podpisové tajemství, kterým si příjemce ověří, že zpráva je opravdu od nás. Nové tajemství vygeneruje jiné a to staré zneplatní, proto se napřed zeptá dialogem Vygenerovat nové podpisové tajemství?.
Pozastavit odesílání dočasně zastaví a Zapnout ho zase pustí.
Log doručení ukáže posledních 25 zpráv se stavem (Ve frontě, Doručeno, Neúspěch, zkusíme znovu, nebo Vzdáno), odpovědí protistrany a počtem pokusů. Podrobnosti ukážou odeslané tělo i odpověď, Odeslat znovu zprávu pošle ještě jednou.
Smazat po potvrzení v dialogu Smazat koncový bod? odstraní adresu i s logem.

Doručujeme nejméně jednou: při neúspěchu opakujeme po 1 minutě, 5 minutách, 30 minutách, 2 hodinách a 6 hodinách, pak zprávu vzdáme. Po deseti vzdaných zprávách v řadě se adresa sama pozastaví, dostane označení Vypnuto pro opakované chyby a do zvonku přijde upozornění Odchozí webhook byl vypnut. Opravte scénář a koncový bod znovu zapněte tlačítkem Zapnout.

Bez zapnutého REST API webhooky nechodíWebhooky patří k REST API a platí pro ně totéž: plocha REST API musí být obchodu zapnutá a obchod musí mít tarif, který externí přístup zahrnuje. Když tomu tak není, karta webhooků ukáže, že jsou pozastavené a proč, a odkaz Přejít na přepínače vás vrátí ke kartě Externí přístup. Nové události se neodesílají (ani později), zprávy čekající ve frontě skončí v logu jako Vzdáno a testovací zprávu ani nový koncový bod založit nejde. Po znovuzapnutí chodí nové události hned a vzdané zprávy jde poslat odkazem Odeslat znovu.

Hromadné změny webhook neposílajíUdálosti chodí za jednotlivými změnami: jedna objednávka, jeden produkt, jeden doklad. Hromadné úkony schválně mlčí, a to import produktů, hromadná změna stavu i hromadné odstranění. Tisícová dávka by jinak znamenala tisíc zpráv během pár vteřin, váš příjemce by narazil na svůj vlastní strop a koncový bod by se po deseti selháních sám pozastavil, takže byste přišli i o události, které chcete. Po hromadné změně si katalog načtěte přes API. Docházející zásoba je ze stejného důvodu jedna denní zpráva se seznamem položek, ne zpráva na každou položku.

Make.com a n8n

Obě služby umí obecný webhook, takže nepotřebují žádnou aplikaci ani instalaci. V Make založte scénář s modulem Webhooks → Custom webhook, zkopírujte URL a vložte ji v části Webhooky oddílu Nastavení → API a MCP jako nový koncový bod. Pak klikněte na Odeslat test, ať si Make načte strukturu dat. V n8n přidejte uzel Webhook s metodou POST, zapněte Raw Body (bez surového těla nejde ověřit podpis) a použijte Production URL. Data si pak dotáhnete modulem HTTP (Make), respektive uzlem HTTP Request (n8n) s hlavičkou Authorization: Bearer <klíč>.

Recept Jak to napojit na Make.com a n8n pod seznamem koncových bodů obsahuje i hotový kód na ověření podpisu. Nepřeskakujte ho: podpis, který nikdo neověřuje, je jen ozdoba. Celou smlouvu pro příjemce, tedy hlavičky, podpis, opakování a tvar zprávy, popisuje článek Webhooky: příjem událostí.

Připojení AI asistenta (MCP)

Server MCP dává asistentovi jako Claude Code, Cursor nebo VS Code přímý přístup k datům obchodu. Místo vypisování exportů se zeptáte „kolik mám produktů bez popisu“ a asistent si data dotáhne sám.

V kartě Připojení klienta v Nastavení → API a MCP je adresa serveru a hotové nastavení pro Claude Code, Cursor, VS Code a jiného klienta; tentýž blok s klíčem už doplněným ukáže i dialog nového klíče. Ověřuje se stejným API klíčem jako REST API, takže asistent uvidí přesně to, na co klíč má oprávnění. Nástroje, na které oprávnění chybí, se mu vůbec nenabídnou.

Co něco přepisuje nebo maže, co sahá na veřejný internet, co utrácí vaše kredity a co strhává peníze z karty (navýšení tarifu), se vás přes MCP napřed zeptá a spustí se až po vašem potvrzení. Celý postup i s tím, co takový asistent smí a nesmí měnit, je v článku Připojení AI asistenta (MCP).

Propojení vlastního účtu Google nebo Apple ID pro přihlašování zůstalo v oddílu Integrace, viz Integrace a přihlašování přes Google a Apple.

Časté potíže

Tlačítko Přidat koncový bod je šedé. Webhooky jsou pozastavené, protože REST API je vypnuté nebo obchod nemá tarif s externím přístupem. Důvod stojí nad seznamem, odkaz Přejít na přepínače vede ke kartě Externí přístup.

„Vyberte alespoň jednu událost, která se má odesílat.“ Zaškrtněte aspoň jednu událost.

Adresu to nevezme. Přijímáme jen adresy začínající https:// a nikdy adresy do vnitřní sítě.

Koncový bod má stav Vypnuto pro opakované chyby. Adresa desetkrát po sobě neodpověděla ani po všech opakováních. Zkontrolujte scénář, klikněte na Zapnout a vzdané zprávy pošlete z logu doručení odkazem Odeslat znovu.

Scénář přestal přijímat zprávy po kliknutí na Nové tajemství. Nové tajemství to staré zneplatní. Vložte do scénáře nové, které ukáže Zobrazit tajemství.

Scénář dostal tutéž zprávu dvakrát. Doručujeme nejméně jednou, takže se to po výpadku na vaší straně stát může. Deduplikujte podle hlavičky webhook-id.