Príručka integrácie so Shopify

Tajo prepája Shopify s Brevo na dvoch miestach. Aplikácia Tajo pre Shopify mení webhooky Shopify na zápisy do Brevo hneď, ako prídu. Pravidlá synchronizácie, ktoré zostaví agent a schváli človek, presúvajú záznamy do Brevo podľa plánu. Táto stránka opisuje oboje a potom nástroje Shopify, ktoré Tajo poskytuje cez MCP.

Predpoklady

Skôr než začnete s integráciou, uistite sa, že máte:

• Obchod Shopify na ľubovoľnom pláne (Basic, Shopify, Advanced alebo Plus)
• Účet Tajo (Tajo je v predbežnom prístupe)
• Účet Brevo, cieľ synchronizácie
• Prístup správcu k Vášmu obchodu Shopify

Krok 1: Pripojte svoj obchod Shopify

Tajo je v predbežnom prístupe. Aplikácia pre Shopify nie je uvedená v obchode Shopify App Store a neexistuje žiadny odkaz na samoobslužnú inštaláciu. Kontaktujte tím, ktorý Vám pomôže s nastavením. Keď bude Váš pracovný priestor Tajo pripravený:

1. V Tajo otvorte Connections.
2. Zadajte doménu myshopify.com Vášho obchodu a zvoľte Connect Shopify. Shopify zobrazí rozsahy povolení, ktoré Tajo žiada, a po ich schválení Vás vráti späť do Tajo.
3. Na čo slúži každý rozsah a čo Tajo zapisuje späť do Shopify, zistíte vo Vysvetlení povolení Shopify.

Krok 2: Čo aplikácia Tajo pre Shopify posiela do Brevo

Aplikácia overí každý webhook Shopify, uloží ho, zaradí do frontu a hneď spracuje. Témy zákazníkov a produktov najprv čakajú približne štyri sekundy. Neexistuje žiadne dávkové okno. Neúspešná úloha sa opakuje s postupne predlžovaným odstupom (backoff).

Témy webhookov

Aplikácia Tajo pre Shopify odoberá tieto témy webhookov Shopify:

Povinné webhooky Shopify na ochranu súkromia (žiadosť o údaje zákazníka, vymazanie zákazníka, vymazanie obchodu) sú tiež obslúžené. Aplikácia neodoberá carts/*. Opustené košíky pochádzajú z tém checkouts/*.

Čo sa dostane do Brevo:

Aplikácia nepridáva do Vašej témy tlačidlo „Upozorniť ma“. Žiadosť o upozornenie na naskladnenie musí prísť z Vášho obchodu, napríklad z tlačidla, ktoré pridáte.

Existujúce údaje

Pri inštalácii aplikácia naimportuje Vašich existujúcich zákazníkov ako kontakty Brevo. Úplnú synchronizáciu historických údajov spustíte zo stránky synchronizácie v aplikácii. Na platených plánoch importuje aj produkty, kolekcie, spoločnosti a objednávky.

Krok 3: Zostavte pravidlo synchronizácie s agentom

Pravidlo synchronizácie je deklaratívna definícia jednej synchronizácie: zdrojový prostriedok, akcia v Brevo, mapovanie polí a filter. Nepíšete ho ručne. Opíšete ho, agent ho zostaví a človek ho schváli.

1. V Tajo otvorte Agents a požiadajte Brevo Integration Architect o synchronizáciu bežným jazykom. Napríklad: „Posielaj zákazníkov Shopify, ktorí prijali e-mailový marketing, do Brevo ako kontakty.“
2. Agent preskúma konektor Shopify. Jeho vzorka vracia názvy a typy polí, nikdy nie hodnoty zákazníkov.
3. Navrhne pravidlo s mapovaním polí a filtrom, potom overí mapovanie polí voči akcii Brevo a vykoná skúšobný beh (dry run) návrhu. Ani jeden krok nečíta záznamy zákazníkov.
4. Pravidlo uloží ako koncept. Môžete začať aj zo šablóny v Connections > Syncs and mappings > New sync from template.
5. Request publish approval spustí náhľad nad Vaším obchodom. Načíta najviac 10 záznamov, nič nezapíše do Brevo a neposúva kurzor. Zaznamená len počty: načítané záznamy, vhodné, namapované a odmietnuté filtrom, plus chyby mapovania. Ak náhľad zlyhá, žiadne schválenie sa nevytvorí.
6. Človek schváli žiadosť na stránke Approvals s písomným odôvodnením. Schválenie je viazané na digest SHA-256 pravidla a vyprší po 30 minútach. Stránka pravidla potom zobrazí Publish approved version.

Úprava publikovaného pravidla ho vráti do konceptu. Pred ďalším spustením znova prejde náhľadom a schválením.

Skutočné pravidlo

Toto je šablóna Shopify customers -> Brevo contacts tak, ako ju definuje Tajo:

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)",

Filter je kontrola súhlasu. Tajo odvodzuje obe hodnoty z email_marketing_consent.state v Shopify alebo zo staršieho príznaku accepts_marketing. Pravidlo, ktoré zapisuje kontakty do Brevo, nemožno bez neho publikovať. Druhá šablóna Shopify, Shopify orders → Brevo orders, zaznamenáva do Brevo objednávky kupujúcich, ktorí pri nákupe prijali marketing.

Kedy sa pravidlo spúšťa

• Pravidlá synchronizácie kontaktov sa predvolene spúšťajú každých 15 minút. Každý beh začína od kurzora pravidla.
• Stránka aktívneho pravidla má tlačidlo Test run (1 batch).
• Aktívne publikované pravidlo Shopify orders → Brevo orders sa tiež spúšťa každých 15 minút. Jeho prvý plánovaný beh začína niekoľko minút pred týmto okamihom a neodosiela staršie objednávky. Každý ďalší beh odošle objednávky aktualizované od predchádzajúceho behu.
• Minulé objednávky sa do Brevo dostanú len vtedy, keď pravidlo spustíte sami: tlačidlom Test run (1 batch) alebo tak, že o to požiadate agenta Sync Operator.
• Pravidlo pre objednávky sa podľa plánu spúšťa len s filtrom súhlasu kupujúceho s marketingom zo šablóny. Pravidlo s upraveným filtrom beží len vtedy, keď ho sami spustíte.
• Po piatich po sebe nasledujúcich neúspešných behoch sa pravidlo samo pozastaví a jeho stránka zobrazí poslednú chybu. Odstráňte príčinu a potom ho znova publikujte.

Každý beh je uvedený v histórii behov pravidla s načítanými, zapísanými a neúspešnými záznamami a s dĺžkou trvania.

Čo konektor Shopify číta a zapisuje

Pravidlá synchronizácie zapisujú len do cieľa, tu do Brevo. Nikdy nezapisujú do Shopify.

Aplikácia Tajo pre Shopify žiada 12 rozsahov povolení a do Shopify vykonáva krátky zoznam zápisov, napríklad odhlásenia súhlasu a vernostné štítky. Vysvetlenie povolení Shopify uvádza každý rozsah a každý zápis aj s tým, čo ho spúšťa.

Agenti a hostitelia MCP pristupujú k obchodu cez konektor Shopify:

Konektor deklaruje aj úpravu skladových zásob. Vyžaduje rozsah write_inventory, ktorý aplikácia Tajo pre Shopify nežiada.

Krok 4: Používajte nástroje Shopify cez MCP

Tajo poskytuje konektor Shopify ako server MCP na adrese https://alto.tajo.io/mcp/connectors/shopify. Pridajte ho do Claude Code:

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

Hostiteľ nájde server OAuth Tajo a otvorí prihlásenie do Tajo. Prístup majú len účty v predbežnom prístupe. Server poskytuje 12 nástrojov:

Riešenie problémov

• Kontakty sa nezobrazujú v Brevo: pozrite si chýbajúce kontakty v Brevo.
• Pravidlo, ktoré sa nespúšťa alebo sa samo pozastavilo: pozrite si údaje sa nesynchronizujú.

Ďalšie kroky

• Pochopenie synchronizácie údajov, ako sa správajú pravidlá synchronizácie
• Vysvetlenie povolení Shopify, každý rozsah a každý zápis
• Shopify + Brevo, príručka integrácie
• Kontaktujte tím, ktorý Vám pomôže s nastavením