# MCP: zákazníci, recenze a zprávy > Nástroje MCP pro zákazníky, cenové skupiny, recenze, zprávy z kontaktního formuláře, žádosti podle GDPR a čekací listinu: oprávnění, potvrzení a parametry. - Sekce: Pro vývojáře - Stránka: https://shopzi.cz/dokumentace/vyvojari/mcp-zakaznici - Ověřeno: 2026-09-16 --- Zákazníci a jejich cenové skupiny, historie e-mailů a SMS, které jim obchod poslal, moderace recenzí, schránka zpráv, žádosti podle GDPR a čekací listina v pořadí zápisu. Čtecí nástroj vrací osobní údaje, proto oprávnění `customers:read` dávejte jen klientům, které je opravdu potřebují. O rozhodnutí o žádosti o velkoobchod dostane zákazník e-mail. 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](/dokumentace/vyvojari/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_list_customers` [#shopzi-list-customers] Vrátí podle `resource` zákazníky (s filtry a řazením jako obrazovka Zákazníci, třeba podle útraty), cenové skupiny, recenze k moderaci, zprávy z kontaktního formuláře, žádosti podle GDPR, čekací listinu ze stránky před spuštěním v pořadí zápisu (`waitlist`, jiný seznam přes `listKey`), nebo historii e-mailů a SMS odeslaných zákazníkům (`emails`, bez těla zprávy). Výsledek obsahuje osobní údaje zákazníků. * **Oprávnění:** `customers:read`, u klíče „Zákazníci, skupiny, recenze, zprávy, historie e-mailů a SMS a žádosti GDPR (čtení)“. * **Druh:** čtení (`readOnlyHint`). * **Potvrzení přes MCP:** ne. * **Kredity a platba kartou:** ne. ### `shopzi_list_customers`: oblasti [#shopzi-list-customers-oblasti] * `customers` * `groups` * `reviews` (Recenze) * `messages` * `gdpr_requests` * `waitlist` * `emails` ## `shopzi_list_customers`: parametry [#shopzi-list-customers-parametry] * `resource` (jedna z hodnot `customers`, `groups`, `reviews`, `messages`, `gdpr_requests`, `waitlist` a `emails`; povinný) * `listKey` (text, 1 až 48 znaků; nepovinný): Jen `waitlist`: klíč seznamu z bloku formuláře. Vynechané = `cekaci-listina`. * `search` (text; nepovinný): Jen `customers`: hledá v e-mailu, jménu a názvu firmy. Jen `messages`: hledá ve jménu, e-mailu a textu zprávy. * `customerStatus` (jedna z hodnot `active`, `suspended` a `deleted`; nepovinný): Jen `customers`: `active` = aktivní, `suspended` = pozastavený nebo deaktivovaný, `deleted` = ke smazání nebo anonymizovaný. * `b2bStatus` (jedna z hodnot `none`, `pending`, `verified` a `rejected`; nepovinný): Jen `customers`: stav žádosti o velkoobchod. `pending` je fronta k rozhodnutí, kterou vyřizuje `shopzi_manage_customer` s `operation: decide_b2b`. * `consent` (jedna z hodnot `subscribed`, `none` a `suppressed`; nepovinný): Jen `customers`: `subscribed` = odběratelé newsletteru, `none` = bez souhlasu, `suppressed` = odhlášení nebo zablokovaní. Rozeslat kampaň nástrojem nelze, to dělá člověk. * `sort` (jedna z hodnot `email`, `name`, `created`, `orders`, `spent`, `last_order` a `consent`; nepovinný): Jen `customers`: spent = útrata, orders = počet objednávek, created = registrace. Vynechané = nejnovější registrace první. * `dir` (jedna z hodnot `asc` a `desc`; nepovinný): Jen `customers`, výchozí `desc`. * `customerId` (UUID; nepovinný): Jen `emails`: ID zákazníka (`resource: customers`). * `orderId` (UUID; nepovinný): Jen `emails`: ID objednávky. * `email` (text, 3 až 320 znaků; nepovinný): Jen `emails`: přesná adresa příjemce; najde i zprávy hostům. * `reviewStatus` (jedna z hodnot `pending`, `published`, `rejected` a `reported`; nepovinný): Jen `reviews`: která fronta moderace. Výchozí `pending`. * `messageStatus` (jedna z hodnot `new`, `read` a `archived`; nepovinný): Jen `messages`: filtr stavu. Vynechané = všechny. * `gdprStatus` (jedna z hodnot `pending`, `processing`, `completed` a `rejected`; nepovinný): Jen `gdpr_requests`: filtr stavu. Vynechané = všechny. * `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet položek na stránku, 1 až 100. Velká stránka se do jedné odpovědi nemusí vejít a nástroj ji pak odmítne, což stojí krok navíc: berte jen tolik položek, kolik na odpověď opravdu potřebujete. * `offset` (celé číslo od 0 do 100000, výchozí `0`; nepovinný): Kolik položek přeskočit. 0 = první stránka. ## `shopzi_moderate_review` [#shopzi-moderate-review] Schválí, zamítne, označí za spam, skryje nebo obnoví recenzi a zveřejní nebo stáhne veřejnou odpověď obchodu pod ní. * **Oprávnění:** `customers:write`, u klíče „Recenze a zákazníci (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í:** > Schválení recenze, která teprve čekala na posouzení, se vrátit NEDÁ: do fronty čekajících ji nevrátí ani „vrátit zpět“, protože do ní recenzi zařazuje jen systém. Zpátky z ní vede skrytí nebo zamítnutí, ne návrat do fronty. Schválená recenze i vaše odpověď jsou VEŘEJNÉ, tedy vidí je každý na stránce produktu, a schválení a zamítnutí přepočítá hvězdičkové hodnocení produktu. Skrytí, zamítnutí, spam a stažení odpovědi se vracejí celé. ## `shopzi_moderate_review`: parametry [#shopzi-moderate-review-parametry] * `reviewId` (UUID; povinný): ID recenze ve tvaru UUID. * `action` (jedna z hodnot `approve`, `reject`, `spam`, `hide`, `reinstate`, `reply` a `unpublish_reply`; povinný): approve = zveřejnit, reject = zamítnout, spam = označit za spam, hide = stáhnout, reinstate = vrátit skrytou zpět, reply = zveřejnit nebo přepsat odpověď obchodu (text v poli `reply`), unpublish\_reply = stáhnout odpověď obchodu. Poslední dvě nechávají stav recenze i její hvězdičky beze změny. * `reply` (text nebo `null`; nepovinný): Veřejná odpověď obchodu pod recenzí. Vynechané pole = odpověď se nemění, prázdné = stávající odpověď se stáhne. * `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_manage_customer` [#shopzi-manage-customer] Založí kartu zákazníka, rozhodne o čekající žádosti o velkoobchod, přepíše marketingové štítky zákazníka, nebo archivuje přečtenou zprávu. O rozhodnutí o velkoobchodu dostane zákazník e-mail stejně jako z administrace a ten vzít zpět nejde; ostatní operace nic neodesílají. Založení karty vrátit nejde. * **Oprávnění:** `customers:write`, u klíče „Recenze a zákazníci (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 `operation`, viz seznam níž. ### `shopzi_manage_customer`: operace [#shopzi-manage-customer-operace] * `create` (založit) * Věta o důsledku v potvrzení: > Založí se nová karta zákazníka s uvedenými údaji. Zákazníkovi nic neodejde a heslo se nezakládá. Vrátit to nejde: kartu zruší jen výmaz podle GDPR, který schvaluje člověk v administraci. * `decide_b2b` (rozhodnout o žádosti o velkoobchod) * Věta o důsledku v potvrzení: > Rozhodnutí o žádosti o velkoobchod platí hned: schválený zákazník uvidí ceny své cenové skupiny, zamítnutý zůstane u běžných cen. E-mail mu o tom neodejde, dejte mu vědět sami. Vrátit to jde. * `set_tags` (přepsat marketingové štítky) * Věta o důsledku v potvrzení: > Štítky se PŘEPISUJÍ celé: co v seznamu níž není, zákazníkovi zmizí. Rozhodují zároveň o tom, kdo padne do segmentu, tedy komu by šla budoucí kampaň; odeslat ji ale umí jen člověk v administraci a před odesláním uvidí, kolika lidem to půjde. Vrátit to jde. Archivace zprávy nic zákazníkovi neposílá a nesmaže: jen ji uklidí z fronty. Týká se výhradně zprávy, kterou už někdo přečetl, takže počet nepřečtených zpráv se tím nezmění, a vrátit ji z archivu jde jedním krokem. * `archive_message` (archivovat vyřízenou zprávu) * Věta o důsledku v potvrzení: > Štítky se PŘEPISUJÍ celé: co v seznamu níž není, zákazníkovi zmizí. Rozhodují zároveň o tom, kdo padne do segmentu, tedy komu by šla budoucí kampaň; odeslat ji ale umí jen člověk v administraci a před odesláním uvidí, kolika lidem to půjde. Vrátit to jde. Archivace zprávy nic zákazníkovi neposílá a nesmaže: jen ji uklidí z fronty. Týká se výhradně zprávy, kterou už někdo přečetl, takže počet nepřečtených zpráv se tím nezmění, a vrátit ji z archivu jde jedním krokem. Hodnota bez odrážky Věta o důsledku v potvrzení žádnou takovou větu nemá. ## `shopzi_manage_customer`: parametry [#shopzi-manage-customer-parametry] * `operation` (jedna z hodnot `create`, `decide_b2b`, `set_tags` a `archive_message`; povinný): create = založit kartu zákazníka; decide\_b2b = rozhodnout o žádosti o velkoobchod; set\_tags = přepsat marketingové štítky zákazníka; archive\_message = uklidit z fronty dotazů zprávu, kterou už někdo přečetl a vyřídil. * `customerId` (text; nepovinný): `decide_b2b` a `set_tags`: ID zákazníka ze `shopzi_list_customers` (`resource: customers`). * `messageId` (UUID; nepovinný): Jen `archive_message`: ID zprávy ze `shopzi_list_customers` (`resource: messages`). * `fields` (objekt; nepovinný): Jen `create`: údaje nového zákazníka. * `fields.email` (text; nepovinný): POVINNÝ při zakládání: přihlašovací e-mail zákazníka. Heslo se nezakládá ani neposílá, zákazník si ho nastaví přes „zapomenuté heslo“. * `fields.firstName` (text nebo `null`; nepovinný) * `fields.lastName` (text nebo `null`; nepovinný) * `fields.phone` (text nebo `null`; nepovinný) * `fields.companyName` (text nebo `null`; nepovinný): Vyplněný název firmy nebo IČO označí zákazníka jako firmu. * `fields.ico` (text nebo `null`; nepovinný): IČO firmy. * `fields.dic` (text nebo `null`; nepovinný): DIČ firmy. * `decision` (jedna z hodnot `approve` a `reject`; nepovinný): Jen `decide_b2b`: approve = schválit, reject = zamítnout. * `note` (text nebo `null`; nepovinný): Jen `decide_b2b` + `reject`: důvod zamítnutí. Zůstane na kartě a zákazník ho dostane v e-mailu o zamítnutí. * `customerGroupId` (text; nepovinný): Jen `decide_b2b` + `approve`: cenová skupina ze `shopzi_list_customers` (`resource: groups`). Vynechané pole zařadí firmu do velkoobchodní skupiny obchodu. * `tags` (pole, položka: text, nejvýš 40 znaků, nejvýš 20 položek; nepovinný): Jen `set_tags`: ÚPLNÝ seznam štítků, které má zákazník mít. Zápis je náhrada, ne přidání, takže si současné štítky nejdřív načtěte přes `shopzi_list_customers` (`resource: customers`) a pošlete je zpátky i s tím novým. Prázdný seznam štítky zruší. Štítky se ukládají malými písmeny a bez mezer na krajích, protože je segmenty porovnávají PŘESNĚ. * `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ýž.