Průvodce integrací Shopify

Tajo propojuje Shopify s Brevo na dvou místech. Aplikace Tajo pro Shopify mění webhooky Shopify na zápisy do Brevo hned, jak dorazí. Pravidla synchronizace, která sestaví agent a schválí člověk, přesouvají záznamy do Brevo podle plánu. Tato stránka popisuje obojí a pak nástroje Shopify, které Tajo poskytuje přes MCP.

Předpoklady

Než začnete s integrací, ujistěte se, že máte:

• Obchod na Shopify v libovolném tarifu (Basic, Shopify, Advanced nebo Plus)
• Účet Tajo (Tajo je v předběžném přístupu)
• Účet Brevo, cíl synchronizace
• Administrátorský přístup k Vašemu obchodu na Shopify

Krok 1: Připojte svůj obchod Shopify

Tajo je v předběžném přístupu. Aplikace pro Shopify není uvedena v obchodě Shopify App Store a neexistuje žádný odkaz pro samoobslužnou instalaci. Kontaktujte tým, který Vám pomůže s nastavením. Jakmile bude Váš pracovní prostor Tajo připraven:

1. V Tajo otevřete Connections.
2. Zadejte doménu myshopify.com svého obchodu a zvolte Connect Shopify. Shopify zobrazí rozsahy oprávnění, která Tajo požaduje, a po jejich schválení Vás vrátí zpět do Tajo.
3. K čemu každý rozsah slouží a co Tajo zapisuje zpět do Shopify, zjistíte ve Vysvětlení oprávnění Shopify.

Krok 2: Co aplikace Tajo pro Shopify posílá do Brevo

Aplikace ověří každý webhook Shopify, uloží ho, zařadí do fronty a hned zpracuje. Témata zákazníků a produktů nejprve počkají asi čtyři sekundy. Neexistuje žádné dávkové okno. Neúspěšná úloha se opakuje s postupně prodlužovaným odstupem (backoff).

Témata webhooků

Aplikace Tajo pro Shopify odebírá tato témata webhooků Shopify:

Povinné webhooky Shopify k ochraně soukromí (žádost o data zákazníka, smazání zákazníka, smazání obchodu) jsou také obslouženy. Aplikace neodebírá carts/*. Opuštěné košíky pocházejí z témat checkouts/*.

Co se objeví v Brevo:

Aplikace nepřidává do Vašeho motivu tlačítko „Notify me“. Žádost o upozornění na naskladnění musí přijít z Vašeho obchodu, například z tlačítka, které přidáte.

Stávající data

Při instalaci aplikace naimportuje Vaše stávající zákazníky jako kontakty Brevo. Úplnou historickou synchronizaci spustíte ze stránky synchronizace v aplikaci. V placených tarifech importuje také produkty, kolekce, společnosti a objednávky.

Krok 3: Sestavte pravidlo synchronizace s agentem

Pravidlo synchronizace je deklarativní definice jedné synchronizace: zdrojový prostředek, akce v Brevo, mapování polí a filtr. Nepíšete ho ručně. Popíšete ho, agent ho sestaví a člověk ho schválí.

1. V Tajo otevřete Agents a požádejte Brevo Integration Architect o synchronizaci běžnými slovy. Například: „Pošli zákazníky Shopify, kteří souhlasili s e-mailovým marketingem, do Brevo jako kontakty.“
2. Agent prozkoumá konektor Shopify. Jeho ukázka vrací názvy a typy polí, nikdy hodnoty zákazníků.
3. Navrhne pravidlo s mapováním polí a filtrem, pak ověří mapování polí vůči akci Brevo a provede zkušební běh (dry run) návrhu. Ani jeden krok nečte záznamy zákazníků.
4. Uloží pravidlo jako koncept. Můžete také začít ze šablony v Connections > Syncs and mappings > New sync from template.
5. Request publish approval spustí náhled nad Vaším obchodem. Přečte nejvýše 10 záznamů, do Brevo nic nezapíše a neposune kurzor. Zaznamená pouze počty: načtené záznamy, způsobilé, namapované a odmítnuté filtrem, plus chyby mapování. Pokud náhled selže, žádné schválení nevznikne.
6. Člověk žádost schválí na stránce Approvals s písemným zdůvodněním. Schválení je vázáno na otisk SHA-256 pravidla a vyprší po 30 minutách. Stránka pravidla pak zobrazí Publish approved version.

Úprava publikovaného pravidla ho vrátí do konceptu. Než znovu poběží, projde opět náhledem a schválením.

Skutečné pravidlo

Toto je šablona Shopify customers -> Brevo contacts tak, jak ji Tajo definuje:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

Filtr je kontrola souhlasu. Tajo obě hodnoty odvozuje z email_marketing_consent.state v Shopify nebo ze staršího příznaku accepts_marketing. Pravidlo, které zapisuje kontakty do Brevo, nelze bez něj publikovat. Druhá šablona Shopify, Shopify orders → Brevo orders, zaznamenává v Brevo objednávky zákazníků, kteří při placení souhlasili s marketingem.

Kdy pravidlo běží

• Pravidla synchronizace kontaktů běží ve výchozím nastavení každých 15 minut. Každý běh začíná od kurzoru pravidla.
• Stránka aktivního pravidla má tlačítko Test run (1 batch).
• Aktivní, publikované pravidlo Shopify orders → Brevo orders také běží každých 15 minut. Jeho první plánovaný běh začíná několik minut před tímto okamžikem a neodešle žádné starší objednávky. Každý další běh odešle objednávky aktualizované od předchozího běhu.
• Starší objednávky se do Brevo dostanou jen tehdy, když pravidlo spustíte sami: tlačítkem Test run (1 batch), nebo tak, že o spuštění požádáte agenta Sync Operator.
• Pravidlo pro objednávky běží podle plánu jen s filtrem marketingového souhlasu kupujícího ze šablony. Pravidlo s upraveným filtrem běží jen tehdy, když ho spustíte sami.
• Po pěti po sobě jdoucích neúspěšných bězích se pravidlo samo pozastaví a jeho stránka zobrazí poslední chybu. Odstraňte příčinu a pak pravidlo znovu publikujte.

Každý běh je uveden v historii běhů pravidla s počtem přečtených, zapsaných a neúspěšných záznamů a s dobou trvání.

Co konektor Shopify čte a zapisuje

Pravidla synchronizace zapisují jen do cíle, zde do Brevo. Do Shopify nikdy nezapisují.

Aplikace Tajo pro Shopify požaduje 12 rozsahů oprávnění a do Shopify provádí krátký seznam zápisů, například odhlášení souhlasu a věrnostní štítky. Vysvětlení oprávnění Shopify uvádí každý rozsah a každý zápis i s tím, co ho spouští.

Agenti a hostitelé MCP přistupují k obchodu přes konektor Shopify:

Konektor deklaruje také úpravu zásob. Ta vyžaduje rozsah write_inventory, který aplikace Tajo pro Shopify nepožaduje.

Krok 4: Používejte nástroje Shopify přes MCP

Tajo poskytuje konektor Shopify jako server MCP na adrese https://alto.tajo.io/mcp/connectors/shopify. Přidejte ho do Claude Code:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

Hostitel najde OAuth server Tajo a otevře přihlášení do Tajo. Přístup mají jen účty v předběžném přístupu. Server nabízí 12 nástrojů:

Řešení potíží

• Kontakty se v Brevo nezobrazují: viz chybějící kontakty v Brevo.
• Pravidlo, které neběží nebo se samo pozastavilo: viz data se nesynchronizují.

Další kroky

• Pochopení synchronizace dat, jak se chovají pravidla synchronizace
• Vysvětlení oprávnění Shopify, každý rozsah a každý zápis
• Shopify + Brevo, průvodce integrací
• Kontaktujte tým, který Vám pomůže s nastavením