Rozhraní pro vývojáře | Dokumentace pro vývojáře SHOPZI

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.

Obchod má dvě rozhraní, a nejsou to dvě verze téhož.

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; strojový popis ve formátu OpenAPI, ze kterého si vygenerujete klienta, je v článku OpenAPI popis REST API.

Čte a nezapisuje, a není to nedodělekVš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

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. Připojení konkrétního klienta popisuje článek Připojení asistenta k obchodu.

Založení obchodu z terminálu

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.

Co je společné

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í.
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.
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. Č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í.

Než začnete

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é.

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.
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.
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 a MCP. Obchodnickou verzi téhož, tedy postup klikáním v administraci, najdete v článcích API a MCP, API klíče, webhooky a napojení a Připojení AI asistenta (MCP).