Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

Nesta página

Guia de Integração com Shopify

O Tajo conecta o Shopify à Brevo em dois pontos. O app Tajo para Shopify transforma os webhooks do Shopify em gravações na Brevo assim que eles chegam. As regras de sincronização, que um agente cria e uma pessoa aprova, levam registros para a Brevo em intervalos programados. Esta página cobre os dois e, depois, as ferramentas do Shopify que o Tajo oferece via MCP.

Pré-requisitos

Antes de iniciar a integração, certifique-se de ter:

Loja Shopify em qualquer plano (Basic, Shopify, Advanced ou Plus)
Conta Tajo (o Tajo está em acesso antecipado)
Conta Brevo, o destino da sincronização
Acesso de administrador à sua loja Shopify

Passo 1: Conectar sua loja Shopify

O Tajo está em acesso antecipado. O app Shopify não está listado na Shopify App Store e não há link de instalação self-service. Fale com a equipe para configurar. Quando o seu workspace do Tajo estiver pronto:

No Tajo, abra Connections.
Digite o domínio myshopify.com da sua loja e escolha Connect Shopify. O Shopify mostra os scopes que o Tajo solicita e leva você de volta ao Tajo quando você os aprova.
Confira para que serve cada scope, e o que o Tajo grava de volta no Shopify, em Permissões do Shopify explicadas.

Passo 2: O que o app Tajo para Shopify envia para a Brevo

O app verifica cada webhook do Shopify, armazena, coloca na fila e processa na hora. Os tópicos de clientes e produtos aguardam cerca de quatro segundos antes. Não existe janela de lote. Um job que falha é tentado de novo com backoff.

Tópicos de webhook

O app Tajo para Shopify se inscreve nestes tópicos de webhook do Shopify:

Tópicos de webhook	Finalidade
`customers/create`, `customers/update`, `customers/delete`	Manter os contatos da Brevo atualizados
`orders/create`, `orders/updated`, `orders/fulfilled`, `orders/cancelled`	Eventos de pedidos e métricas de pedidos para a Brevo
`orders/paid`, `refunds/create`	Conceder e deduzir pontos de fidelidade
`checkouts/create`, `checkouts/update`	Recuperação de checkouts abandonados na Brevo
`products/create`, `products/update`, `products/delete`	Manter o catálogo de produtos atualizado na Brevo
`inventory_levels/update`	Manter o estoque dos produtos atualizado na Brevo
`collections/create`, `collections/update`, `collections/delete`	Manter as coleções atualizadas
`companies/`, `company_contacts/`, `company_locations/*` (create, update, delete)	Sincronização de empresas B2B
`app/uninstalled`, `app/scopes_update`, `app_subscriptions/update`	Ciclo de vida do app

Os webhooks obrigatórios de privacidade do Shopify (solicitação de dados do cliente, exclusão de dados do cliente e exclusão de dados da loja) também são tratados. O app não se inscreve em carts/*. Os carrinhos abandonados vêm dos tópicos checkouts/*.

O que chega à Brevo:

Evento do Shopify	Na Brevo
Cliente criado ou atualizado	O contato é criado ou atualizado com nome, e-mail e consentimento de marketing. Nos planos pagos, o app adiciona tags, número de pedidos, valor gasto e último pedido.
Cliente excluído	O contato tem a inscrição cancelada, não é excluído
Pedido criado, atualizado, pago, atendido ou cancelado	O pedido pela API de pedidos da Brevo, e os eventos `order_paid`, `order_completed` e `order_cancelled`
Reembolso criado	O evento `order_refunded`. Se você mantém um programa de fidelidade da Brevo pelo Tajo, os pontos são deduzidos proporcionalmente.
Pedido pago, com um programa de fidelidade da Brevo	Pontos concedidos conforme a sua taxa de pontos por dólar
Checkout criado ou atualizado, com e-mail e itens	Os eventos `cart_updated` e `cart_abandoned`. A sua automação na Brevo decide quando enviar.
Produto ou coleção criado, atualizado ou excluído	O catálogo de produtos e as categorias da Brevo
Nível de estoque atualizado	O estoque do produto no catálogo da Brevo. Quando uma variante passa de 0 para mais de 0, cada comprador que pediu para ser avisado recebe um evento `back_in_stock`, uma vez por reposição.

O app não adiciona um botão “Avise-me” ao seu tema. Um pedido de aviso de volta ao estoque precisa vir da sua vitrine, por exemplo de um botão que você adiciona.

Dados existentes

Na instalação, o app importa seus clientes existentes como contatos da Brevo. Uma sincronização histórica completa é iniciada na página de sincronização do app. Nos planos pagos, ela também importa produtos, coleções, empresas e pedidos.

Passo 3: Criar uma regra de sincronização com o agente

Uma regra de sincronização é a definição declarativa de uma sincronização: um recurso de origem, uma ação na Brevo, um mapeamento de campos e um filtro. Você não a escreve à mão. Você a descreve, um agente a cria e uma pessoa a aprova.

No Tajo, abra Agents e peça a sincronização ao Brevo Integration Architect em linguagem natural. Por exemplo: “Envie para a Brevo, como contatos, os clientes do Shopify que aceitaram marketing por e-mail.”
O agente inspeciona o conector do Shopify. A amostra dele traz nomes e tipos de campos, nunca valores de clientes.
Ele propõe uma regra com um mapeamento de campos e um filtro, depois valida o mapeamento em relação à ação da Brevo e faz um dry run do rascunho. Nenhuma das etapas lê registros de clientes.
Ele salva a regra como rascunho. Você também pode começar por um template em Connections > Syncs and mappings > New sync from template.
Request publish approval executa uma pré-visualização na sua loja. Ela lê no máximo 10 registros, não grava nada na Brevo e não move o cursor. Ela registra apenas contagens: registros lidos, elegíveis, mapeados e rejeitados pelo filtro, além dos erros de mapeamento. Se a pré-visualização falhar, nenhuma aprovação é criada.
Uma pessoa aprova a solicitação na página Approvals, com uma justificativa por escrito. A aprovação fica vinculada a um digest SHA-256 da regra e expira após 30 minutos. A página da regra passa então a mostrar Publish approved version.

Editar uma regra publicada faz com que ela volte a ser rascunho. Ela passa de novo pela pré-visualização e pela aprovação antes de rodar outra vez.

Uma regra real

Este é o template Shopify customers -> Brevo contacts como o Tajo o define:

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

O filtro é a verificação de consentimento. O Tajo deriva os dois valores do email_marketing_consent.state do Shopify, ou da flag mais antiga accepts_marketing. Uma regra que grava contatos na Brevo não pode ser publicada sem ele. O outro template do Shopify, Shopify orders → Brevo orders, registra pedidos na Brevo para compradores que aceitaram marketing no checkout.

Quando uma regra roda

As regras de sincronização de contatos rodam a cada 15 minutos por padrão. Cada execução começa a partir do cursor da regra.
A página de uma regra ativa tem um botão Test run (1 batch).
Uma regra Shopify orders → Brevo orders ativa e publicada também roda a cada 15 minutos. A primeira execução agendada começa alguns minutos antes desse momento e não envia pedidos mais antigos. Cada execução seguinte envia os pedidos atualizados desde a anterior.
Pedidos antigos só chegam à Brevo quando você mesmo executa a regra: com Test run (1 batch) ou pedindo ao agente Sync Operator que a execute.
Uma regra de pedidos só roda no agendamento com o filtro de opt-in de marketing do comprador do template. Uma regra cujo filtro foi editado só roda quando você a inicia.
Após cinco execuções seguidas com falha, a regra se pausa sozinha e a página dela mostra o último erro. Corrija a causa e publique de novo.

Cada execução aparece no histórico de execuções da regra, com os registros lidos, gravados e com falha, e a duração.

O que o conector do Shopify lê e grava

As regras de sincronização só gravam no destino, aqui a Brevo. Elas nunca gravam no Shopify.

O app Tajo para Shopify solicita 12 scopes e faz uma lista curta de gravações no Shopify, como cancelamentos de consentimento e tags de fidelidade. Permissões do Shopify explicadas lista cada scope e cada gravação, com o que a dispara.

Os agentes e os hosts MCP acessam a loja pelo conector do Shopify:

Leituras	Gravações
Dados da loja, clientes (listagem e busca), pedidos, produtos, metafields de clientes, níveis de estoque, status de exportação em massa	Metafields e tags de clientes, e o início de uma exportação em massa. Cada gravação é preparada como uma proposta e só é executada depois de aprovada.

O conector também declara um ajuste de estoque. Ele exige o scope write_inventory, que o app Tajo para Shopify não solicita.

Passo 4: Usar as ferramentas do Shopify via MCP

O Tajo oferece o conector do Shopify como um servidor MCP em https://alto.tajo.io/mcp/connectors/shopify. Adicione-o ao Claude Code:

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

O host descobre o servidor OAuth do Tajo e abre o login do Tajo. O acesso é limitado às contas com acesso antecipado. O servidor expõe 12 ferramentas:

Ferramenta	O que faz
`preview_tajo_shopify_app`	Pré-visualização interativa do app Tajo para Shopify, renderizada como MCP UI
`get_shop`	Os dados da loja
`search_customers`	Busca clientes com a sintaxe de consulta do Shopify, como `tag:tajo-vip` ou `total_spent:>100`
`list_customers`	Lista clientes, com paginação
`list_orders`	Lista pedidos, com paginação
`list_products`	Lista produtos com variantes, imagens e estoque
`get_customer_metafields`	Lê os metafields de um cliente
`get_inventory_levels`	Lê o estoque de uma variante em todos os locais
`poll_bulk_export`	Verifica uma exportação em massa e traz o link de download quando ela termina
`calculate_rewards_profile`	Calcula o nível, os pontos e o saldo de recompensas de um cliente a partir dos dados de comércio sincronizados
`shopify_propose`	Prepara uma gravação no Shopify como proposta. Nada é enviado.
`shopify_apply`	Executa uma proposta aprovada

Solução de problemas

Contatos que não aparecem na Brevo: veja contatos ausentes na Brevo.
Uma regra que não roda, ou que se pausou sozinha: veja dados que não sincronizam.

Próximos passos

Entendendo a sincronização de dados, como as regras de sincronização se comportam
Permissões do Shopify explicadas, cada scope e cada gravação
Shopify + Brevo, o guia de integração
Fale com a equipe para configurar