---
title: "Connettore Customer.io"
description: "Guida completa all'integrazione di Customer.io per sincronizzare persone, eventi, campagne e dati di workflow con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/marketing/customerio/
markdown: https://tajo.io/it/docs/connectors/marketing/customerio.md
lang: it-IT
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Connettore Customer.io

Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore.

| Campo di origine | Campo di destinazione | Valore di esempio |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Collega la tua piattaforma di messaggistica Customer.io a Brevo per dati cliente unificati, coordinamento di campagne cross-platform e analytics di engagement consolidate.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Customer.io |
| **Categoria** | Marketing |
| **Complessità di setup** | Moderata |
| **Integrazione ufficiale** | No |
| **Dati sincronizzati** | Persone, Eventi, Campagne, Segmenti |
| **API utilizzate** | Track API, App API, Pipelines API |
| **Autenticazione** | Site ID + API Key / App API Key |
| **Base URL** | `track.customer.io`, `api.customer.io` |

## Funzionalità

- **Sync delle persone** - Sincronizzazione bidirezionale dei profili cliente con i contatti Brevo
- **Inoltro eventi** - Traccia eventi comportamentali e inoltrali a Brevo per i trigger di automazione
- **Analytics delle campagne** - Sincronizza le metriche di performance delle campagne per una reportistica unificata
- **Dati workflow** - Replica gli stati dei workflow Customer.io negli attributi di contatto Brevo
- **Replica dei segmenti** - Replica i segmenti Customer.io come liste Brevo
- **Sync dati oggetti** - Sincronizza oggetti non-persone e dati relazionali

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Customer.io con accesso API
2. Il tuo Site ID e Track API Key (in Settings > API Credentials)
3. Una chiave App API per leggere dati di campagne e segmenti
4. Un account Brevo con accesso API
5. Un account Tajo con un abbonamento attivo

## Autenticazione

Customer.io utilizza due API separate con metodi di autenticazione diversi:

### Track API (Dati comportamentali)

Usata per inviare persone, eventi e dati dispositivo. Si autentica con Site ID e API Key tramite 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 (Lettura dati)

Usata per recuperare campagne, segmenti e dati cliente. Si autentica con un Bearer token.

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

Separazione delle chiavi API

La chiave Track API e la chiave App API sono credenziali diverse. La chiave Track API è usata per scrivere dati, mentre la chiave App API è per leggere dati. Entrambe sono richieste per l’integrazione completa con Tajo.

### Connessione a 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
```

## Configurazione

### Setup di base

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

### Mappatura dei campi

Mappa gli attributi delle persone Customer.io agli attributi di contatto 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
```

### Mappatura degli eventi

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

## Endpoint API

Tajo si integra con i seguenti endpoint API di Customer.io:

| Endpoint | Metodo | API | Scopo |
| --- | --- | --- | --- |
| `/api/v1/customers/{id}` | PUT | Track | Crea o aggiorna una persona |
| `/api/v1/customers/{id}/events` | POST | Track | Traccia un evento di una persona |
| `/api/v1/events` | POST | Track | Traccia eventi anonimi |
| `/api/v2/entity` | POST | Track | Crea o aggiorna persone/oggetti (Pipelines) |
| `/v1/campaigns` | GET | App | Elenca le campagne |
| `/v1/campaigns/{id}/metrics` | GET | App | Metriche di performance delle campagne |
| `/v1/segments` | GET | App | Elenca i segmenti |
| `/v1/segments/{id}/membership` | GET | App | Ottieni i membri di un segmento |
| `/v1/customers/{id}/attributes` | GET | App | Ottieni gli attributi di un cliente |
| `/v1/customers/{id}/activities` | GET | App | Ottieni il log attività di un cliente |

## Esempi di codice

### Inizializza il connettore

```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'
});
```

### Sincronizza le persone su 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
// }
```

### Inoltra eventi

```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');
});
```

### Esporta un 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`);
```

## Limiti di velocità

Customer.io applica limiti di velocità diversi per ciascuna API:

| API | Limite | Note |
| --- | --- | --- |
| **Track API** | ~100 richieste/secondo | Per workspace |
| **App API** | 10 richieste/secondo | Per chiave API |
| **Pipelines API** | 100 richieste/secondo | Consigliata per dati in blocco |
| **Endpoint batch** | 1.000 persone per richiesta | Payload massimo 500KB |

Usa gli endpoint batch

Per sync di grandi dimensioni, Tajo usa l’endpoint batch di Customer.io per inviare fino a 1.000 persone per richiesta, riducendo significativamente il volume di chiamate API.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | Site ID o chiave API non validi | Verifica le credenziali in Customer.io Settings > API |
| Persone non sincronizzate | Identificatore mancante | Assicurati che ogni persona abbia un `id` o `email` |
| Eventi non tracciati | Tipo di chiave API errato | Usa la chiave Track API per gli eventi, non la chiave App API |
| Dati EU non accessibili | Regione configurata errata | Imposta region su `eu` per workspace EU |
| Errori limite di velocità | Troppe chiamate App API | Riduci la frequenza di polling per i dati delle campagne |

### Modalità debug

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

### Testa la connessione

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

## Best practice

1. **Usa la Pipelines API per dati in blocco** - La nuova Pipelines API è ottimizzata per ingest ad alto volume
2. **Imposta i webhook di reporting** - Inoltra gli eventi email Customer.io a Tajo in tempo reale
3. **Mappa gli stage del lifecycle** - Sincronizza l’appartenenza ai segmenti Customer.io agli attributi Brevo
4. **Usa identificatori coerenti** - Allinea i campi `id` tra Customer.io e Brevo
5. **Sincronizza in modo incrementale** - Evita le esportazioni complete; sfrutta i timestamp `last_activity`
6. **Monitora la consegna webhook** - Imposta avvisi per le consegne webhook fallite

## Sicurezza

- **Basic Auth** - La Track API si autentica con Site ID e API Key
- **Bearer Token** - L’App API usa bearer token in stile OAuth
- **Solo HTTPS** - Tutte le comunicazioni API cifrate via TLS 1.2+
- **Data center regionali** - Opzione data center EU per la conformità GDPR
- **Storage cifrato** - Tutte le credenziali cifrate a riposo in Tajo
- **Firme webhook** - Verifica i payload webhook con firme HMAC

## Risorse correlate

- [Connettore Braze](https://tajo.io/it/docs/connectors/marketing/braze)
- [Connettore Iterable](https://tajo.io/it/docs/connectors/marketing/iterable)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)
- [API Contatti Brevo](https://tajo.io/it/docs/contact-management)