---
title: "Guia de Integração com Shopify | Tajo"
description: "Como o Tajo conecta uma loja Shopify à Brevo: a sincronização por webhooks do app Shopify, regras de sincronização que um agente cria e uma pessoa aprova, e as ferramentas MCP do Shopify."
url: https://tajo.io/pt/docs/ecommerce-platforms/shopify/
markdown: https://tajo.io/pt/docs/ecommerce-platforms/shopify.md
lang: pt-BR
author: "Set Noa"
author_url: https://tajo.io/pt/set-noa/
robots: noindex
---

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.

# Guia de Integração com Shopify

[Set Noa](https://tajo.io/pt/set-noa/)

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](https://tajo.io/pt/contact) para configurar. Quando o seu workspace do Tajo estiver pronto:

1. No Tajo, abra **Connections**.
2. 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.
3. Confira para que serve cada scope, e o que o Tajo grava de volta no Shopify, em [Permissões do Shopify explicadas](https://tajo.io/pt/resources/help/integrations/shopify-permissions-explained/).

## 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.

1. 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.”
2. O agente inspeciona o conector do Shopify. A amostra dele traz nomes e tipos de campos, nunca valores de clientes.
3. 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.
4. Ele salva a regra como rascunho. Você também pode começar por um template em **Connections > Syncs and mappings > New sync from template**.
5. **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.
6. 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:

```ts
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](https://tajo.io/pt/resources/help/integrations/shopify-permissions-explained/) 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:

```bash
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](https://tajo.io/pt/resources/help/troubleshooting/contacts-missing-in-brevo/).
- Uma regra que não roda, ou que se pausou sozinha: veja [dados que não sincronizam](https://tajo.io/pt/resources/help/troubleshooting/data-not-syncing/).

## Próximos passos

- [Entendendo a sincronização de dados](https://tajo.io/pt/resources/help/getting-started/understanding-data-sync/), como as regras de sincronização se comportam
- [Permissões do Shopify explicadas](https://tajo.io/pt/resources/help/integrations/shopify-permissions-explained/), cada scope e cada gravação
- [Shopify + Brevo](https://tajo.io/pt/docs/integrations/shopify-brevo), o guia de integração
- [Fale com a equipe](https://tajo.io/pt/contact) para configurar