# API a MCP > Oddíl nastavení, ve kterém vlastník zapíná REST API a server MCP, vydává a upravuje klíče, sleduje využití a protokol volání a spravuje odchozí webhooky. - Sekce: Nastavení obchodu - Stránka: https://shopzi.cz/dokumentace/nastaveni/api-a-mcp - Popisuje v administraci: /administrace/nastaveni?tab=api-mcp - Ověřeno: 2026-10-20 --- **Nastavení → API a MCP** je místo pro všechno, co pouští k datům obchodu programy zvenčí: účetní nebo skladový systém a Make.com přes **REST API**, AI asistenta přes **server MCP** a scénáře, kterým obchod sám posílá **odchozí webhooky**. Oddíl najdete v levém sloupci Nastavení ve skupině **Technické**. Má čtyři části, mezi kterými přepínáte nahoře: **Přístup a klíče**, **Využití**, **Protokol volání** a **Webhooky**. ## Kdo co smí [#kdo-co-smi] Co kdo v **Nastavení → API a MCP** smí: * **Vlastník obchodu** zapíná a vypíná obě plochy a vydává, upravuje a vyměňuje klíče. * **Manažer** a **účet podpory SHOPZI** vidí stav ploch, klíče, využití i protokol a smí klíč odvolat. Zapnout plochu ani vydat klíč nemohou, a místo přepínačů uvidí větu, že externí přístup zapíná a vypíná jen vlastník obchodu. * Ostatní role klíče ani protokol neuvidí. ## Zapnutí REST API a serveru MCP [#zapnuti-rest-api-a-serveru-mcp] Karta **Externí přístup** je nahoře v části **Přístup a klíče** oddílu **Nastavení → API a MCP**. Má dva řádky, **REST API** a **Server MCP**, a každý vlastní přepínač. Plochy se zapínají zvlášť, protože dělají velmi různé věci: * **REST API** slouží ke čtení objednávek, produktů, zásob a dokladů pro účetnictví, sklad nebo BI. Přes REST API se nic nemění. Patří k němu i odchozí webhooky. * **Server MCP** dává AI asistentovi (Claude, Cursor, VS Code) nástroje obchodu. Umí i zapisovat: každou změnu, která něco přepisuje, maže nebo stojí kredity, napřed potvrdí člověk. *Snímek obrazovky: Část Přístup a klíče: REST API a server MCP mají každý vlastní přepínač a klíče se vydávají v kartě pod nimi.* 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. ### Co znamená stav u plochy [#co-znamena-stav-u-plochy] * **Zapnuto**: plocha odpovídá klientům s platným klíčem. * **Zapnuto, ale zavřeno**: přepínač je zapnutý, ale plochu drží zavřenou něco, co nezávisí na přepínači. Pod řádkem je věta, co to je: obchod nemá aktivní placený tarif, SHOPZI přístup obchodu pozastavilo, nebo je plocha dočasně vypnutá pro všechny obchody. Jakmile překážka zmizí, plocha se otevře sama a klíče fungují dál. * **Teď nejde zapnout**: plocha je vypnutá a některá z těch překážek brání ji zapnout. Přepínač nejde použít a věta pod řádkem říká proč. * **Vypnuto**: plocha klientům neodpovídá. Externí přístup je součástí placených tarifů: potřebuje aktivní placený tarif, jednorázovou licenci, nebo běžící zkušební období s **uloženou platební kartou**. Obchod na tarifu Free, se zrušeným předplatným nebo ve zkušebním období bez karty plochu nezapne a v kartě uvidí odkaz **Externí přístup je součástí placených tarifů**, který vede do Předplatného. ### Postup zapnutí [#postup-zapnuti] 1. U plochy klikněte na přepínač. Nejdřív se ověří, že obchod plochu zapnout smí; když ne, dozvíte se to hned, bez hesla i bez dialogu. 2. Když plochu zapínáte poprvé, otevře se dialog **Potvrzení odpovědnosti**. Stojí v něm, že klient, kterému vydáte klíč, získá data obchodu v rozsahu oprávnění klíče, včetně osobních údajů zákazníků, pokud klíč takové oprávnění má; že takového klienta zapojujete vlastním jménem jako správce, WEBZI s.r.o. není jeho zpracovatelem a za smlouvu s ním i za informování zákazníků odpovídáte vy, jak to říká odstavec 9.4 Smlouvy o zpracování osobních údajů ve verzi 1.1; a že klíče chráníte jako heslo. Pod textem je odkaz na celou smlouvu. U serveru MCP je navíc věta, že klient s odpovídajícím oprávněním může obchod měnit a každou změnu, která něco přepisuje, maže nebo stojí kredity, musí potvrdit člověk. Totéž shrnuje [článek XXa obchodních podmínek](/obchodni-podminky#externi-pristup). 3. Zaškrtněte **Přečetl(a) jsem to a za klienty, kterým vydám klíč, odpovídám.** a klikněte na **Potvrdit a pokračovat**. Potvrzuje se jednou za obchod a plochu a uložíme, kdo, kdy, odkud a kterou verzi textu potvrdil. U plochy pak drobně stojí **odpovědnost potvrzena**. 4. Krok potvrďte heslem do administrace, nebo, pokud váš účet vznikl přes Google či Apple a heslo jste si nenastavili, tlačítkem **Poslat kód** a šestimístným kódem z e-mailu. Kód platí 10 minut a potvrzení také 10 minut. Plocha je zapnutá hned a všichni vlastníci obchodu dostanou e-mail a upozornění v administraci. ### Vypnutí [#vypnuti] Zapnutou plochu vypnete kliknutím na přepínač, bez hesla a bez potvrzování, i když obchod zrovna nemá tarif: kdo zjistí, že klíč unikl, nemá čekat na kód z e-mailu. Klienti dostanou odmítnutí hned při dalším volání a vlastníci obchodu se to dozvědí e-mailem a upozorněním. Klíče se vypnutím nemění, takže po opětovném zapnutí fungují dál. > **Když přístup pozastavilo SHOPZI** Pozastavení od SHOPZI zavře obě plochy bez ohledu na vaše přepínače a zrušit ho můžeme jen my. Klienti pak dostávají odmítnutí `external_access_suspended`; když plochu dočasně vypneme všem obchodům naráz, je to `external_access_disabled`. Automatický e-mail o tom nechodí: stav a důvod uvidíte na kartě Externí přístup a důvod vám sdělí podpora SHOPZI. Přepínače zůstanou, jak jste je nechali, takže po zrušení pozastavení se vrátí přesně to, co bylo zapnuté. Pod přepínači je počet aktivních klíčů a strop, který na ně dává tarif. Když na schválení čekají změny od asistenta, který se neumí zeptat ve svém okně, karta to řekne i s počtem. Otevřete je z upozornění ve zvonku nahoře a schválit je smí vlastník nebo manažer; víc v článku [Schválení změn z AI asistenta](/dokumentace/nastaveni/schvaleni-zmen-agenta). ## API klíče [#api-klice] Pod přepínači v části **Přístup a klíče** oddílu **Nastavení → API a MCP** je karta **API klíče**. Klíč nese oprávnění, plochu, platnost a měsíční strop kreditů. Každé napojení má mít vlastní klíč, ať jde odvolat právě ten jeden. *Snímek obrazovky: Nový API klíč: rychlá volba předvyplní oprávnění a řádek pod ní ukáže, kolik nástrojů a tokenů klíč asistentovi otevře.* Kolik aktivních klíčů obchod smí mít, určuje tarif: **Basic** 1, **Standard** 5, **Business** 20, **Enterprise** a jednorázová licence 50. Odvolané a vypršelé klíče se nepočítají, stejně jako klíč, který po výměně dobíhá. Když je strop plný, karta to řekne a nový klíč vznikne, až některý odvoláte, nebo na vyšším tarifu. ### Vytvoření klíče [#vytvoreni-klice] 1. Klikněte na **Vytvořit klíč**. Když není zapnutá ani jedna plocha, karta upozorní, že klíč by teď nic neotevřel. 2. V dialogu **Nový API klíč** vyplňte **Název klíče**, ať je za půl roku poznat, komu patří (třeba „Claude na notebooku“). 3. **Kde klíč platí**: **REST API i server MCP**, **Jen REST API**, nebo **Jen server MCP**. Klíč pro účetní systém, který jen čte, nemá důvod fungovat i pro asistenta, a naopak. 4. **Platnost**: 30 dní, 90 dní (doporučeno), 180 dní, 1 rok, nebo **Bez expirace**. Klíč bez expirace platí, dokud ho neodvoláte, a formulář na to upozorní. Před koncem platnosti přijde vlastníkům e-mail a upozornění, 14 a 3 dny předem. 5. **Měsíční strop kreditů**: kolik kreditů smí klíč za kalendářní měsíc utratit, výchozí je 2 000. Strop se obnoví prvního dne dalšího měsíce. Nula vypne pro tenhle klíč všechno, co stojí kredity (generování obrázků a videí, hledání na webu); čtení a zápisy zdarma fungují dál. Strop hlídá jen server MCP, přes REST API se kredity neutrácejí. 6. Zaškrtejte oprávnění, nebo začněte **Rychlou volbou**: **Vše**, **Čtení katalogu**, **Objednávky a sklad** a **Obsah a marketing**. Rychlá volba nastaví i to, kde klíč platí, a u každé je vidět, kolik nástrojů asistent uvidí a kolik tokenů zaplatí za jejich popis. Oprávnění jsou rozdělená na **Čtení** a **Zápis (jen server MCP)** a u každého je popiska, co otevírá. 7. Klikněte na **Vytvořit klíč**. Nejdřív se ověří, že obchod klíč vydat smí (zapnutá plocha, tarif a strop klíčů), a teprve potom krok potvrdíte heslem nebo kódem z e-mailu. > **Klíč uvidíte jednou a naposledy** Po vytvoření se otevře dialog **Klíč je vytvořený** s klíčem a tlačítkem na kopírování. Ukládáme si jen jeho otisk, takže ho znovu nepřečteme ani my. Když klíč platí pro server MCP, dialog ukáže i hotové nastavení pro Claude Code, Cursor, VS Code a jiného klienta s klíčem už doplněným (kromě VS Code, který se na klíč zeptá sám); když platí pro REST API, ukáže příkaz na ověření klíče proti `/api/v1/ping`. Dialog zavřete tlačítkem **Mám klíč uložený**. Klíč nevkládejte do chatu s asistentem, patří do nastavení klienta nebo do správce hesel. ### Seznam klíčů [#seznam-klicu] Tabulka má sloupce **Klíč**, **Přístup**, **Strop kreditů**, **Platnost** a **Naposledy**. Ve sloupci **Klíč** je název, stav (**Aktivní**, **Vyměněný, dobíhá**, **Vypršel**, **Odvolaný**) a začátek klíče (celý klíč už nikde neuvidíte). **Přístup** ukazuje plochu (například **REST API i server MCP**) a pod ní, kolik oprávnění klíč má ke čtení a kolik k zápisu; celý seznam oprávnění se ukáže po najetí myší. **Naposledy** je čas posledního volání a pod ním počet dnešních volání. Platnost se zvýrazní 14 dní před koncem a znovu, naléhavěji, 3 dny před ním, tedy ve stejné dny, kdy chodí připomínky e-mailem. Klíč bez expirace je označený také. Klíč, který vznikl při založení obchodu z terminálu, nese u názvu poznámku „vydaný při založení obchodu z terminálu“. Vpravo v řádku jsou ikony **Vyměnit klíč**, **Upravit klíč** a **Odvolat klíč**. Vyměnit a upravit jde jen aktivní klíč, odvolat i klíč, který po výměně dobíhá. ### Úprava klíče [#uprava-klice] **Upravit klíč** (jen vlastník) otevře dialog, ve kterém změníte **Název klíče**, **Platnost** (první volba **Beze změny** nechá platnost, jak je), **Měsíční strop kreditů** a oprávnění. Tajemství se úpravou nemění, takže napojení běží dál bez výměny. Plochu, na které klíč platí, úpravou nezměníte: na to je potřeba nový klíč. Změny uložíte tlačítkem **Uložit změny** a potvrdíte heslem nebo kódem z e-mailu. Vyměněný ani vypršelý klíč upravit nejde. ### Výměna a odvolání [#vymena-a-odvolani] **Vyměnit klíč** (jen vlastník) se zeptá, jestli klíč opravdu vyměnit, a po potvrzení heslem nebo kódem vydá nový klíč se stejným názvem, oprávněními, plochou i stropem kreditů. Ukáže se jednou v dialogu **Nový klíč po výměně**. **Starý klíč funguje ještě 24 hodin**, abyste ho stihli v napojení nahradit; potom přestane platit sám. **Odvolat klíč** smí vlastník, manažer i podpora. Klíč zneplatní v tu chvíli a nevratně: napojení, která ho používají, přestanou fungovat hned. Když klíč jen nahrazujete, použijte raději výměnu. O vytvoření, úpravě, výměně i odvolání klíče dostanou všichni vlastníci obchodu e-mail a upozornění v administraci. ### Připojení klienta [#pripojeni-klienta] Karta **Připojení klienta** ukazuje adresu **Serveru MCP** (končí na `/api/mcp`) a **REST API** (končí na `/api/v1`), obě na doméně vašeho obchodu, a hotové nastavení pro **Claude Code**, **Cursor**, **VS Code** a **Jiného klienta**. V ukázce stojí místo klíče `VÁŠ_API_KLÍČ`: nahraďte ho svým klíčem v nastavení klienta. Klient uvidí jen to, na co má klíč oprávnění, a REST API zůstává jen ke čtení. Připojení konkrétního asistenta krok za krokem popisuje článek [Připojení AI asistenta (MCP)](/dokumentace/nastaveni/mcp-pripojeni-asistenta). ## Co vám o přístupu přijde za zprávy [#co-vam-o-pristupu-prijde-za-zpravy] O dění kolem **Nastavení → API a MCP** vás obchod zpravuje sám. E-mail dostanou **všichni vlastníci obchodu**, upozornění ve zvonku vidí celý tým. Chodí tyhle: * **klíč vznikl, byl upraven, vyměněn nebo odvolán**, vždycky s názvem a začátkem klíče; * **klíč brzy vyprší**, 14 a 3 dny předem; * **REST API nebo server MCP byl zapnut nebo vypnut**, s tím, kdo přepínač přehodil; * **externí přístup je pozastavený**, když obchod přestane mít aktivní placený tarif: klienti pak dostávají `plan_required` a odchozí webhooky se neposílají. Nic se nemaže, klíče i koncové body zůstávají. Až tarif zase běží, přijde **externí přístup znovu běží** a všechno se rozjede se stávajícími klíči. Zpráva chodí jen tehdy, když má obchod aspoň jednu plochu zapnutou; * **neobvykle mnoho chyb a odmítnutí**: když na jedné ploše skončí za 15 minut padesát volání jednoho klíče (nebo volání bez platného klíče) chybou či odmítnutím. Nejčastěji je to rozbitá integrace, která zkouší pořád totéž, ale může to být i někdo, kdo zkouší klíče. Zpráva přijde nejvýš jednou denně na klíč a plochu a nepočítají se do ní odmítnutí, která nemáte jak spravit (vypnutá plocha, chybějící tarif, pozastavení od SHOPZI, požadavek bez klíče); * **tarif navýšil AI asistent**, se strženou částkou a klíčem, kterým se to stalo, viz [Navýšení tarifu z AI asistenta](/dokumentace/nastaveni/navyseni-tarifu-z-asistenta). Vyčerpaný **měsíční strop kreditů klíče** zprávu neposílá: poznáte ho v Protokolu volání podle výsledku **Strop kreditů** a v pruhu čísel ve Využití mezi odmítnutími. ## Využití [#vyuziti] Část **Využití** v **Nastavení → API a MCP** ukazuje, kolik práce externí přístup dostal za zvolené období. Období vyberete nahoře: **Dnes** (výchozí), **Včera**, **7 dní**, **30 dní** nebo **90 dní**. Pruh čísel má pět hodnot: * **Volání**: všechna volání obou ploch za období. * **Chyby**: volání, která skončila chybou. * **Odmítnutí**: volání, která brána nebo nástroj odmítly (neplatný klíč, chybějící oprávnění, vyčerpaný strop kreditů klíče a další odmítnutí). * **Nad limit**: volání nad strop počtu volání. * **Kredity**: kolik kreditů klíče za období utratily. Kredity utrácí jen server MCP. Pod pruhem je tabulka po klíčích se stejnými čísly, **Průměrnou dobou** odpovědi a časem, kdy klíč volal **Naposledy**. Volání bez platného klíče (neplatný nebo chybějící klíč, zavřená plocha) mají vlastní řádek **Bez platného klíče**. Denní statistiky držíme 90 dní a počítá se do nich každé volání, i to, jehož řádek protokol při záplavě neuložil. ## Protokol volání [#protokol-volani] Část **Protokol volání** v **Nastavení → API a MCP** je seznam jednotlivých volání, nejnovější nahoře. U každého je **Čas** na sekundy, **Klíč**, **Plocha**, **Operace**, **Výsledek**, stavový kód **HTTP**, **Doba** zpracování, **Kredity**, **IP** a **Klient**. Výsledek je jeden z těchto: **Úspěch**, **Chyba**, **Odmítnuto**, **Neověřený klíč**, **Bez oprávnění**, **Strop kreditů**, **Nad limit**, **Čeká na potvrzení** a **Čeká na schválení**. Protokol se řídí stejným obdobím jako **Využití** (**Dnes**, **Včera**, **7 dní**, **30 dní**, **90 dní**): když období přepnete na jedné části, platí i na druhé. Záznamy protokolu držíme 30 dní, takže delší období v něm ukáže nejvýš posledních 30 dní. Kolik chyb a odmítnutí za období přišlo, vidíte v pruhu čísel ve Využití. Filtry protokolu otevřete v liště: * **Plocha**: obě plochy, REST API, nebo server MCP. * **Výsledek**: chyby, odmítnutí, nad limit, čeká na člověka, nebo úspěšná volání. * **Klíč**: konkrétní klíč, nebo volání bez platného klíče. Odkaz **Zrušit filtry** vrátí celý protokol. Starší a novější záznamy procházíte odkazy **Starší** a **Novější**. Protokol ukládá jen metadata: kdo, kdy, odkud, jakou operací a s jakým výsledkem. Těla požadavků ani odpovědí se nikde neukládají. Záznamy starší než 30 dní se mažou a záplava neúspěšných volání se do protokolu zapisuje jen do stropu; v části Využití se ale počítá celá. ## Webhooky [#webhooky] Odchozí webhooky jsou v části **Webhooky** oddílu **Nastavení → API a MCP**: tlačítkem **Přidat koncový bod** zaregistrujete adresu, vyberete události, pošlete testovací zprávu a projdete log doručení. Pod seznamem je recept **Jak to napojit na Make.com a n8n**. Webhooky patří k REST API: když je REST API zavřené, karta 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. Podrobný postup je v článku [API klíče, webhooky a napojení](/dokumentace/nastaveni/api-klice-a-webhooky). ## Časté potíže [#caste-potize] **Přepínač nejde zapnout.** Věta pod řádkem plochy říká proč. Nejčastěji obchod nemá aktivní placený tarif. **Klient dostává `403 external_access_not_enabled`.** Plocha, na kterou volá, je vypnutá. Zapněte ji v kartě Externí přístup. **Klient dostává `403 key_surface_mismatch`.** Klíč platí jen pro druhou plochu. Plochu úpravou nezměníte, vytvořte klíč pro tu správnou. **Asistent nevidí nástroj, který má mít.** Klíči chybí oprávnění. Doplňte ho přes **Upravit klíč**. **Nástroje, které stojí kredity, skončí odmítnutím o stropu.** Klíč vyčerpal měsíční strop kreditů. Strop změníte přes **Upravit klíč**, jinak se obnoví prvního dne dalšího měsíce. **Nevidím přepínače ani tlačítko Vytvořit klíč.** Plochy zapíná a klíče vydává jen vlastník obchodu. Co který kód chyby znamená pro program na druhé straně, vypisuje článek [Chybové odpovědi](/dokumentace/vyvojari/chybove-odpovedi) v dokumentaci pro vývojáře.