# Rozhraní pro vývojáře > Dvě rozhraní do obchodu: REST API jen ke čtení a MCP server pro asistenta. Čím se liší, kdy sáhnout po kterém a co si připravit, než začnete. - Sekce: Pro vývojáře - Stránka: https://shopzi.cz/dokumentace/vyvojari/rozhrani-prehled - Ověřeno: 2026-10-20 --- Dokumentace pro vývojáře je psaná pro toho, kdo staví napojení. Popisují se v ní **rozhraní**: adresy, hlavičky, tvary odpovědí a to, co se stane, když něco selže. Obrazovky administrace popisuje [uživatelská dokumentace](/dokumentace). Obchod má dvě rozhraní, a nejsou to dvě verze téhož. ## REST API [#rest-api] Klasické REST a JSON přes HTTPS na cestě `/api/v1`. Volá ho **váš program** a dělá přesně to, co jste do něj napsali: stáhne objednávky, vratky a zásilky, projde katalog, přečte zásoby a skladové pohyby, zákazníky, doklady i s PDF a ISDOC nebo data feedů dodavatelů (odběry, katalog dodavatelů, fronta ke schválení, dropship objednávky). Cest je 24 a jsou vypsané v článku [Endpointy REST API](/dokumentace/vyvojari/rest-api-endpointy); strojový popis ve formátu OpenAPI, ze kterého si vygenerujete klienta, je v článku [OpenAPI popis REST API](/dokumentace/vyvojari/openapi). > **Čte a nezapisuje, a není to nedodělek** Všechny cesty REST API odpovídají jen na GET. Cizí systém, který zapisuje do objednávek a do skladu, potřebuje vlastní řešení idempotence, validace a auditu, a to postavíme pořádně, nebo vůbec. Nepočítejte tedy se zápisovou cestou: neexistuje a nemá slíbený termín. Když potřebujete něco měnit, je k tomu MCP server. ## MCP server [#mcp-server] Jedna adresa, `/api/mcp`, kterou volá **AI asistent** podle protokolu Model Context Protocol. Rozdíl proti REST API není v datech, ale v tom, kdo rozhoduje: nástroj si vybírá model podle toho, na co se ho člověk zeptal, a v mezích oprávnění klíče také zapisuje. Nástrojů je celkem 40, z toho 19 jen ke čtení. Většinu zápisů jde vzít zpět nástrojem na vrácení změn; co vrátit nejde a na co se proto nástroj napřed zeptá, vypisuje článek [MCP server](/dokumentace/vyvojari/mcp-server). Připojení konkrétního klienta popisuje článek [Připojení asistenta k obchodu](/dokumentace/vyvojari/pripojeni-asistenta). ## Založení obchodu z terminálu [#zalozeni-obchodu-z-terminalu] Obchod, který ještě neexistuje, nemá doménu ani klíč, a proto pro jeho založení běží zvláštní server MCP **na shopzi.cz**, bez klíče. Umí jen to, co k založení obchodu patří: ceník tarifů, kontrolu subdomény, koncept obchodu a jeho stav, a k tomu hledání v dokumentaci. Člověk koncept v prohlížeči dokončí a uloží platební kartu (prvních 30 dní je zdarma), a klíč k novému obchodu se mu ukáže jednou na konci. K žádnému existujícímu obchodu tenhle server nepřistupuje. Postup je v článku [Založení obchodu přes MCP](/dokumentace/vyvojari/zalozeni-obchodu-pres-mcp). ## Co je společné [#co-je-spolecne] * **Adresa je doména vašeho obchodu**, ne shopzi.cz. Obchod se rozpoznává z hostitele požadavku, takže úplná cesta vypadá jako `https://muj-eshop.cz/api/v1/orders`. Žádnou centrální adresu, na kterou by se dal poslat identifikátor obchodu, nevydáváme; jediný veřejný server na shopzi.cz zakládá nové obchody a do existujících nevidí. * **Jeden druh klíče pro obě rozhraní.** Klíč vydává vlastník obchodu v administraci a zaškrtává u něj oprávnění. Navíc u něj volí **plochu**: obě rozhraní, jen REST API, nebo jen server MCP; na té druhé pak klíč dostane `403 key_surface_mismatch`. Viz [Autentizace a oprávnění](/dokumentace/vyvojari/autentizace-a-opravneni). * **Volání mají strop na klíč.** REST API počítá volání za minutu a za den podle tarifu obchodu a odpověď na volání, které prošlo všemi branami, nese hlavičky `X-RateLimit-*`; server MCP počítá volání nástrojů zvlášť, v hodinovém a denním okně na klíč, také podle tarifu. Čísla a co dělat s odpovědí 429 jsou v článku [Chybové odpovědi](/dokumentace/vyvojari/chybove-odpovedi). * **Peníze jsou celá čísla v haléřích.** Pole končící na `_minor` je částka v nejmenší jednotce měny, vedle ní stojí `currency_code`. Nikdy to není desetinné číslo. Proč to tak je, vysvětluje článek [DPH a ceny](/dokumentace/produkty/dph-a-ceny). Čtecí nástroje serveru MCP k ní navíc posílají hotový text pro model pod jménem bez `_minor` (`price` vedle `price_minor`); REST API ho neposílá, integrace čtou celé číslo. * **Opačný směr obsluhují webhooky.** Když má obchod zavolat vám, zaregistrujete si koncový bod: [Webhooky: příjem událostí](/dokumentace/vyvojari/webhooky). ## Než začnete [#nez-zacnete] Všechno, co k napojení potřebujete od obchodu, se nastavuje v **Nastavení → API a MCP**, v části **Přístup a klíče**. Oddíl najdete v levém sloupci Nastavení ve skupině **Technické**. 1. **Zapněte plochu.** V kartě **Externí přístup** má **REST API** i **Server MCP** vlastní přepínač. Zapíná je jen vlastník obchodu: poprvé s potvrzením odpovědnosti a při každém zapnutí s druhým ověřením, heslem nebo kódem z e-mailu. Externí přístup je součástí placených tarifů, a to včetně jejich zkušebního období s uloženou platební kartou. Obchod založený přes MCP má server MCP zapnutý rovnou, REST API si vlastník zapíná sám. 2. **Založte si klíč** v kartě **API klíče** tlačítkem **Vytvořit klíč**. Vydat ho smí jen vlastník a jen tehdy, když je aspoň jedna plocha zapnutá: jinak administrace odmítne s tím, že by klíč nic neotevřel. V poli **Kde klíč platí** zvolte plochu a zaškrtejte jen ta oprávnění, která napojení opravdu potřebuje. 3. **Ověřte klíč**, ještě než postavíte první scénář. Klíč pro REST API ověříte cestou `/api/v1/ping`: rozliší neplatný klíč od chybějícího oprávnění, což je rozdíl, který se jinak hledá dlouho. Klíč jen pro server MCP na ní dostane `403 key_surface_mismatch`, protože ping patří k REST API; ten se ověřuje voláním `tools/list`. Marketingový přehled obou rozhraní je na stránkách [API](/api) a [MCP](/mcp). Obchodnickou verzi téhož, tedy postup klikáním v administraci, najdete v článcích [API a MCP](/dokumentace/nastaveni/api-a-mcp), [API klíče, webhooky a napojení](/dokumentace/nastaveni/api-klice-a-webhooky) a [Připojení AI asistenta (MCP)](/dokumentace/nastaveni/mcp-pripojeni-asistenta).