---
title: "Conector Customer.io"
description: "Guia completo de integração do Customer.io para sincronizar pessoas, eventos, campanhas e dados de workflow com o Brevo via Tajo."
url: https://tajo.io/pt/docs/connectors/marketing/customerio/
markdown: https://tajo.io/pt/docs/connectors/marketing/customerio.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 Customer.io

Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje.

| 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 plataforma de mensageria Customer.io ao Brevo para dados de cliente unificados, coordenação de campanhas multiplataforma e analytics de engajamento consolidados.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | Customer.io |
| **Categoria** | Marketing |
| **Complexidade de configuração** | Moderada |
| **Integração oficial** | Não |
| **Dados sincronizados** | Pessoas, Eventos, Campanhas, Segmentos |
| **APIs usadas** | Track API, App API, Pipelines API |
| **Autenticação** | Site ID + API Key / App API Key |
| **URLs base** | `track.customer.io`, `api.customer.io` |

## Recursos

- **Sincronização de pessoas** - Sincronização bidirecional de perfis de cliente com contatos do Brevo
- **Encaminhamento de eventos** - Rastreie eventos comportamentais e encaminhe para o Brevo como gatilhos de automação
- **Analytics de campanha** - Sincronize métricas de desempenho de campanha para relatórios unificados
- **Dados de workflow** - Espelhe estados de workflow do Customer.io em atributos de contato do Brevo
- **Replicação de segmentos** - Replique segmentos do Customer.io como listas do Brevo
- **Sincronização de dados de objeto** - Sincronize objetos que não são pessoas e dados de relacionamento

## Pré-requisitos

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

1. Uma conta Customer.io com acesso à API
2. Seu Site ID e Track API Key (encontrados em Settings > API Credentials)
3. Uma App API key para ler dados de campanhas e segmentos
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo com assinatura ativa

## Autenticação

O Customer.io usa duas APIs separadas com métodos de autenticação diferentes:

### Track API (Dados comportamentais)

Usada para enviar pessoas, eventos e dados de dispositivos. Autentica com Site ID e API Key via Basic Auth.

```bash
# Basic Auth: Site ID as username, API Key as password
curl -X POST https://track.customer.io/api/v1/customers/user123 \
  -u "$SITE_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

### App API (Leitura de dados)

Usada para recuperar campanhas, segmentos e dados de clientes. Autentica com um token Bearer.

```bash
curl -X GET https://api.customer.io/v1/campaigns \
  -H "Authorization: Bearer $APP_API_KEY"
```

Separação de chaves API

A Track API key e a App API key são credenciais diferentes. A Track API key é usada para gravar dados, enquanto a App API key é para ler dados. Ambas são necessárias para a integração completa do Tajo.

### Conectando ao Tajo

```bash
tajo connectors install customerio \
  --site-id $CIO_SITE_ID \
  --track-api-key $CIO_TRACK_API_KEY \
  --app-api-key $CIO_APP_API_KEY
```

## Configuração

### Configuração básica

```yaml
connectors:
  customerio:
    enabled: true
    region: "us"  # or "eu" for EU data center

    sync:
      people: true
      events: true
      campaigns: true
      segments: true
      objects: false

    lists:
      all_contacts: 12
      active_subscribers: 13
      churned: 14
```

### Mapeamento de campos

Mapeie atributos de pessoa do Customer.io para atributos de contato do Brevo:

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

  # Engagement metrics
  created_at: SIGNUP_DATE
  last_activity: LAST_ACTIVE
  plan: PLAN_NAME

  # Custom attributes
  company: COMPANY
  role: JOB_TITLE
  mrr: MONTHLY_REVENUE
  lifecycle_stage: LIFECYCLE_STAGE
```

### Mapeamento de eventos

```yaml
event_mapping:
  # Customer.io event -> Brevo event
  purchase_completed: ORDER_PLACED
  subscription_started: SUBSCRIPTION_START
  feature_activated: FEATURE_USED
  support_ticket_opened: SUPPORT_REQUEST
```

## Endpoints da API

O Tajo integra-se com os seguintes endpoints da API do Customer.io:

| Endpoint | Método | API | Finalidade |
| --- | --- | --- | --- |
| `/api/v1/customers/{id}` | PUT | Track | Criar ou atualizar uma pessoa |
| `/api/v1/customers/{id}/events` | POST | Track | Rastrear um evento de pessoa |
| `/api/v1/events` | POST | Track | Rastrear eventos anônimos |
| `/api/v2/entity` | POST | Track | Criar ou atualizar pessoas/objetos (Pipelines) |
| `/v1/campaigns` | GET | App | Listar campanhas |
| `/v1/campaigns/{id}/metrics` | GET | App | Métricas de desempenho de campanha |
| `/v1/segments` | GET | App | Listar segmentos |
| `/v1/segments/{id}/membership` | GET | App | Obter membros de segmento |
| `/v1/customers/{id}/attributes` | GET | App | Obter atributos de cliente |
| `/v1/customers/{id}/activities` | GET | App | Obter log de atividade do cliente |

## 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
});

await tajo.connectors.connect('customerio', {
  siteId: process.env.CIO_SITE_ID,
  trackApiKey: process.env.CIO_TRACK_API_KEY,
  appApiKey: process.env.CIO_APP_API_KEY,
  region: 'us'
});
```

### Sincronizar pessoas para o Brevo

```javascript
// Incremental sync of Customer.io people
await tajo.connectors.sync('customerio', {
  type: 'incremental',
  resources: ['people'],
  since: '2024-01-01',
  batchSize: 100
});

const status = await tajo.connectors.status('customerio');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T14:20:00Z',
//   peopleCount: 32500,
//   campaignsTracked: 18,
//   eventsProcessed: 87000
// }
```

### Encaminhar eventos

```javascript
// Forward Customer.io reporting webhook events to Brevo
app.post('/webhooks/customerio', async (req, res) => {
  const events = req.body;

  for (const event of events) {
    await tajo.connectors.handleEvent('customerio', {
      type: event.metric,
      payload: {
        customerId: event.data.customer_id,
        campaignId: event.data.campaign_id,
        timestamp: event.timestamp
      }
    });
  }

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

### Exportar segmento

```javascript
const result = await tajo.connectors.exportSegment('customerio', {
  segmentId: 42,
  targetList: 13,
  includeAttributes: ['email', 'first_name', 'last_name', 'plan']
});

console.log(`Exported ${result.count} people to Brevo list 13`);
```

## Limites de taxa

O Customer.io aplica diferentes limites de taxa por API:

| API | Limite de taxa | Observações |
| --- | --- | --- |
| **Track API** | ~100 requisições/segundo | Por workspace |
| **App API** | 10 requisições/segundo | Por chave API |
| **Pipelines API** | 100 requisições/segundo | Recomendado para dados em volume |
| **Endpoint de lote** | 1.000 pessoas por requisição | Payload máx. 500KB |

Use endpoints de lote

Para grandes sincronizações, o Tajo usa o endpoint de lote do Customer.io para enviar até 1.000 pessoas por requisição, reduzindo significativamente o volume de chamadas à API.

## Solução de problemas

### Problemas comuns

| Problema | Causa | Solução |
| --- | --- | --- |
| 401 Unauthorized | Site ID ou chave API inválidos | Verifique credenciais em Customer.io Settings > API |
| Pessoas não sincronizando | Identificador ausente | Certifique-se de que cada pessoa tenha um `id` ou `email` |
| Eventos não rastreados | Tipo de chave API incorreto | Use a Track API key para eventos, não a App API key |
| Dados da UE inacessíveis | Região configurada incorretamente | Defina a região como `eu` para workspaces da UE |
| Erros de limite de taxa | Muitas chamadas à App API | Reduza a frequência de polling para dados de campanha |

### Modo de depuração

```yaml
connectors:
  customerio:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### Testar conexão

```bash
tajo connectors test customerio
# ✓ Track API connection successful
# ✓ App API connection successful
# ✓ People accessible
# ✓ Campaigns readable
# ✓ Segments listable
```

## Melhores práticas

1. **Use a Pipelines API para dados em volume** - A Pipelines API mais recente é otimizada para ingestão de alto volume
2. **Configure webhooks de relatório** - Encaminhe eventos de e-mail do Customer.io para o Tajo em tempo real
3. **Mapeie estágios do ciclo de vida** - Sincronize associação de segmentos do Customer.io para atributos do Brevo
4. **Use identificadores consistentes** - Combine campos `id` entre Customer.io e Brevo
5. **Sincronize incrementalmente** - Evite exportações completas; aproveite os timestamps `last_activity`
6. **Monitore entrega de webhooks** - Configure alertas para entregas de webhook com falha

## Segurança

- **Basic Auth** - A Track API autentica com Site ID e API Key
- **Bearer Token** - A App API usa tokens bearer no estilo OAuth
- **Somente HTTPS** - Toda comunicação com a API é criptografada via TLS 1.2+
- **Data centers regionais** - Opção de data center na UE para conformidade com GDPR
- **Armazenamento criptografado** - Todas as credenciais são criptografadas em repouso no Tajo
- **Assinaturas de webhook** - Verifique payloads de webhook com assinaturas HMAC

## Recursos relacionados

- [Conector Braze](https://tajo.io/pt/docs/connectors/marketing/braze)
- [Conector Iterable](https://tajo.io/pt/docs/connectors/marketing/iterable)
- [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync)
- [API de contatos do Brevo](https://tajo.io/pt/docs/contact-management)