# API klíče, webhooky a napojení > Kdy potřebujete klíč a kdy webhook, jak založit odchozí webhook a jak obchod napojit na Make.com, n8n nebo AI asistenta. - Sekce: Nastavení obchodu - Stránka: https://shopzi.cz/dokumentace/nastaveni/api-klice-a-webhooky - Popisuje v administraci: /administrace/nastaveni?tab=api-mcp - Ověřeno: 2026-10-20 --- 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](/dokumentace/nastaveni/api-a-mcp). ## Klíč, nebo webhook? [#klic-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 [#nejdriv-zapnete-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ů](/zpracovani-osobnich-udaju). 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ů](/dokumentace/produkty/feedy-dodavatelu) (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ář [#klic-pro-scenar] 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](/dokumentace/nastaveni/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](/dokumentace/vyvojari/chybove-odpovedi). Které cesty existují a co vracejí, vypisuje článek [Endpointy REST API](/dokumentace/vyvojari/rest-api-endpointy). ## Odchozí webhooky [#odchozi-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: 1. Klikněte na **Přidat koncový bod**. 2. Vyplňte **Adresu koncového bodu**. Přijímáme jen `https` a adresy do vnitřní sítě odmítáme. 3. Doplňte nepovinný **Popis (nepovinné)**, ať je za půl roku poznat, komu adresa patří. 4. 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. 5. Klikněte na **Přidat koncový bod**. Ukáže se **Koncový bod byl přidán.** *Snímek obrazovky: 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 [#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 `. 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í](/dokumentace/vyvojari/webhooky). ## Připojení AI asistenta (MCP) [#pripojeni-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)](/dokumentace/nastaveni/mcp-pripojeni-asistenta). 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](/dokumentace/nastaveni/integrace). ## Časté potíže [#caste-potize] **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`.