Handleiding voor de Shopify-integratie

Tajo verbindt Shopify op twee plekken met Brevo. De Tajo Shopify-app zet Shopify-webhooks om in schrijfacties naar Brevo zodra ze binnenkomen. Synchronisatieregels, die een agent bouwt en een mens goedkeurt, zetten records volgens een schema over naar Brevo. Deze pagina behandelt beide, en daarna de Shopify-tools die Tajo via MCP aanbiedt.

Vereisten

Zorg dat je het volgende hebt voordat je met de integratie begint:

• Shopify-winkel met elk abonnement (Basic, Shopify, Advanced of Plus)
• Tajo-account (Tajo is in early access)
• Brevo-account, de bestemming van de synchronisatie
• Beheerderstoegang tot je Shopify-winkel

Stap 1: verbind je Shopify-winkel

Tajo is in early access. De Shopify-app staat niet in de Shopify App Store en er is geen selfservice-installatielink. Neem contact op met het team om aan de slag te gaan. Zodra je Tajo-werkruimte klaar is:

1. Open in Tajo Connections.
2. Vul het myshopify.com-domein van je winkel in en kies Connect Shopify. Shopify toont de scopes die Tajo aanvraagt en stuurt je terug naar Tajo zodra je ze goedkeurt.
3. Lees in Shopify-machtigingen uitgelegd waarvoor elke scope dient en wat Tajo terugschrijft naar Shopify.

Stap 2: wat de Tajo Shopify-app naar Brevo stuurt

De app verifieert elke Shopify-webhook, slaat hem op, zet hem in de wachtrij en verwerkt hem meteen. Klant- en producttopics wachten eerst ongeveer vier seconden. Er is geen batchvenster. Een mislukte job wordt opnieuw geprobeerd met backoff.

Webhooktopics

De Tajo Shopify-app abonneert zich op deze Shopify-webhooktopics:

Ook de verplichte privacywebhooks van Shopify (verzoek om klantgegevens, klantgegevens wissen, winkelgegevens wissen) worden afgehandeld. De app abonneert zich niet op carts/*. Verlaten winkelwagens komen uit de checkouts/*-topics.

Wat er in Brevo terechtkomt:

De app voegt geen knop “Houd me op de hoogte” aan je thema toe. Een verzoek om een melding bij nieuwe voorraad moet uit je storefront komen, bijvoorbeeld via een knop die je zelf toevoegt.

Bestaande gegevens

Bij installatie importeert de app je bestaande klanten als Brevo-contacten. Een volledige historische synchronisatie start je vanaf de synchronisatiepagina van de app. Bij betaalde abonnementen importeert die ook producten, collecties, bedrijven en bestellingen.

Stap 3: bouw een synchronisatieregel met de agent

Een synchronisatieregel is een declaratieve definitie van één synchronisatie: een bronresource, een Brevo-actie, een veldmapping en een filter. Je schrijft hem niet met de hand. Jij beschrijft hem, een agent bouwt hem en een mens keurt hem goed.

1. Open in Tajo Agents en vraag de Brevo Integration Architect in gewone taal om de synchronisatie. Bijvoorbeeld: “Stuur Shopify-klanten die e-mailmarketing hebben geaccepteerd als contacten naar Brevo.”
2. De agent inspecteert de Shopify-connector. Zijn steekproef geeft veldnamen en typen terug, nooit klantwaarden.
3. Hij stelt een regel voor met een veldmapping en een filter, valideert de veldmapping tegen de actie van Brevo en doet een dry run van het concept. Geen van beide stappen leest klantrecords.
4. Hij slaat de regel op als concept. Je kunt ook beginnen met een sjabloon onder Connections > Syncs and mappings > New sync from template.
5. Request publish approval voert een preview uit op je winkel. Die leest maximaal 10 records, schrijft niets naar Brevo en verplaatst de cursor niet. Hij legt alleen aantallen vast: opgehaalde, in aanmerking komende, gemapte en door het filter afgewezen records, plus mappingfouten. Mislukt de preview, dan wordt er geen goedkeuringsverzoek aangemaakt.
6. Een mens keurt het verzoek goed op de pagina Approvals, met een schriftelijke onderbouwing. De goedkeuring is gekoppeld aan een SHA-256-digest van de regel en verloopt na 30 minuten. De pagina van de regel toont daarna Publish approved version.

Bewerk je een gepubliceerde regel, dan wordt hij weer een concept. Hij gaat opnieuw door preview en goedkeuring voordat hij weer draait.

Een echte regel

Dit is het sjabloon Shopify customers -> Brevo contacts zoals Tajo het definieert:

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

Het filter is de toestemmingscontrole. Tajo leidt beide waarden af uit email_marketing_consent.state van Shopify, of uit de oudere vlag accepts_marketing. Een regel die contacten naar Brevo schrijft, kan zonder dit filter niet gepubliceerd worden. Het andere Shopify-sjabloon, Shopify orders → Brevo orders, registreert bestellingen in Brevo voor kopers die bij de checkout marketing hebben geaccepteerd.

Wanneer een regel draait

• Regels voor contactsynchronisatie draaien standaard elke 15 minuten. Elke run begint bij de cursor van de regel.
• De pagina van een actieve regel heeft een knop Test run (1 batch).
• Een actieve, gepubliceerde regel Shopify orders → Brevo orders draait ook elke 15 minuten. De eerste geplande run begint een paar minuten vóór dat moment en verstuurt geen oudere bestellingen. Elke volgende run verstuurt de bestellingen die sinds de vorige run zijn bijgewerkt.
• Eerdere bestellingen komen alleen in Brevo terecht als je de regel zelf draait: met Test run (1 batch), of door de agent Sync Operator te vragen hem te draaien.
• Een bestellingenregel draait alleen volgens schema met het filter uit het sjabloon voor de marketing-opt-in van de koper. Een regel waarvan het filter is bewerkt, draait alleen als je hem zelf start.
• Na vijf mislukte runs op rij pauzeert de regel zichzelf en toont de pagina de laatste fout. Los de oorzaak op en publiceer opnieuw.

Elke run staat in de runhistorie van de regel, met gelezen, geschreven en mislukte records en de duur.

Wat de Shopify-connector leest en schrijft

Synchronisatieregels schrijven alleen naar de bestemming, hier Brevo. Ze schrijven nooit naar Shopify.

De Tajo Shopify-app vraagt 12 scopes aan en doet een korte lijst schrijfacties naar Shopify, zoals afmeldingen voor toestemming en loyaltytags. Shopify-machtigingen uitgelegd noemt elke scope en elke schrijfactie, met wat die in gang zet.

Agents en MCP-hosts bereiken de winkel via de Shopify-connector:

De connector declareert ook een voorraadaanpassing. Die vereist de scope write_inventory, die de Tajo Shopify-app niet aanvraagt.

Stap 4: gebruik de Shopify-tools via MCP

Tajo biedt de Shopify-connector aan als MCP-server op https://alto.tajo.io/mcp/connectors/shopify. Voeg hem toe aan Claude Code:

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

De host vindt de OAuth-server van Tajo en opent de Tajo-aanmelding. Toegang is beperkt tot early-access-accounts. De server biedt 12 tools:

Problemen oplossen

• Contacten verschijnen niet in Brevo: zie contacten ontbreken in Brevo.
• Een regel die niet draait of zichzelf heeft gepauzeerd: zie gegevens synchroniseren niet.

Volgende stappen

• Gegevenssynchronisatie begrijpen, hoe synchronisatieregels werken
• Shopify-machtigingen uitgelegd, elke scope en elke schrijfactie
• Shopify + Brevo, de integratiehandleiding
• Neem contact op met het team om aan de slag te gaan