Sincronização de Clientes

Sincronize automaticamente os dados de clientes da sua plataforma de e-commerce com os contatos do Brevo. Esta skill garante que sua lista de contatos do Brevo sempre reflita sua base de clientes atual.

Visão Geral

Propriedade	Valor
Categoria	Data Sync
Status	Estável
Versão	2.1
Triggers	`customer_created`, `customer_updated`, `customer_deleted`
Ações	Criar Contato, Atualizar Contato, Excluir Contato

Como Funciona

graph LR
    A[E-commerce Platform] -->|Customer Event| B[Customer Sync Skill]
    B -->|Map Data| C[Field Mapping]
    C -->|API Call| D[Brevo Contacts API]
    D -->|Success| E[Contact Updated]
    D -->|Error| F[Retry Queue]

Detecção de Eventos: Escuta eventos do ciclo de vida do cliente na sua plataforma
Mapeamento de Dados: Mapeia campos da plataforma para atributos de contato do Brevo
Sincronização via API: Cria, atualiza ou exclui contatos via API do Brevo
Tratamento de Erros: Repete operações que falharam com backoff exponencial

Configuração

Configuração Básica

skills:
  customer-sync:
    enabled: true
    source: shopify  # or woocommerce, magento, custom

    # Map platform fields to Brevo attributes
    field_mapping:
      email: email
      firstName: FIRSTNAME
      lastName: LASTNAME
      phone: SMS

    # Sync options
    options:
      sync_mode: realtime  # or batch
      delete_behavior: soft  # or hard
      list_id: 5  # Add to this list

Mapeamento de Campos

Mapeie os campos de cliente da sua plataforma para atributos de contato do Brevo:

Mapeamentos de Campos Padrão

Parameter	Type	Description
`email` required	string	Endereço de e-mail do cliente. Usado como identificador único no Brevo.
`firstName` optional	string	Primeiro nome do cliente. Mapeia para o atributo FIRSTNAME. Default: `FIRSTNAME`
`lastName` optional	string	Sobrenome do cliente. Mapeia para o atributo LASTNAME. Default: `LASTNAME`
`phone` optional	string	Número de telefone no formato E.164. Mapeia para o atributo SMS para WhatsApp/SMS. Default: `SMS`
`acceptsMarketing` optional	boolean	Status de opt-in de marketing. Controla o status da assinatura de e-mail. Default: `true`

Atributos Personalizados

Adicione mapeamentos de atributos personalizados para dados de e-commerce:

field_mapping:
  # Standard fields
  email: email
  firstName: FIRSTNAME

  # Custom e-commerce attributes
  totalOrders: TOTAL_ORDERS
  totalSpent: TOTAL_SPENT
  lastOrderDate: LAST_ORDER_DATE
  customerTier: CUSTOMER_TIER
  tags: TAGS

Tip

Crie os atributos primeiro: Atributos personalizados precisam ser criados no Brevo antes que possam ser sincronizados. Use o dashboard ou API do Brevo para criá-los.

Triggers

customer_created

Dispara quando um novo cliente é criado na sua plataforma.

{
  "event": "customer_created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+1234567890",
    "acceptsMarketing": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

customer_updated

Dispara quando as informações do cliente são modificadas.

{
  "event": "customer_updated",
  "timestamp": "2024-01-15T14:45:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "changes": {
      "phone": {
        "old": null,
        "new": "+1234567890"
      }
    }
  }
}

customer_deleted

Dispara quando um cliente é removido da sua plataforma.

{
  "event": "customer_deleted",
  "timestamp": "2024-01-15T16:00:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "deletedAt": "2024-01-15T16:00:00Z"
  }
}

Ações

Criar Contato

Cria um novo contato no Brevo quando um cliente é criado.

Crie um novo contato na sua conta Brevo

Query Parameters

Parameter	Description
email string required	Endereço de e-mail do contato
attributes object optional	Atributos do contato
listIds array optional	IDs das listas às quais o contato será adicionado
updateEnabled boolean optional	Atualiza se o contato já existir Default: `false`

Responses

201 Contato criado com sucesso

400 Parâmetros de requisição inválidos

409 Contato já existe

Atualizar Contato

Atualiza um contato existente quando os dados do cliente mudam.

Atualize os atributos de um contato existente

Path Parameters

Parameter	Description
identifier string required	E-mail ou ID do contato

Query Parameters

Parameter	Description
attributes object optional	Atributos a serem atualizados
listIds array optional	Listas às quais adicionar o contato
unlinkListIds array optional	Listas das quais remover o contato

Responses

204 Contato atualizado com sucesso

400 Parâmetros de requisição inválidos

404 Contato não encontrado

Excluir Contato

Remove um contato quando um cliente é excluído.

Excluir permanentemente um contato do Brevo

Path Parameters

Parameter	Description
identifier string required	E-mail ou ID do contato

Responses

204 Contato excluído com sucesso

404 Contato não encontrado

Exemplos de Código

JavaScript (Node.js)

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

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

// Enable customer sync skill
await tajo.skills.enable('customer-sync', {
  source: 'shopify',
  fieldMapping: {
    email: 'email',
    firstName: 'FIRSTNAME',
    lastName: 'LASTNAME',
    totalOrders: 'TOTAL_ORDERS',
    totalSpent: 'TOTAL_SPENT'
  },
  options: {
    syncMode: 'realtime',
    listId: 5
  }
});

// Manually trigger a sync
await tajo.skills.trigger('customer-sync', {
  event: 'customer_created',
  data: {
    email: '[email protected]',
    firstName: 'Jane',
    lastName: 'Smith'
  }
});

Python

from tajo import TajoClient

tajo = TajoClient(
    api_key=os.environ['TAJO_API_KEY'],
    brevo_api_key=os.environ['BREVO_API_KEY']
)

# Enable customer sync skill
tajo.skills.enable('customer-sync', {
    'source': 'woocommerce',
    'field_mapping': {
        'email': 'email',
        'first_name': 'FIRSTNAME',
        'last_name': 'LASTNAME',
        'total_orders': 'TOTAL_ORDERS'
    },
    'options': {
        'sync_mode': 'realtime',
        'list_id': 5
    }
})

# Manually trigger a sync
tajo.skills.trigger('customer-sync', {
    'event': 'customer_updated',
    'data': {
        'email': '[email protected]',
        'total_orders': 10,
        'total_spent': 1250.00
    }
})

Monitoramento

Dashboard de Status de Sincronização

Monitore o desempenho da sincronização no dashboard Tajo:

Taxa de Sucesso da Sincronização: Porcentagem de sincronizações bem-sucedidas
Latência Média: Tempo do evento até a atualização no Brevo
Taxa de Erro: Tentativas de sincronização que falharam
Profundidade da Fila: Operações de sincronização pendentes

Notificações por Webhook

Receba notificações para eventos de sincronização:

notifications:
  webhook_url: https://your-app.com/webhooks/tajo
  events:
    - sync_completed
    - sync_failed
    - batch_completed

Solução de Problemas

Problemas Comuns

Contato Já Existe (409)

Ative updateEnabled: true na sua configuração para atualizar contatos existentes em vez de falhar.

Erro	Causa	Solução
`Contact already exists`	Contato com o e-mail já existe	Ative `updateEnabled: true`
`Invalid attribute`	Atributo não existe no Brevo	Crie o atributo no Brevo primeiro
`Rate limit exceeded`	Muitas requisições à API	Use o modo de sincronização em lote
`Invalid email format`	Endereço de e-mail malformado	Valide os e-mails antes de sincronizar

Modo de Depuração

Ative logs de depuração para solução de problemas:

skills:
  customer-sync:
    debug: true
    log_level: verbose

Skills Relacionadas

Eventos de Pedidos - Sincronize dados de pedidos
Catálogo de Produtos - Sincronize dados de produtos
Eventos de Carrinho - Acompanhe atividade no carrinho

Próximos Passos

Configure mapeamentos de campos para sua plataforma
Configure atributos personalizados no Brevo
Ative a sincronização em tempo real para atualizações instantâneas

Sincronização de Clientes