MCP: nastavení, doprava a vyhledávání

Čtení a úprava nastavení po sekcích (čtení i právních dokumentů, hlavičky a patičky, přesměrování, měřicích kódů a napojení na účetnictví), nastavení obchodu z terminálu (firma, kontakt, právní dokumenty, doména, žádost o Comgate, spuštění a zavření závěsem, přesměrování, stavba celého obchodu z popisu), metody dopravy včetně váhových pásem a vyhledávání v obchodě.

Nástroje volá klient přes server MCP na doméně obchodu, například https://muj-eshop.cz/api/mcp, a v odpovědi na tools/list dostane jen ty, na jejichž oprávnění klíč dosáhne. Jak server mluví, kdy se ptá člověka a jak se změny vracejí, popisuje článek MCP server.

U každého nástroje stojí oprávnění, které chce, jestli se server před provedením zeptá člověka a kudy, jestli volání strhne kredity obchodu nebo peníze z karty, co vrací pro deník změn a jakou větu o důsledku člověk v potvrzení uvidí. Všechno z toho se vyhodnocuje z téhož kódu, podle kterého se server rozhoduje. Popisy parametrů jsou převzaté ze schématu, které server posílá v tools/list; kde se v něm text obrací přímo k modelu, je tady převedený do vykání. Povinnost parametru platí uvnitř objektu, ve kterém parametr leží.

Před zápisem, který přepisuje nebo maže, před útratou kreditů nebo platbou kartou a před hledáním mimo obchod se server ptá člověka a do té doby neprovede nic. Nejdřív použije schválení, které pro totéž volání se stejnými hodnotami už v administraci leží schválené. Jinak se zeptá formulářem, když ho klient deklaruje a politika akce ho dovoluje; formulář potvrzuje ten, kdo drží klíč, takže před ukradeným klíčem takové potvrzení nechrání. Otázka ve formuláři nese pod nadpisem „Co se změní“ tytéž řádky jako stránka schválení. Klient s elicitací URL dostane odkaz na stránku schválení v administraci a klient bez elicitace odmítnutí approval_required s odkazem v _meta; po schválení volání zopakuje se stejnými hodnotami. Na stránce schválení rozhoduje jen přihlášený člověk, kterého u každé akce jmenuje odrážka Potvrzení přes MCP, a účet podpory SHOPZI nikdy. Když politika nedovoluje nic, co klient umí, přijde odmítnutí confirmation_required a neprovede se nic. Výsledek potvrzeného volání nese v _meta["cz.shopzi/confirmation"] údaj, že akci potvrdil člověk a kde (form nebo approval), a v obsahu českou větu pro model, u placené akce i s cenou a zůstatkem kreditů z dotazu. Na otázku formulářem je 15 minut, schválení na stránce platí 60 minut, pokud u akce není uvedeno jinak.

Zápisové nástroje vracejí v poli change_id ID záznamu v deníku změn; co pole u kterého nástroje nese, říká jeho odrážka Deník změn. Změnu z deníku vrací shopzi_undo_change podle jejího druhu: obnoví předchozí hodnoty, u skladu zapíše vyrovnávací pohyb, u běžné ceny zapíše návrat do 30denní historie cen (nic z ní nemaže) a změnu, která už opustila obchod nebo stála peníze (odeslaný e-mail, stržené kredity, platbu kartou), odmítne s vysvětlením.

shopzi_get_settings

Vrátí jednu sekci nastavení podle resource, od údajů obchodu a dopravy po stav spuštění obchodu a průběh stavby obchodu (setup), předplatné (billing), právní dokumenty (legal, text jednoho přes document), hlavičku a patičku (storefront_layout), přesměrování (redirects), měřicí kódy (measurement) a napojení na účetnictví (accounting). Přístupové údaje k branám ani jiná tajemství nevrací nikdy; u měření říká jen, jestli je tajemství vyplněné.

• Oprávnění: settings:read, u klíče „Nastavení, doprava, platby, vzhled (čtení)“.
• Druh: čtení (readOnlyHint).
• Potvrzení přes MCP: ne.
• Kredity a platba kartou: ne.

shopzi_get_settings: oblasti

• store (Obecné nastavení)
• shipping (Doručení na adresu)
• payments
• appearance
• seo (SEO)
• notifications (Notifikace)
• products (Produkty)
• reviews (Recenze)
• inventory (Sklad)
• privacy (Soukromí)
• ai (AI)
• wholesale (Velkoobchod)
• hours (Pracovní doba)
• search
• setup
• billing
• legal (Právní dokumenty)
• storefront_layout
• redirects (Přesměrování)
• measurement
• accounting

shopzi_get_settings: parametry

• resource (jedna z hodnot store, shipping, payments, appearance, seo, notifications, products, reviews, inventory, privacy, ai, wholesale, hours, search, setup, billing, legal, storefront_layout, redirects, measurement a accounting; povinný)
• open_task (jedna z hodnot vat_payer, bank_account, stripe_connect, comgate_credentials, smtp, carrier_credentials, legal_edit a domain_purchase; nepovinný): Jen u setup: úkol, který se dělá jen v prohlížeči (účet, Stripe, Comgate, SMTP, dopravci, text právních dokumentů, nákup domény). Vrátí na něj odkaz do administrace.
• document (jedna z hodnot terms, gdpr, refund, withdrawal, delivery a cookies; nepovinný): Jen u legal: dokument, jehož text vrátit. Bez něj jen přehled.

shopzi_save_shipping_method

Založí nebo upraví metodu dopravy: cenu, váhová pásma (seznam se nahrazuje celý), hranici dopravy zdarma, limit dobírky, hmotnost, rozměry, rozvoz jen na vybraná PSČ, sazbu DPH a dopravce s funkčním napojením. Platební metody ani přístupové údaje k přepravcům tudy nevedou.

• Oprávnění: shipping:write, u klíče „Doprava: metody a ceny (zápis)“.

• Druh: zápis, který umí přepsat nebo smazat existující data (destructiveHint).

• Potvrzení přes MCP: ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí approval_required. Na stránce schválení rozhoduje vlastník nebo manažer obchodu.

• Kredity a platba kartou: ne.

• Deník změn: výsledek nese change_id. ID záznamu v deníku. Předejte ho do shopzi_undo_change.

• Věta o důsledku, kterou člověk uvidí v potvrzení:

  Nová cena, hranice dopravy zdarma i limit dobírky platí pro každou další objednávku. Vypnutá metoda zmizí zákazníkům z pokladny. Změnu vrátíte v deníku změn.

shopzi_save_shipping_method: parametry

• methodId (text; nepovinný): ID existující metody dopravy. Vynechte pro založení nové metody.
• fields (objekt; povinný): Pole ke změně. Vynechané pole zůstane beze změny.
• fields.name (text; nepovinný): Název, který zákazník uvidí v pokladně, například „Zásilkovna na výdejní místo“.
• fields.carrierCode (text; nepovinný): Kód dopravce. Použitelné jsou jen ti s funkčním napojením: personal, packeta, ppl, gls. personal = vlastní doprava nebo osobní odběr.
• fields.fulfillmentType (jedna z hodnot shipping, pickup_point a personal_pickup; nepovinný): shipping = na adresu, pickup_point = na výdejní místo, personal_pickup = osobní odběr v prodejně. Výběr výdejního místa se z tohoto typu odvozuje sám.
• fields.priceMinor (celé číslo aspoň 0; nepovinný): Základní cena dopravy v haléřích: 9900 = 99 Kč.
• fields.vatRate (jedna z hodnot 21, 12 a 0; nepovinný): Sazba DPH v celých procentech: 21, 12 nebo 0.
• fields.freeShippingThresholdMinor (celé číslo aspoň 0 nebo null; nepovinný): Od jaké hodnoty košíku je doprava zdarma, v haléřích. null = nikdy zdarma.
• fields.codAllowed (true nebo false; nepovinný): true = u této dopravy jde zaplatit dobírkou.
• fields.codMaxAmountMinor (celé číslo aspoň 0 nebo null; nepovinný): Nejvyšší dobírka, kterou dopravce přijme, v haléřích. null = bez limitu.
• fields.postcodePrefixes (pole, položka: text se vzorem ^\d{1,5}$, nejvýš 100 položek; nepovinný): Rozvoz jen na tato PSČ: začátky PSČ, například ["1", "252"]. Prázdné pole = všude.
• fields.isActive (true nebo false; nepovinný): false = metoda se v pokladně nenabízí.
• fields.displayOrder (celé číslo aspoň 0; nepovinný): Pořadí v pokladně, nižší číslo je výš.
• fields.maxWeightGrams (celé číslo aspoň 0 nebo null; nepovinný): Nejvyšší hmotnost zásilky v GRAMECH (Zásilkovna 15 000). null = bez limitu.
• fields.maxLengthMm (celé číslo aspoň 0 nebo null; nepovinný): Nejvyšší délka v MILIMETRECH (pevná schránka, Z-BOX).
• fields.maxWidthMm (celé číslo aspoň 0 nebo null; nepovinný)
• fields.maxHeightMm (celé číslo aspoň 0 nebo null; nepovinný)
• fields.maxLongestSideMm (celé číslo aspoň 0 nebo null; nepovinný): Nejdelší strana zásilky v milimetrech (Zásilkovna 1200 = 120 cm).
• fields.maxDimensionSumMm (celé číslo aspoň 0 nebo null; nepovinný): Součet tří stran v milimetrech (Zásilkovna 1500 = 150 cm).
• fields.weightBands (pole objektů, nejvýš 50 položek; nepovinný): Váhová pásma. CELÁ SADA: nahradí stávající, [] smaže, vynechané nechá. Nad posledním platí priceMinor.
• fields.weightBands[].maxWeightGrams (celé číslo aspoň 1; povinný): Horní mez v GRAMECH, včetně.
• fields.weightBands[].priceMinor (celé číslo aspoň 0; povinný): V haléřích.
• fields.weightBands[].maxLongestSideMm (celé číslo aspoň 1 nebo null; nepovinný)
• fields.weightBands[].maxDimensionSumMm (celé číslo aspoň 1 nebo null; nepovinný): Součet tří stran.
• idempotencyKey (text, 1 až 200 znaků; nepovinný): Klíč idempotence. Stejný klíč = stejný zápis: opakované volání vrátí původní výsledek a NEZAPÍŠE podruhé. Použijte vlastní náhodný řetězec pro každou zamýšlenou změnu; při opakování po chybě sítě pošlete tentýž.

shopzi_update_settings

Změní vybraná pole v jedné sekci nastavení (resource), včetně průvodce prvním spuštěním (onboarding). Sekce nastavení obchodu z terminálu nastaví firmu podle IČO z registru ARES, kontakt, právní dokumenty ze šablony a doménu (údaje se posílají v poli setup), podají žádost o Comgate, spustí obchod a zavřou ho závěsem (site_gate: Připravujeme, Údržba, Čekací listina; otevírá jen spuštění) a založí nebo upraví přesměrování (redirects; vypnout nebo smazat ho jde jen v administraci). Sekce store_build postaví na prázdném obchodě celý obchod z popisu sortimentu (kategorie, produkty s fotkami, vzhled, domovskou stránku) za kredity obchodu, s odhadem ceny předem.

• Oprávnění: settings:write, u klíče „Nastavení obchodu (zápis)“.
• Druh: zápis, který umí přepsat nebo smazat existující data (destructiveHint).
• Potvrzení přes MCP: ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí approval_required. Na stránce schválení rozhoduje vlastník nebo manažer obchodu.
• Kredity a platba kartou: ne.
• Deník změn: výsledek nese change_id. ID záznamu v deníku. Předejte ho do shopzi_undo_change.
• Věta o důsledku, kterou člověk uvidí v potvrzení: podle resource, viz seznam níž.

shopzi_update_settings: oblasti

• store (Obecné nastavení)

• seo (SEO)

• notifications (Notifikace)

• products (Produkty)

• reviews (Recenze)

• inventory (Sklad)

• privacy (Soukromí)

• ai (AI)

• wholesale (Velkoobchod)

• hours (Pracovní doba)

• onboarding (Průvodce prvním spuštěním)

• company (Firma a fakturační údaje)

  • Věta o důsledku v potvrzení:

    Fakturační údaje firmy se přepíšou podle ARES a objeví se na nových dokladech. Vrátit jde deníkem změn.

• contact (Kontakt obchodu)

  • Věta o důsledku v potvrzení:

    Změní se kontaktní e-mail nebo telefon obchodu, na který chodí upozornění a který je na dokladech. Původní adresa i vlastníci dostanou e-mail o změně. Vrátit jde deníkem změn.

• legal (Právní dokumenty)

  • Věta o důsledku v potvrzení:

    Vybrané právní dokumenty se přepíšou šablonou s údaji firmy a dosavadní text se nahradí. Vrátit jde deníkem změn.

• domain (Vlastní doména)

  • Věta o důsledku v potvrzení:

    Doména se připojí k obchodu u poskytovatele hostingu a po ověření se na ni obchod přestěhuje (hlavní adresa, přesměrování ze subdomény). Vrátit to nástrojem nejde, jen ručně v Nastavení → Doména. Vlastník dostane e-mail.

• comgate_request (Žádost o Comgate)

  • Věta o důsledku v potvrzení:

    Správci platformy odejde žádost o aktivaci Comgate s údaji firmy z ARES. Vzít zpátky ji nejde. Vlastník dostane e-mail.

• launch (Spuštění obchodu)

  • Věta o důsledku v potvrzení:

    Obchod se zveřejní: sundá se závěs a zákazníci ho uvidí a mohou nakupovat. Ukázkové produkty, na které nikdo nesáhl, se přesunou do konceptu. Vrátit to nejde, zavřít obchod jde znovu v Nastavení → Obecné. Vlastník dostane e-mail.

• site_gate (Závěs obchodu)

  • Věta o důsledku v potvrzení:

    Obchod se zavře závěsem: návštěvníci místo něj uvidí úvodní obrazovku (nebo stránku před spuštěním) a nakoupit nemohou. Vrátit to deníkem nejde, otevřít ho jde jen spuštěním nebo v Nastavení → Obecné. Vlastník dostane e-mail.

• store_build (Stavba celého obchodu)

• redirects (Přesměrování)

  • Věta o důsledku v potvrzení:

    Stará adresa obchodu začne návštěvníky i vyhledávače posílat jinam, a to hned. Vrátit jde deníkem změn; smazat přesměrování jde jen v administraci.

Hodnota bez odrážky Věta o důsledku v potvrzení žádnou takovou větu nemá.

shopzi_update_settings: parametry resource až idempotencyKey

• resource (jedna z hodnot store, seo, notifications, products, reviews, inventory, privacy, ai, wholesale, hours, onboarding, company, contact, legal, domain, comgate_request, launch, site_gate, store_build a redirects; povinný): Která sekce nastavení. Pole musí patřit do ní.
• fields (objekt, schéma připouští i další klíče; nepovinný): Pole ke změně. Vynechané pole zůstane beze změny. Pro všechny sekce KROMĚ hours.
• hours (objekt; nepovinný): Rozvrh ke změně. JEN pro sekci hours.
• hours.scope (physical; povinný): Který rozvrh: physical, tedy provozní doba pobočky, kterou obchod zobrazuje v kontaktech. Jiný rozvrh obchod nemá: objednávky přijímá nepřetržitě a na čas je zastaví jen přepínač Online objednávky.
• hours.days (pole objektů, 1 až 7 položek; povinný): Dny, které se mají změnit. Stačí ty, o které jde: neuvedený den zůstane beze změny. Otevřený den musí mít vyplněné open i close; zavřený se posílá jako closed: true.
• hours.days[].day (celé číslo od 0 do 6; povinný): Den v týdnu: 0 = neděle, 1 = pondělí, 2 = úterý, 3 = středa, 4 = čtvrtek, 5 = pátek, 6 = sobota.
• hours.days[].open (text nebo null; povinný): Čas otevření ve tvaru HH:MM.
• hours.days[].close (text nebo null; povinný): Čas zavření ve tvaru HH:MM.
• hours.days[].closed (true nebo false; povinný): true = v tento den je zavřeno.
• onboarding (objekt; nepovinný): JEN pro sekci onboarding: co se stalo s krokem průvodce. Obchod se spouští sekcí launch.
• onboarding.action (jedna z hodnot done, skip, postpone a resume; povinný): done = krok je hotový; skip = krok se přeskakuje; postpone = průvodce se odloží („dokončím později“, přestane vás do sebe přesměrovávat); resume = vrátit se k němu. Obchod se spouští sekcí launch, ne tady.
• onboarding.step (jedna z hodnot vitejte, puvod, obor, firma, kontakt, vzhled, doprava, platby, emaily, pravni, katalog, domena a spusteni; nepovinný): Jen u done a skip: který krok. Povinný krok (firma, platby, právní dokumenty) jde odškrtnout jen tehdy, když ho potvrzují data (IČO v ARES, fungující platba, uložené podmínky a lhůta); přeskočit ho jde. Informační kroky (vítejte, spuštění) se neodškrtávají.
• setup (objekt; nepovinný): JEN pro sekce company, contact, legal, domain, site_gate, store_build a redirects. comgate_request a launch nepotřebují nic.
• setup.ico (text; nepovinný): company: IČO (8 číslic). Název, adresu a DIČ doplní ARES; plátcovství DPH se nemění (open_task vat_payer).
• setup.email (text; nepovinný): contact: kontaktní e-mail obchodu.
• setup.phone (text; nepovinný): contact: kontaktní telefon.
• setup.documents (pole, položka: jedna z hodnot terms, gdpr, refund, withdrawal, delivery a cookies; nepovinný): legal: dokumenty vložené ze šablony s údaji firmy.
• setup.withdrawal_days (celé číslo; nepovinný): legal: lhůta pro odstoupení od smlouvy ve dnech, aspoň 14.
• setup.action (jedna z hodnot connect a verify; nepovinný): domain: connect = připojit, verify = ověřit DNS.
• setup.domain (text; nepovinný): domain: např. mujobchod.cz.
• setup.store_description (text, nejvýš 1500 znaků; nepovinný): store_build: co obchod prodává a komu, větami obchodníka. Z toho vzniknou kategorie, produkty, texty i vzhled.
• setup.store_product_count (celé číslo od 1 do 20; nepovinný): store_build: kolik produktů založit, 1 až 20. Výchozí 8.
• setup.store_images (true nebo false; nepovinný): store_build: vyfotit produkty a kategorie AI (výchozí ano). Bez fotek je stavba levnější.
• setup.redirect_id (text; nepovinný): redirects: ID existujícího (shopzi_get_settings sekce redirects) = úprava, bez něj nové.
• setup.source_path (text; nepovinný): redirects: stará adresa, např. /stary-produkt. Jen u nového.
• setup.destination_path (text; nepovinný): redirects: cíl, relativní cesta.
• setup.redirect_type (jedna z hodnot permanent a temporary; nepovinný): redirects: permanent (301, výchozí) nebo temporary (302).
• setup.redirect_active (true; nepovinný): redirects: true zapne vypnuté. Vypnout jde jen v administraci (adresa by skončila na 404).
• setup.gate_mode (jedna z hodnot coming_soon, under_construction a waitlist; nepovinný): site_gate: coming_soon = Připravujeme, under_construction = Údržba, waitlist = Brzy otevíráme s formulářem čekací listiny. Otevřít obchod jde jen sekcí launch.
• idempotencyKey (text, 1 až 200 znaků; nepovinný): Klíč idempotence. Stejný klíč = stejný zápis: opakované volání vrátí původní výsledek a NEZAPÍŠE podruhé. Použijte vlastní náhodný řetězec pro každou zamýšlenou změnu; při opakování po chybě sítě pošlete tentýž.

shopzi_update_settings: fields pro sekci store

• fields.site_name (text, 1 až 120 znaků; nepovinný): Název obchodu, jak se zobrazuje v titulcích a e-mailech. (sekce store)
• fields.overlay_message (text, nejvýš 300 znaků nebo null; nepovinný): Věta, kterou obchod ukáže, když má obchodník pozastavené objednávky, například „Máme dovolenou do 5. 8.“. Objednávky tím NEZAPÍNÁTE ani NEVYPÍNÁTE, jen měníte text. Prázdné pole zobrazí výchozí větu. (sekce store)
• fields.coming_soon_message (text, nejvýš 500 znaků nebo null; nepovinný): Text závěsu „Připravujeme“, pokud je zapnutý. Zapnutí ani vypnutí závěsu tímhle neřídíte. (sekce store)
• fields.under_construction_message (text, nejvýš 500 znaků nebo null; nepovinný): Text závěsu „Údržba“, pokud je zapnutý. Zapnutí ani vypnutí závěsu tímhle neřídíte. (sekce store)
• fields.waitlist_message (text, nejvýš 500 znaků nebo null; nepovinný): Text čekací listiny, pokud je zapnutá. Zapnutí ani vypnutí tímhle neřídíte. (sekce store)
• fields.waitlist_success_message (text, nejvýš 500 znaků nebo null; nepovinný): Poděkování, které návštěvník uvidí po přihlášení do čekací listiny. (sekce store)
• fields.waitlist_branding_enabled (true nebo false; nepovinný): Čekací listina nese logo a jméno obchodu místo neutrální obrazovky. Týká se JEN čekací listiny; závěsy „Připravujeme“ a „Údržba“ zůstávají neutrální vždy. (sekce store)
• fields.newsletter_confirm_target (text, nejvýš 60 znaků nebo null; nepovinný): Kam vede proklik z potvrzovacího e-mailu odběru: thanks = stránka s poděkováním (výchozí), builtin = vestavěná potvrzovací obrazovka, page:<ID stránky> = vlastní stránka ze shopzi_list_content (resource=pages). Za závěsem vede proklik vždy na stránku s poděkováním. Neplatná hodnota se čte jako thanks. (sekce store)

shopzi_update_settings: fields pro sekci seo

• fields.seo_title_template (text, nejvýš 200 znaků nebo null; nepovinný): Šablona SEO titulku. Proměnné: %%title%% %%sitename%% %%sep%% %%page%% %%currentyear%%. (sekce seo)
• fields.seo_metadesc_template (text, nejvýš 300 znaků nebo null; nepovinný): Šablona meta popisku. Proměnné: %%excerpt%% %%title%% %%sitename%%. (sekce seo)
• fields.seo_separator (text, nejvýš 8 znaků nebo null; nepovinný): Oddělovač v titulku, například „–“ nebo „|“. (sekce seo)
• fields.home_meta_title (text, nejvýš 200 znaků nebo null; nepovinný): SEO titulek domovské stránky. (sekce seo)
• fields.home_meta_description (text, nejvýš 400 znaků nebo null; nepovinný): SEO popisek domovské stránky. (sekce seo)
• fields.og_site_name (text, nejvýš 120 znaků nebo null; nepovinný): Název webu pro sdílení na sociálních sítích (og:site_name). (sekce seo)
• fields.meta_title (text, nejvýš 200 znaků nebo null; nepovinný): Záchytný SEO titulek pro stránky, které nemají vlastní ani ho neskládá šablona. Prázdné pole použije název obchodu. (sekce seo)
• fields.meta_description (text, nejvýš 400 znaků nebo null; nepovinný): Záchytný SEO popisek pro stránky, které nemají vlastní ani ho neskládá šablona. (sekce seo)
• fields.menu_meta_title (text, nejvýš 200 znaků nebo null; nepovinný): SEO titulek stránky s výpisem produktů (/produkty). (sekce seo)
• fields.menu_meta_description (text, nejvýš 400 znaků nebo null; nepovinný): SEO popisek stránky s výpisem produktů (/produkty). (sekce seo)
• fields.menu_hero_title (text, nejvýš 120 znaků nebo null; nepovinný): Nadpis nad výpisem produktů. Prázdné pole zobrazí „Produkty“. (sekce seo)
• fields.menu_hero_subtitle (text, nejvýš 300 znaků nebo null; nepovinný): Podnadpis nad výpisem produktů. (sekce seo)
• fields.contact_meta_title (text, nejvýš 200 znaků nebo null; nepovinný): SEO titulek stránky Kontakt. (sekce seo)
• fields.contact_meta_description (text, nejvýš 400 znaků nebo null; nepovinný): SEO popisek stránky Kontakt. (sekce seo)
• fields.og_image_url (text, nejvýš 500 znaků; nepovinný): Obrázek obchodu pro sdílení na sociálních sítích (og:image). Použije se všude, kde stránka nemá vlastní. Adresa musí být z knihovny médií tohoto obchodu, ve tvaru /media/… (vezměte ji z nástroje na média, nevymýšlejte ji). Prázdná hodnota obrázek odebere. (sekce seo)
• fields.home_og_image_url (text, nejvýš 500 znaků; nepovinný): Obrázek domovské stránky pro sdílení na sociálních sítích. Adresa musí být z knihovny médií tohoto obchodu, ve tvaru /media/… (vezměte ji z nástroje na média, nevymýšlejte ji). Prázdná hodnota obrázek odebere. (sekce seo)
• fields.menu_og_image_url (text, nejvýš 500 znaků; nepovinný): Obrázek stránky s výpisem produktů (/produkty) pro sdílení na sociálních sítích. Adresa musí být z knihovny médií tohoto obchodu, ve tvaru /media/… (vezměte ji z nástroje na média, nevymýšlejte ji). Prázdná hodnota obrázek odebere. (sekce seo)
• fields.ai_crawlers_training_allowed (true nebo false; nepovinný): Smí roboti sbírat texty a fotky obchodu pro TRÉNOVÁNÍ modelů AI (GPTBot, ClaudeBot, Google-Extended a další). Výchozí stav je zakázáno. Pořadí ve vyhledávačích to neovlivňuje. (sekce seo)
• fields.ai_crawlers_search_allowed (true nebo false; nepovinný): Smí AI vyhledávače stahovat obchod ve chvíli, kdy se jich někdo ptá (ChatGPT-User, Claude-User, PerplexityBot). Výchozí stav je povoleno; zakázáním se obchod přestane objevovat v odpovědích AI vyhledávačů. (sekce seo)
• fields.ai_crawler_gptbot (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota GPTBot (Trénování modelů OpenAI). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_claudebot (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota ClaudeBot (Trénování modelů Anthropic). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_google_extended (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota Google-Extended (Trénování AI Google (neovlivňuje pořadí ve vyhledávání)). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_applebot_extended (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota Applebot-Extended (Trénování Apple Intelligence). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_ccbot (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota CCBot (Common Crawl (datasety pro AI)). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_amazonbot (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota Amazonbot (Amazon Alexa a AI). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_facebookbot (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota FacebookBot (AI společnosti Meta). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_bytespider (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota Bytespider (AI ByteDance a TikTok). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_chatgpt_user (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota ChatGPT-User (Prohlížení webu v ChatGPT). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_claude_user (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota Claude-User (Prohlížení webu v Claude). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.ai_crawler_perplexitybot (jedna z hodnot default, allow a disallow; nepovinný): Výjimka pro robota PerplexityBot (Vyhledávač Perplexity AI). default = řídit se hlavním přepínačem skupiny, allow = pustit, disallow = zakázat. (sekce seo)
• fields.llms_txt_enabled (true nebo false; nepovinný): Vydávat soubor /llms.txt, tedy strojově čitelný rozcestník obchodu pro AI agenty. Výchozí stav je zapnuto. (sekce seo)
• fields.llms_txt_description (text, nejvýš 500 znaků nebo null; nepovinný): Popis obchodu v souboru /llms.txt, jednou až dvěma větami. Prázdné pole použije SEO popisek obchodu. (sekce seo)

shopzi_update_settings: fields pro sekci notifications

• fields.notify_new_order (true nebo false; nepovinný): E-mail obchodníkovi o nové objednávce. (sekce notifications)
• fields.notify_return_request (true nebo false; nepovinný): E-mail obchodníkovi o žádosti o vrácení nebo reklamaci. (sekce notifications)
• fields.notify_b2b_request (true nebo false; nepovinný): E-mail obchodníkovi o žádosti o velkoobchodní účet. (sekce notifications)
• fields.notify_quotation_request (true nebo false; nepovinný): E-mail obchodníkovi o nové poptávce. (sekce notifications)
• fields.notify_contact_form (true nebo false; nepovinný): E-mail obchodníkovi o zprávě z kontaktního formuláře. (sekce notifications)
• fields.inventory_low_stock_email_alert (true nebo false; nepovinný): E-mail obchodníkovi o docházejících zásobách. (sekce notifications)
• fields.inapp_new_order (true nebo false; nepovinný): Zvoneček v adminu: nová objednávka. (sekce notifications)
• fields.inapp_payment_events (true nebo false; nepovinný): Zvoneček v adminu: platební události. (sekce notifications)
• fields.inapp_order_status_change (true nebo false; nepovinný): Zvoneček v adminu: změna stavu objednávky. (sekce notifications)
• fields.inventory_low_stock_inapp_alert (true nebo false; nepovinný): Zvoneček v adminu: docházející zásoby. (sekce notifications)
• fields.inapp_contact_form (true nebo false; nepovinný): Zvoneček v adminu: zpráva z kontaktního formuláře. (sekce notifications)
• fields.inapp_gdpr_deletion (true nebo false; nepovinný): Zvoneček v adminu: žádost o výmaz údajů. (sekce notifications)
• fields.inapp_return_request (true nebo false; nepovinný): Zvoneček v adminu: žádost o vrácení. (sekce notifications)
• fields.inapp_sound_enabled (true nebo false; nepovinný): Přehrávat zvuk u upozornění v adminu. (sekce notifications)
• fields.inapp_sound_volume (celé číslo od 0 do 100; nepovinný): Hlasitost upozornění v adminu, 0 až 100 (výchozí 60). (sekce notifications)
• fields.inapp_sound_default (jedna z hodnot chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Výchozí zvuk upozornění v adminu. Použije se všude, kde skupina nemá vlastní. (sekce notifications)
• fields.inapp_sound_orders (jedna z hodnot prázdný text, chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Zvuk pro skupinu oznámení „Objednávky“. "" = použít výchozí zvuk, none = mlčet. (sekce notifications)
• fields.inapp_sound_messages (jedna z hodnot prázdný text, chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Zvuk pro skupinu oznámení „Zprávy“. "" = použít výchozí zvuk, none = mlčet. (sekce notifications)
• fields.inapp_sound_gdpr (jedna z hodnot prázdný text, chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Zvuk pro skupinu oznámení „GDPR“. "" = použít výchozí zvuk, none = mlčet. (sekce notifications)
• fields.inapp_sound_inventory (jedna z hodnot prázdný text, chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Zvuk pro skupinu oznámení „Sklad“. "" = použít výchozí zvuk, none = mlčet. (sekce notifications)
• fields.inapp_sound_customers (jedna z hodnot prázdný text, chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Zvuk pro skupinu oznámení „Zákazníci“. "" = použít výchozí zvuk, none = mlčet. (sekce notifications)
• fields.inapp_sound_system (jedna z hodnot prázdný text, chime, ding, pop, marimba, bell, blip, knock, alert, swoosh a none; nepovinný): Zvuk pro skupinu oznámení „Systém“. "" = použít výchozí zvuk, none = mlčet. (sekce notifications)

shopzi_update_settings: fields pro sekce products, reviews, inventory, privacy a ai

• fields.catalog_mode_note (text, nejvýš 120 znaků nebo null; nepovinný): Text, který se v katalogovém režimu zobrazí místo tlačítka „Do košíku“, například „Neposíláme, pouze osobní odběr“. Prázdné pole zobrazí výchozí větu. (sekce products)
• fields.pdp_assurance_badges (pole, položka: jedna z hodnot free_shipping, fast_delivery, returns_14, secure_payment, fast_dispatch, czech_store, warranty_24, support a in_stock, 2 až 4 položky; nepovinný): Důvěryhodnostní odznaky pod nákupním boxem na detailu produktu: vyberte 2 až 4 z nabídky. Odznak free_shipping bere částku z pole free_delivery_threshold; bez ní se ukáže jen v obchodě, který má dopravu zdarma pro každou objednávku, jinak z detailu zmizí. (sekce products)
• fields.free_delivery_threshold (celé číslo od 0 do 100000000; nepovinný): Hranice dopravy zdarma, kterou obchod INZERUJE u produktu, v celých korunách (2000 = „Doprava zdarma od 2 000 Kč“). 0 částku sundá: odznak „Doprava zdarma“ pak zůstane jen tehdy, když má obchod aktivní dopravu (ne osobní odběr), která je zdarma pro každou objednávku, jinak se neukáže. POZOR: je to jen text u produktu, ne cena v pokladně. Skutečnou hranici má každý způsob dopravy zvlášť (pole freeShippingThresholdMinor v shopzi_save_shipping_method, v haléřích); když se čísla rozejdou, obchod slibuje u produktu něco, co pokladna neudělá, tak si tu skutečnou napřed přečtěte přes shopzi_get_settings s resource shipping. (sekce products)
• fields.pdp_description_heading_show (true nebo false; nepovinný): Nad popisem produktu se zobrazuje nadpis (výchozí „Popis“). Jednotlivý produkt ho může přebít vlastním textem nebo skrýt. (sekce products)
• fields.pdp_description_heading (text, nejvýš 60 znaků nebo null; nepovinný): Text nadpisu nad popisem produktu, například „O produktu“. Prázdné pole zobrazí „Popis“. (sekce products)
• fields.pdp_custom_params_show (true nebo false; nepovinný): Vlastní parametry produktu (Atributy → vlastní parametry) se ukazují v tabulce Parametry na detailu produktu. (sekce products)
• fields.archive_layout (jedna z hodnot grid a list; nepovinný): Výchozí zobrazení výpisu produktů: grid (dlaždice) nebo list (seznam). (sekce products)
• fields.archive_view_toggle (true nebo false; nepovinný): Nabídnout návštěvníkovi přepínač mezi dlaždicemi a seznamem. (sekce products)
• fields.archive_image_ratio (jedna z hodnot 1:1 a 3:4; nepovinný): Poměr stran obrázků v dlaždicích výpisu: 1:1 (čtverec) nebo 3:4 (na výšku). (sekce products)
• fields.archive_image_slider (true nebo false; nepovinný): Posuvník obrázků přímo v dlaždici výpisu, pokud má produkt více fotek. (sekce products)
• fields.archive_quick_add (true nebo false; nepovinný): Tlačítko „Do košíku“ přímo v dlaždici výpisu (rychlé přidání). (sekce products)
• fields.archive_per_page (jedna z hodnot 12, 24, 36 a 48; nepovinný): Počet produktů na stránku ve výpisu, jako text: 12, 24, 36 nebo 48. (sekce products)
• fields.archive_content_width (jedna z hodnot boxed a full; nepovinný): Šířka výpisu produktů, kategorií a vyhledávání: boxed (v obsahovém boxu) nebo full (přes celou šířku). (sekce products)
• fields.archive_card_gap (jedna z hodnot none, sm, md a lg; nepovinný): Mezera mezi kartami ve výpisu: none (žádná), sm (malá), md (střední) nebo lg (velká). (sekce products)
• fields.archive_card_size (jedna z hodnot sm, md a lg; nepovinný): Velikost karet ve výpisu (kolik jich stojí v řadě): sm (malé), md (střední) nebo lg (velké, nejvýš tři v řadě). (sekce products)
• fields.archive_mobile_columns (jedna z hodnot 1 a 2; nepovinný): Počet karet vedle sebe ve výpisu na telefonu, jako text: 2 (dvě vedle sebe) nebo 1 (jedna na celou šířku). (sekce products)
• fields.product_compare_enabled (true nebo false; nepovinný): Porovnávání produktů: tlačítko „Porovnat“ na kartách, plovoucí lišta a stránka /porovnani. (sekce products)
• fields.reviews_enabled (true nebo false; nepovinný): Modul recenzí: hodnocení a recenze produktů v obchodě. Vypnuto skryje hodnocení i formulář, uložené recenze zůstávají. (sekce reviews)
• fields.review_allow_guests (true nebo false; nepovinný): Recenzi smí napsat i nepřihlášený návštěvník (vyplní jméno a e-mail). (sekce reviews)
• fields.review_allow_photos (true nebo false; nepovinný): Zákazník smí ke své recenzi přiložit fotografie. (sekce reviews)
• fields.review_max_photos (celé číslo od 1 do 10; nepovinný): Kolik fotografií smí zákazník přiložit k jedné recenzi (1 až 10). (sekce reviews)
• fields.review_auto_publish (true nebo false; nepovinný): Automatické schvalování: nová recenze se zveřejní bez ruční kontroly. Doporučený stav je vypnuto. (sekce reviews)
• fields.inventory_show_soldout_overlay (true nebo false; nepovinný): Varianty s nulovou skladovou dostupností se v obchodě označí jako „Vyprodáno“ a NEPŮJDOU koupit. Ve výchozím stavu vypnuto: zapínejte jen tam, kde se skladové množství opravdu udržuje, jinak se zamkne katalog na nevyplněných nulách. (sekce inventory)
• fields.inventory_low_stock_threshold (celé číslo od 0 do 100000; nepovinný): Od jakého množství (a méně) se varianta hlásí jako nízký stav a přijde upozornění. Vlastní práh varianty má přednost. (sekce inventory)
• fields.cookie_consent_banner_text (text, nejvýš 600 znaků nebo null; nepovinný): Text v liště souhlasu s cookies. Krátce a srozumitelně, k čemu obchod cookies používá. (sekce privacy)
• fields.cookie_consent_position (jedna z hodnot bottom a top; nepovinný): Umístění lišty souhlasu: bottom (dole, doporučeno) nebo top (nahoře). (sekce privacy)
• fields.cookie_consent_theme (jedna z hodnot prázdný text, light a dark; nepovinný): Barevné schéma lišty souhlasu. "" = automaticky podle šablony obchodu, light = světlé, dark = tmavé. (sekce privacy)
• fields.ai_brand_tone (jedna z hodnot neutral, premium, playful, minimal, rugged a warm; nepovinný): Tón, kterým má AI psát texty a tvořit vizuály obchodu. (sekce ai)
• fields.ai_brand_audience (text, nejvýš 300 znaků nebo null; nepovinný): Cílová skupina, kterou má AI oslovit, například „domácí kutilové 30 až 50 let“. (sekce ai)
• fields.ai_banned_words (text, nejvýš 500 znaků nebo null; nepovinný): Slova a fráze, které AI nesmí použít, oddělené čárkou. (sekce ai)
• fields.business_type (jedna z hodnot moda, elektronika, kosmetika, domacnost, sport, hracky, sperky, potraviny a jine; nepovinný): Obor obchodu, tedy co prodává. Neřídí nic v obchodě ani v pokladně; je to podklad, ze kterého AI píše texty a tvoří vizuály, takže po změně se liší jen to, co se nově vygeneruje. Vlastní popis oboru („Jiné“) se vyplňuje v průvodci prvním spuštěním. (sekce ai)

shopzi_update_settings: fields pro sekci wholesale

• fields.b2b_landing_intro (text, nejvýš 1000 znaků nebo null; nepovinný): Úvodní odstavec na veřejné stránce /velkoobchod. Prázdné pole zobrazí výchozí text. (sekce wholesale)
• fields.b2b_show_header_link (true nebo false; nepovinný): Odkaz na velkoobchod v hlavičce obchodu. Zobrazí se jen tehdy, když je režim Velkoobchod zapnutý; tímhle přepínačem ho nezapínáte ani nevypínáte. (sekce wholesale)
• fields.b2b_table_view (true nebo false; nepovinný): Velkoobchodní výpis produktů jako tabulka místo dlaždic. Zapnuté se hodí tam, kde partner objednává podle kódů a množství. (sekce wholesale)

shopzi_manage_search

Nastavuje vyhledávání v obchodě: synonyma, přesměrování dotazů, připnuté produkty a popisky, pořadí a zapnutí filtrů. Katalog nepřeindexuje.

• Oprávnění: settings:write, u klíče „Nastavení obchodu (zápis)“.
• Druh: zápis, který umí přepsat nebo smazat existující data (destructiveHint).
• Potvrzení přes MCP: ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí approval_required. Na stránce schválení rozhoduje vlastník nebo manažer obchodu.
• Kredity a platba kartou: ne.
• Deník změn: výsledek nese change_id. ID záznamu v deníku. Předejte ho do shopzi_undo_change.

shopzi_manage_search: oblasti

• synonym (Synonymum)
• redirect (Přesměrování hledání)
• pin (Připnutý výsledek)
• facets (Filtry hledání)

shopzi_manage_search: operace

• save (uložit)
• delete (smazat)

shopzi_manage_search: parametry

• resource (jedna z hodnot synonym, redirect, pin a facets; povinný): Čeho se změna týká. Pole musí patřit k němu.
• operation (jedna z hodnot save a delete; povinný): synonym | redirect | pin: save | delete. facets: jen save (vypíná se isActive: false).
• id (text; nepovinný): ID řádku ze shopzi_get_settings (resource: "search"). Povinné u delete a u fasety; u synonym a redirect ho vynechte, když se má založit nový.
• fields (objekt; nepovinný): Údaje k uložení. Vynechané pole zůstane u úpravy beze změny.
• fields.term (text; nepovinný): Jen synonym: výraz, na který se má reagovat. Ukládá se bez diakritiky a malými písmeny, protože stejně se skládá i to, co hledající napíše.
• fields.expansions (pole, položka: text; nepovinný): Jen synonym: výrazy, na které se term rozšíří. Celý seznam, ne přírůstek: co v něm není, se přestane používat.
• fields.kind (jedna z hodnot two_way a one_way; nepovinný): Jen synonym: two_way = platí oběma směry (výchozí), one_way = term se rozšíří na expansions, ale ne naopak.
• fields.matchQuery (text; nepovinný): redirect: výraz, který přesměrování spustí. pin: výraz, u kterého se má produkt ukázat na začátku.
• fields.matchType (jedna z hodnot exact a contains; nepovinný): Jen redirect: exact = přesně tenhle dotaz (výchozí), contains = dotaz ten výraz obsahuje.
• fields.targetUrl (text; nepovinný): Jen redirect: kam se hledající pošle. RELATIVNÍ cesta v obchodě, například /akce. Cizí doména se odmítne.
• fields.priority (číslo; nepovinný): Jen redirect: když dotazu odpovídá víc pravidel, vyhraje vyšší priorita. Výchozí 0.
• fields.productId (UUID; nepovinný): Jen pin: ID produktu (UUID) ze shopzi_search_products.
• fields.position (číslo; nepovinný): Jen pin: kolikátý ve výsledku (1 až 20). Výchozí 1. Jedno místo u jednoho výrazu drží právě jeden produkt.
• fields.label (text; nepovinný): Jen facets: popisek filtru.
• fields.multiSelect (true nebo false; nepovinný): Jen facets: true = hledající smí zaškrtnout víc hodnot naráz.
• fields.displayOrder (číslo; nepovinný): Jen facets: pořadí filtru v postranním panelu, od nuly.
• fields.isActive (true nebo false; nepovinný): synonym, redirect i facets: false = pravidlo se přestane používat, ale zůstane uložené.
• idempotencyKey (text, 1 až 200 znaků; nepovinný): Klíč idempotence. Stejný klíč = stejný zápis: opakované volání vrátí původní výsledek a NEZAPÍŠE podruhé. Použijte vlastní náhodný řetězec pro každou zamýšlenou změnu; při opakování po chybě sítě pošlete tentýž.