Založte si e-shop zdarma a získejte 10 000 AI kreditů na start. Bez karty, bez závazku.E-shop zdarma + 10 000 AI kreditů na start

Začít zdarma
Přeskočit na obsah
Přihlásit seVyzkoušet zdarma
Obsah dokumentace

MCP: slevy, kampaně a feedy

Nástroje MCP pro slevové kódy, vyskakovací okna, koncepty kampaní, segmenty zákazníků a nastavení feedů: oprávnění, potvrzení, důsledky zápisu a parametry.

Ověřeno 16. 9. 2026Markdown verze

Slevové kódy i s cílením na produkty a kategorie, feedy do srovnávačů zboží, kampaně i s výsledky rozeslání, vyskakovací okna a segmenty zákazníků. Rozeslání kampaně ani vygenerování feedu mezi nástroji není, obojí zůstává v administraci.

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_marketing

Vrátí podle resource slevové kódy i s počtem uplatnění a cílením na produkty a kategorie, stav feedů do srovnávačů zboží, kampaně i s výsledky rozeslání (s entityId jednu kampaň i s tělem e-mailu), vyskakovací okna, nebo segmenty zákazníků.

  • Oprávnění: marketing:read, u klíče „Marketing: slevy, feedy, kampaně, segmenty (čtení)“.
  • Druh: čtení (readOnlyHint).
  • Potvrzení přes MCP: ne.
  • Kredity a platba kartou: ne.

shopzi_list_marketing: oblasti

  • discounts
  • feeds
  • campaigns
  • popups
  • segments

shopzi_list_marketing: parametry

  • resource (jedna z hodnot discounts, feeds, campaigns, popups a segments; povinný)
  • status (jedna z hodnot draft, scheduled, active, paused, expired, archived, sending, sent a canceled; nepovinný): Filtr stavu. discounts: draft | scheduled | active | paused | expired | archived. campaigns: draft | scheduled | sending | sent | paused | canceled.
  • search (text; nepovinný): Hledá v kódu a názvu (discounts), v názvu a předmětu (campaigns) nebo v nadpisu (popups).
  • discountKind (jedna z hodnot percent, fixed a free_shipping; nepovinný): Jen discounts: percent = procentní sleva, fixed = pevná částka, free_shipping = doprava zdarma.
  • entityId (UUID; nepovinný): Jen campaigns: jedna kampaň i s body_html.
  • 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_save_discount_code

Založí nebo upraví slevový kód včetně cílení na vybrané produkty a kategorie (seznam se nahrazuje celý), smaže kód, který nikdo neuplatnil, nebo přepne stav více vyjmenovaným kódům naráz. Nový kód vzniká jako koncept; u uplatněného kódu jde měnit jen název, veřejný popisek, stav a konec platnosti.

  • Oprávnění: marketing:write, u klíče „Marketing: slevové kódy, vyskakovací okna, koncepty kampaní, segmenty, feedy (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í:

    Aktivace kódu ho pustí do košíků zákazníků, pozastavení a archivace ho z nich vezmou. Hromadná změna se provede na VŠECH kódech vypsaných níž, naráz a přesně na nich; vrátit to jde jedním krokem, celou dávku najednou. Smazat lze jen kód, který nikdo neuplatnil.

shopzi_save_discount_code: operace

  • save (uložit)
  • delete (smazat)
  • bulk_status (hromadně přepnout stav)

shopzi_save_discount_code: parametry

  • operation (jedna z hodnot save, delete a bulk_status; nepovinný): save (výchozí) = založit nebo upravit, delete = smazat jeden neuplatněný kód, bulk_status = přepnout stav víc kódům najednou.
  • discountId (text; nepovinný): ID promo akce (promotion_id) existujícího kódu. Vynechte pro založení nového. Povinné u delete.
  • discountIds (pole, položka: text, nejvýš 100 položek; nepovinný): Jen bulk_status: VÝSLOVNÝ seznam ID kódů ze shopzi_list_marketing (resource: discounts), nejvýš sto. Filtr se poslat nedá schválně: schvalovací karta ukazuje počet, který v ní stojí, a provede se přesně tolik kódů.
  • fields (objekt; nepovinný): Pole ke změně. Vynechané pole zůstane beze změny. U delete se nepoužívá, u bulk_status se z něj čte jen status.
  • fields.code (text; nepovinný): Kód, který zákazník zadá v košíku. Jen A-Z, 0-9 a . _ - (2 až 40 znaků). Povinný při zakládání.
  • fields.name (text; nepovinný): Interní název akce. Vidí ho jen obchodník.
  • fields.publicTitle (text nebo null; nepovinný): Popisek slevy v košíku, který uvidí zákazník.
  • fields.status (jedna z hodnot draft, active, paused a archived; nepovinný): draft = koncept, active = platí, paused = pozastaveno, archived = archiv. U bulk_status jsou povolené jen active, paused, archived.
  • fields.kind (jedna z hodnot percent, fixed a free_shipping; nepovinný): percent = procenta, fixed = pevná částka, free_shipping = doprava zdarma.
  • fields.percentBp (celé číslo od 1 do 10000 nebo null; nepovinný): Sleva v setinách procenta: 1000 = 10 %, 10000 = 100 %.
  • fields.amountMinor (celé číslo aspoň 1 nebo null; nepovinný): Pevná sleva v haléřích: 20000 = 200 Kč.
  • fields.maxDiscountMinor (celé číslo aspoň 0 nebo null; nepovinný): Strop procentuální slevy v haléřích. null = bez stropu.
  • fields.minSubtotalMinor (celé číslo aspoň 0 nebo null; nepovinný): Minimální hodnota košíku v haléřích. null = bez limitu.
  • fields.startsAt (text nebo null; nepovinný): Začátek platnosti v ISO tvaru. null = ihned.
  • fields.endsAt (text nebo null; nepovinný): Konec platnosti v ISO tvaru. null = bez konce.
  • fields.totalUsageLimit (celé číslo aspoň 1 nebo null; nepovinný): Maximální počet uplatnění celkem. null = bez limitu.
  • fields.perCustomerLimit (celé číslo aspoň 1 nebo null; nepovinný): Maximální počet uplatnění na zákazníka.
  • fields.usageLimit (celé číslo aspoň 1 nebo null; nepovinný): Maximální počet uplatnění tohoto konkrétního kódu.
  • fields.singleUse (true nebo false; nepovinný): true = kód lze uplatnit jen jednou.
  • fields.firstOrderOnly (true nebo false; nepovinný): true = jen pro první objednávku zákazníka.
  • fields.excludeDiscountedItems (true nebo false; nepovinný): true = neplatí na zboží, které už je zlevněné.
  • fields.targets (pole objektů, nejvýš 200 položek; nepovinný): PLNÁ NÁHRADA cílení: celý výsledný seznam, [] = celý košík. Na uplatněném kódu nejde měnit.
  • fields.targets[].targetType (jedna z hodnot product a category; povinný)
  • fields.targets[].targetId (UUID; povinný): ID produktu nebo kategorie ze shopzi_list_catalog.
  • fields.targets[].mode (jedna z hodnot include a exclude; povinný): include = jen na tyto, exclude = na tyto ne.
  • 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_save_marketing_entity

Založí, upraví nebo smaže vyskakovací okno, koncept kampaně, segment zákazníků a nastavení feedů do srovnávačů. Vyskakovací okno vzniká zhasnuté a rozsvítit ho jde, jen když žádné jiné nesvítí. Rozeslat kampaň tudy nejde a změna feedu se do srovnávače propíše až při jeho nejbližším vygenerování.

  • Oprávnění: marketing:write, u klíče „Marketing: slevové kódy, vyskakovací okna, koncepty kampaní, segmenty, feedy (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í:

    Smazat lze jen KONCEPT kampaně, zhasnuté okno a segment, který nemá navázanou žádnou kampaň; všechno tři se dá vrátit i s obsahem. Nic z toho nikomu nic neodesílá: rozeslat kampaň umí jen člověk v administraci. ZAPNUTÍ FEEDU zveřejní adresu s katalogem obchodu, ze které si ho srovnávač (Heureka, Zboží.cz, Google a další) stahuje; vypnutím se zase zavře. Zařazení kategorií a výjimky u položek se do srovnávače propíšou až při nejbližším vygenerování feedu, tedy při ranní automatické aktualizaci, nebo když v sekci Feedy kliknete na Generovat u kanálu či na Generovat vše. Vygenerovat a zveřejnit feed sám agent neumí.

shopzi_save_marketing_entity: oblasti

  • popup (Vyskakovací okno)
  • campaign (Kampaň)
  • segment (Segment zákazníků)
  • feed_channel (Kanál feedu)
  • feed_category (Zařazení kategorie ve feedu)
  • feed_item (Výjimka položky ve feedu)

shopzi_save_marketing_entity: operace

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

shopzi_save_marketing_entity: parametry

  • resource (jedna z hodnot popup, campaign, segment, feed_channel, feed_category a feed_item; povinný): Která položka. Pole musí patřit k ní.
  • operation (jedna z hodnot save a delete; nepovinný): save (výchozí) = založit nebo upravit, delete = smazat. Mazání chce entityId a žádná fields. U feed_category a feed_item znamená delete zrušení zařazení nebo výjimky; feed_channel se nemaže, jen vypíná (enabled: false).
  • channel (jedna z hodnot heureka, zbozi, google_merchant, glami, favi, biano, meta_catalog a microsoft_merchant; nepovinný): Jen feedy: který srovnávač. Povinné u feed_channel, feed_category i feed_item.
  • entityId (UUID; nepovinný): ID existující položky (UUID) ze shopzi_list_marketing. Vynechte pro založení nové. U feed_item je to ID VARIANTY produktu (ze shopzi_get_product).
  • fields (objekt; nepovinný): Pole ke změně. Vynechané pole zůstane beze změny. U operation: delete se nepoužívá.
  • fields.title (text; nepovinný): Jen popup: nadpis okna, nejvýše 60 znaků. Povinný při zakládání.
  • fields.content (text nebo null; nepovinný): Jen popup: text okna (HTML), nejvýše 1000 znaků prostého textu.
  • fields.template (jedna z hodnot announcement, promo, welcome, newsletter a discount_code; nepovinný): Jen popup: vzhled okna. discount_code navíc vyžaduje discountCodeId.
  • fields.ctaText (text nebo null; nepovinný): Jen popup: text tlačítka, nejvýše 50 znaků.
  • fields.imageUrl (text nebo null; nepovinný): Jen popup: adresa obrázku v okně.
  • fields.delaySeconds (celé číslo od 0 do 120; nepovinný): Jen popup: za kolik sekund se okno ukáže (0 až 120).
  • fields.isDismissible (true nebo false; nepovinný): Jen popup: lze okno zavřít křížkem.
  • fields.showFrequency (jedna z hodnot once_session, once_ever a every_visit; nepovinný): Jen popup: once_session = jednou za návštěvu, once_ever = jednou navždy, every_visit = pokaždé.
  • fields.discountCodeId (UUID nebo null; nepovinný): Jen popup: ID slevového kódu (UUID), který okno nabízí. Povinné u šablony discount_code.
  • fields.isActive (true nebo false; nepovinný): Jen popup: false zhasne, true rozsvítí existující okno, jen když žádné jiné nesvítí.
  • fields.subject (text nebo null; nepovinný): Jen campaign: předmět e-mailu.
  • fields.preheader (text nebo null; nepovinný): Jen campaign: úvodní řádek, který se ukáže v seznamu zpráv vedle předmětu.
  • fields.bodyHtml (text nebo null; nepovinný): Jen campaign: tělo e-mailu (HTML).
  • fields.ctaLabel (text nebo null; nepovinný): Jen campaign: text tlačítka v e-mailu.
  • fields.couponCode (text nebo null; nepovinný): Jen campaign: slevový kód uvedený v e-mailu. Kód se tím nezakládá, jen se do zprávy vypíše.
  • fields.segmentId (UUID nebo null; nepovinný): Jen campaign: ID segmentu (UUID), kterému je kampaň určená. Neodesílá, jen vybírá publikum.
  • fields.description (text nebo null; nepovinný): Jen segment: k čemu segment je. Vidí ho jen obchodník.
  • fields.criteria (objekt nebo null; nepovinný): Jen segment: pravidlo výběru. all = všechny podmínky zároveň, any = aspoň jedna. Segment bez podmínek nevybere NIKOHO (prázdné pravidlo se schválně nepřekládá na „všichni“). total_spent_minor je v haléřích, within_days/older_than_days berou počet dní.
  • fields.criteria.all (pole objektů, nejvýš 20 položek; nepovinný)
  • fields.criteria.all[].field (jedna z hodnot newsletter_subscribed, sms_marketing_consent, auth_provider, customer_group_id, marketing_tags, orders_count, total_spent_minor, last_order_at, first_order_at, created_at, locale, is_business a b2b_status; povinný)
  • fields.criteria.all[].op (jedna z hodnot eq, neq, gt, gte, lt, lte, contains, has_tag, within_days, older_than_days, is_set a is_not_set; povinný)
  • fields.criteria.all[].value (text nebo číslo nebo true nebo false nebo null; nepovinný)
  • fields.criteria.any (pole objektů, nejvýš 20 položek; nepovinný)
  • fields.criteria.any[].field (jedna z hodnot newsletter_subscribed, sms_marketing_consent, auth_provider, customer_group_id, marketing_tags, orders_count, total_spent_minor, last_order_at, first_order_at, created_at, locale, is_business a b2b_status; povinný)
  • fields.criteria.any[].op (jedna z hodnot eq, neq, gt, gte, lt, lte, contains, has_tag, within_days, older_than_days, is_set a is_not_set; povinný)
  • fields.criteria.any[].value (text nebo číslo nebo true nebo false nebo null; nepovinný)
  • fields.name (text; nepovinný): campaign a segment: název. Vidí ho jen obchodník. Povinný při zakládání.
  • fields.ctaUrl (text nebo null; nepovinný): popup a campaign: adresa tlačítka. U okna buď cesta v obchodě (např. /produkty), nebo odkaz na https://.
  • fields.enabled (true nebo false; nepovinný): Jen feed_channel: zapnout kanál. true ZVEŘEJNÍ adresu s katalogem, ze které si ho srovnávač stahuje; false ji zase zavře a nastavení zůstane zachované.
  • fields.defaultCpcMinor (celé číslo aspoň 0 nebo null; nepovinný): Jen feed_channel: výchozí cena za proklik v HALÉŘÍCH (2 Kč = 200). Čtou ji Heureka a Zboží.cz. null ji zruší.
  • fields.includeOutOfStock (true nebo false; nepovinný): Jen feed_channel: posílat i zboží, které není skladem. false ho z feedu vynechá.
  • fields.categories (pole objektů; nepovinný): Jen feed_category: kategorie k zařazení (i víc najednou). U operation: delete stačí u každé categoryId.
  • fields.categories[].categoryId (UUID; povinný): ID kategorie obchodu ze shopzi_list_catalog (resource categories).
  • fields.categories[].externalCategoryId (text nebo null; nepovinný): Číslo kategorie ve stromu srovnávače. Čte ho Google, Meta a Microsoft; neexistující číslo nástroj odmítne.
  • fields.categories[].externalCategoryPath (text nebo null; nepovinný): Cesta ve stromu srovnávače, například „Heureka.cz | Dům a zahrada | Nábytek“. Čte ji Heureka, Zboží.cz, Glami, Favi i Biano.
  • fields.exclude (true nebo false; nepovinný): Jen feed_item: true položku z feedu vyřadí, false ji tam vrátí.
  • fields.availability (jedna z hodnot in_stock a out_of_stock, nebo null; nepovinný): Jen feed_item: přebije dostupnost hlášenou srovnávači. null vrátí rozhodování skladu.
  • 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ýž.