Conector Shopify

Conector Shopify

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

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

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

Configuração

Configuração básica

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:

Mapeamento de atributos personalizados

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:

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:

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

Eventos

Eventos de cliente

Eventos de pedido

Eventos de carrinho

Skills habilitadas

O conector Shopify habilita estas skills:

Exemplos de código

Inicializar o conector

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

// 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:

<!-- 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.tajo.io/shopify.js"></script>

Manipulador de webhook personalizado

// 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:

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

Histórico de sincronização

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

tajo connectors history shopify --limit 10

Solução de problemas

Problemas comuns

Modo de depuração

Habilite logging detalhado:

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

Testar conexão

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
• Skill de sincronização de clientes
• Skill de carrinho abandonado
• API de contatos do Brevo