MCP: zákazníci, recenze a zprávy

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.

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

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

• customers
• groups
• reviews (Recenze)
• messages
• gdpr_requests
• waitlist
• emails

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

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

• 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

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

• 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

• 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ýž.