---
title: "Conector Shopify"
description: "Guia completo de integração do Shopify para sincronizar clientes, pedidos, produtos e eventos de carrinho com o Brevo."
url: https://tajo.io/pt/docs/connectors/ecommerce/shopify/
markdown: https://tajo.io/pt/docs/connectors/ecommerce/shopify.md
lang: pt-BR
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.

# Conector Shopify

Status do conector: Em andamento Em construção. Ainda não verificado.

| Campo de origem | Campo de destino | Valor de exemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecte sua loja Shopify ao Brevo para sincronização completa de dados de clientes, recuperação de carrinho abandonado e campanhas de marketing automatizadas.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | Shopify |
| **Categoria** | E-commerce |
| **Complexidade de configuração** | Fácil |
| **Integração oficial** | Não |
| **Dados sincronizados** | Clientes, Pedidos, Produtos, Carrinhos, Eventos |
| **Skills disponíveis** | 12 |

## Recursos

- **Sincronização de clientes em tempo real** - Dados de clientes sincronizados instantaneamente com contatos do Brevo
- **Rastreamento de pedidos** - Eventos de pedidos para fluxos pós-compra
- **Sincronização de catálogo de produtos** - Produtos disponíveis para recomendações
- **Carrinho abandonado** - Rastreie e recupere carrinhos abandonados
- **Comportamento de navegação** - Rastreamento de visualização de página e interesse em produtos
- **Suporte a múltiplas lojas** - Conecte várias lojas Shopify

## Pré-requisitos

Antes de começar, certifique-se de ter:

1. Uma loja Shopify com acesso de administrador
2. Uma conta Brevo com acesso à API
3. Uma conta Tajo

## Instalação

### Opção 1: Shopify App Store (Recomendado)

1. Acesse o [app Tajo na Shopify App Store](https://apps.shopify.com/tajo)
2. Clique em “Add app”
3. Conceda as permissões solicitadas
4. Conecte sua conta Brevo

### Opção 2: Instalação manual

#### Passo 1: Crie um app Shopify

1. Acesse o admin da sua Shopify → Settings → Apps and sales channels
2. Clique em “Develop apps” → “Create an app”
3. Nomeie-o como “Tajo Integration”

#### Passo 2: Configure os escopos da API

Habilite estes escopos:

```
read_customers
write_customers
read_orders
read_products
read_checkouts
write_script_tags
```

#### Passo 3: Instale o app

```bash
# Using Tajo CLI
tajo connectors install shopify \
  --shop-url your-store.myshopify.com \
  --api-key $SHOPIFY_API_KEY \
  --api-secret $SHOPIFY_API_SECRET
```

#### Passo 4: Configure os webhooks

O Tajo registra automaticamente estes webhooks:

| Webhook | Finalidade |
| --- | --- |
| `customers/create` | Sincronização de novo cliente |
| `customers/update` | Alterações nos dados do cliente |
| `customers/delete` | Remoção de cliente |
| `orders/create` | Eventos de pedido realizado |
| `orders/updated` | Alterações de status do pedido |
| `checkouts/create` | Carrinho criado |
| `checkouts/update` | Carrinho atualizado |

## Configuração

### Configuração básica

```yaml
connectors:
  shopify:
    enabled: true
    shop_url: "your-store.myshopify.com"
    api_version: "2024-01"

    # Data sync options
    sync:
      customers: true
      orders: true
      products: true
      carts: true
      inventory: false  # Optional

    # List assignment
    lists:
      all_customers: 5
      buyers: 6
      abandoned_cart: 7
```

### Mapeamento de campos

Mapeie campos do Shopify para atributos de contato do Brevo:

#### Default Mappings

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | E-mail do cliente (identificador único) |
| `first_name` optional | string | Mapeia para o atributo FIRSTNAME |
| `last_name` optional | string | Mapeia para o atributo LASTNAME |
| `phone` optional | string | Mapeia para o atributo SMS para WhatsApp/SMS |
| `accepts_marketing` optional | boolean | Controla o status de inscrição |
| `orders_count` optional | integer | Número total de pedidos |
| `total_spent` optional | number | Valor total do cliente ao longo da vida |
| `tags` optional | array | Tags de cliente vindas do Shopify |

#### Mapeamento de atributos personalizados

```yaml
field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # E-commerce metrics
  orders_count: ORDER_COUNT
  total_spent: TOTAL_SPENT
  last_order_date: LAST_ORDER_DATE

  # Custom fields
  customer_type: CUSTOMER_TYPE
  preferred_language: LANGUAGE
  loyalty_tier: VIP_TIER

  # Computed fields
  average_order_value: AOV
  days_since_last_order: RECENCY
```

### Sincronização de produtos

Sincronize produtos para recomendações por e-mail:

```yaml
sync:
  products:
    enabled: true
    include_variants: true
    include_images: true
    categories_as_tags: true

    # Filter products
    filter:
      status: active
      exclude_tags: ["hidden", "wholesale-only"]
```

### Rastreamento de estoque

Habilite a sincronização de níveis de estoque:

```yaml
sync:
  inventory:
    enabled: true
    low_stock_threshold: 10
    out_of_stock_events: true
```

## Eventos

### Eventos de cliente

| Evento | Gatilho | Caso de uso |
| --- | --- | --- |
| `customer_created` | Cadastro de novo cliente | Série de boas-vindas |
| `customer_updated` | Alterações de perfil | Sincronização de dados |
| `customer_tags_added` | Tags atribuídas | Atualizações de segmento |

### Eventos de pedido

| Evento | Gatilho | Caso de uso |
| --- | --- | --- |
| `order_placed` | Checkout concluído | Confirmação de pedido |
| `order_fulfilled` | Pedido enviado | Notificação de envio |
| `order_cancelled` | Pedido cancelado | E-mail de cancelamento |
| `order_refunded` | Reembolso processado | Confirmação de reembolso |

### Eventos de carrinho

| Evento | Gatilho | Caso de uso |
| --- | --- | --- |
| `cart_created` | Itens adicionados ao carrinho | Rastreamento de navegação |
| `cart_updated` | Carrinho modificado | Rastreamento de valor do carrinho |
| `cart_abandoned` | Sem checkout em 30 min | E-mails de recuperação |

## Skills habilitadas

O conector Shopify habilita estas skills:

| Skill | Descrição |
| --- | --- |
| [Sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync) | Sincronização de clientes em tempo real |
| Eventos de pedido | Rastreamento do ciclo de vida do pedido |
| [Carrinho abandonado](https://tajo.io/pt/docs/skills/email-marketing/abandoned-cart) | E-mails de recuperação de carrinho |
| Série de boas-vindas | Onboarding de novos clientes |
| Pós-compra | Follow-up de pedido |
| Win-Back | Reengajamento de clientes inativos |
| Browse Abandonment | Follow-up de interesse em produtos |
| Reabastecimento | Lembretes de recompra |

## Exemplos de código

### Inicializar o conector

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Shopify store
await tajo.connectors.connect('shopify', {
  shopUrl: 'your-store.myshopify.com',
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecret: process.env.SHOPIFY_API_SECRET
});
```

### Executar sincronização inicial

```javascript
// Full historical sync
await tajo.connectors.sync('shopify', {
  type: 'full',
  resources: ['customers', 'orders', 'products'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('shopify');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   customersCount: 15420,
//   ordersCount: 8234,
//   productsCount: 342
// }
```

### Rastrear eventos de carrinho

Adicione o script do Tajo ao seu tema Shopify:

```liquid
<!-- Add to theme.liquid before </head> -->
{% if customer %}
<script>
  window.tajoConfig = {
    customerId: "{{ customer.id }}",
    customerEmail: "{{ customer.email }}",
    customerName: "{{ customer.first_name }}"
  };
</script>
{% endif %}
<script src="https://cdn.example.com/shopify.js"></script>
```

Caution

O endereço `example.com` acima é um exemplo provisório até que o endpoint da Tajo esteja disponível.

### Manipulador de webhook personalizado

```javascript
// Handle Shopify webhooks manually
app.post('/webhooks/shopify', async (req, res) => {
  const hmac = req.get('X-Shopify-Hmac-SHA256');

  // Verify webhook signature
  if (!verifyShopifyWebhook(req.body, hmac)) {
    return res.status(401).send('Unauthorized');
  }

  const topic = req.get('X-Shopify-Topic');

  // Forward to Tajo
  await tajo.connectors.handleWebhook('shopify', {
    topic,
    payload: req.body
  });

  res.status(200).send('OK');
});
```

## Monitoramento

### Métricas do dashboard

Monitore sua conexão Shopify no dashboard do Tajo:

- **Status da sincronização**: Saúde da conexão em tempo real
- **Clientes sincronizados**: Total de contatos vindos do Shopify
- **Pedidos rastreados**: Eventos de pedidos processados
- **Recuperação de carrinho**: Performance de carrinhos abandonados
- **Taxa de erro**: Tentativas de sincronização que falharam

### Logs de webhook

Visualize o status de entrega dos webhooks:

```bash
tajo connectors logs shopify --type webhook --last 24h
```

### Histórico de sincronização

Verifique operações de sincronização históricas:

```bash
tajo connectors history shopify --limit 10
```

## Solução de problemas

### Problemas comuns

Limites de taxa da API

O Shopify tem limites de taxa da API de 2 requisições/segundo. Use sincronização em lote para grandes importações históricas.

| Problema | Causa | Solução |
| --- | --- | --- |
| Webhook não recebido | Permissões do app | Reinstale o app com os escopos corretos |
| Cliente não sincronizado | E-mail ausente | O Shopify exige e-mail para clientes |
| Produtos ausentes | Status do produto | Verifique se o produto está com status “active” |
| Carrinho não rastreado | Script não carregado | Verifique o script em theme.liquid |

### Modo de depuração

Habilite logging detalhado:

```yaml
connectors:
  shopify:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### Testar conexão

```bash
tajo connectors test shopify
# ✓ API connection successful
# ✓ Webhooks registered
# ✓ Products accessible
# ✓ Customers readable
# ✓ Orders readable
```

## Melhores práticas

1. **Comece com uma loja de teste** - Use primeiro uma loja de desenvolvimento
2. **Execute a sincronização inicial fora do horário de pico** - Sincronizações grandes podem ser lentas
3. **Mapeie atributos personalizados** - Não dependa somente dos mapeamentos padrão
4. **Habilite o rastreamento de carrinho** - Essencial para recuperação de carrinho abandonado
5. **Monitore a saúde dos webhooks** - Configure alertas para entregas que falharam
6. **Use importações em lote** - Para dados históricos acima de 10.000 registros

## Segurança

- **OAuth 2.0** - Autenticação segura baseada em tokens
- **Verificação de webhook** - Validação de assinatura HMAC
- **Armazenamento criptografado** - Credenciais de API criptografadas em repouso
- **Acesso com escopo** - Somente as permissões mínimas necessárias

## Recursos relacionados

- [Conector WooCommerce](https://tajo.io/pt/docs/connectors/ecommerce/woocommerce)
- [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync)
- [Skill de carrinho abandonado](https://tajo.io/pt/docs/skills/email-marketing/abandoned-cart)
- [API de contatos do Brevo](https://tajo.io/pt/docs/contact-management)