MCP: předplatné a kredity

Předplatné obchodu u SHOPZI: navýšení tarifu nebo přechod na roční platbu a odkaz na nákup kreditů v administraci. Mimo zkušební období se rozdíl strhne z karty uložené u SHOPZI; ve zkušebním období se nestrhne nic a mění se jen částka, kterou zaplatíte od první platby. Klient, který umí formulář, se na navýšení zeptá přímo u sebe (v terminálu nebo v okně asistenta) a potvrdí ho ten, kdo drží klíč, takže před ukradeným klíčem takové potvrzení nechrání; schválení na stránce v administraci smí dát jen vlastník obchodu s druhým ověřením. Stav tarifu, využití limitů a faktury vrací shopzi_get_settings se sekcí billing.

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_manage_subscription

Navýší tarif nebo přejde z měsíční na roční platbu, nebo vrátí odkaz na nákup kreditů v administraci. Navýšení má dva kroky: volání bez quote vrátí přesnou částku ze Stripe, volání se stejnou quote ji po potvrzení strhne z karty uložené u SHOPZI. Ve zkušebním období se nestrhne nic a mění se jen částka od první platby.

• Oprávnění: billing:write, u klíče „Předplatné: navýšení tarifu a odkaz na nákup kreditů (zápis, placené)“.
• Druh: zápis, který umí přepsat nebo smazat existující data (destructiveHint).
• Potvrzení přes MCP: podle operation, viz seznam níž.
• Kredity a platba kartou: podle operation, viz seznam níž.
• Deník změn: výsledek nese change_id.
• Věta o důsledku, kterou člověk uvidí v potvrzení: podle operation, viz seznam níž.

shopzi_manage_subscription: operace

• upgrade (navýšit tarif)

  • Potvrzení přes MCP:
    • bez quote: ne.
    • s quote: 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 jen vlastník obchodu s druhým ověřením.
  • Kredity a platba kartou:
    • bez quote: ne.
    • s quote: strhne peníze z karty.
  • Věta o důsledku v potvrzení:

    • bez quote: bez věty o důsledku.

    • s quote:

      Navýšení tarifu STRHNE PENÍZE z karty uložené u SHOPZI, přesně částku uvedenou v otázce, a vyšší tarif platí hned. Ve zkušebním období se nestrhne nic: vyšší tarif platí hned a mění se jen částka od první platby, jejíž datum zůstává. Vrátit to nejde: snížit tarif jde jen v administraci, od konce zaplaceného období. Přes asistenta jde tarif změnit nejvýš jednou za 24 hodin a vlastníci obchodu dostanou e-mail.

• credit_pack_link (podat odkaz na nákup kreditů)

  • Potvrzení přes MCP: ne.
  • Kredity a platba kartou: ne.

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

shopzi_manage_subscription: parametry

• operation (jedna z hodnot upgrade a credit_pack_link; povinný): upgrade navýší tarif ve dvou krocích, credit_pack_link vrátí odkaz na nákup kreditů.
• plan (jedna z hodnot start, growth, scale a pro; nepovinný): Jen upgrade: cílový tarif start (Basic) | growth (Standard) | scale (Business) | pro (Enterprise). V závorce je název z ceníku, pod kterým tarif zná obchodník.
• interval (jedna z hodnot monthly a annual; nepovinný): Jen upgrade: cílová perioda platby monthly | annual.
• quote (objekt; nepovinný): Jen druhý krok upgrade: nabídka z prvního kroku beze změny. Bez ní se nic neúčtuje.
• quote.prorationDate (celé číslo; povinný)
• quote.amountDueMinor (celé číslo aspoň 0; povinný)
• quote.recurringMinor (celé číslo aspoň 0; povinný)
• quote.currency (text, přesně 3 znaky; povinný)
• quote.interval (jedna z hodnot monthly a annual; povinný)
• quote.trialEndsAt (celé číslo větší než 0; nepovinný)
• package (text; nepovinný): Jen credit_pack_link: id balíčku ze sekce billing (například ai_1000).
• 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ýž.