Sincronizzazione Clienti

Sincronizza automaticamente i dati dei clienti dalla tua piattaforma e-commerce ai contatti Brevo. Questa skill assicura che la tua lista di contatti Brevo rifletta sempre la tua base clienti attuale.

Panoramica

Proprietà	Valore
Categoria	Data Sync
Stato	Stabile
Versione	2.1
Trigger	`customer_created`, `customer_updated`, `customer_deleted`
Azioni	Crea Contatto, Aggiorna Contatto, Elimina Contatto

Come funziona

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]

Rilevamento eventi: Ascolta gli eventi del ciclo di vita cliente dalla tua piattaforma
Mappatura dati: Mappa i campi della piattaforma sugli attributi dei contatti Brevo
Sincronizzazione API: Crea, aggiorna o elimina contatti tramite l’API Brevo
Gestione errori: Ritenta le operazioni fallite con backoff esponenziale

Configurazione

Setup di base

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

Mappatura dei campi

Mappa i campi cliente della tua piattaforma sugli attributi dei contatti Brevo:

Mappature di campo predefinite

Parameter	Type	Description
`email` required	string	Indirizzo email del cliente. Usato come identificatore univoco in Brevo.
`firstName` optional	string	Nome del cliente. Mappato sull'attributo FIRSTNAME. Default: `FIRSTNAME`
`lastName` optional	string	Cognome del cliente. Mappato sull'attributo LASTNAME. Default: `LASTNAME`
`phone` optional	string	Numero di telefono in formato E.164. Mappato sull'attributo SMS per WhatsApp/SMS. Default: `SMS`
`acceptsMarketing` optional	boolean	Stato di opt-in marketing. Controlla lo stato di iscrizione all'email. Default: `true`

Attributi personalizzati

Aggiungi mappature di attributi personalizzati per i dati 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

Crea prima gli attributi: gli attributi personalizzati devono essere creati in Brevo prima di poter essere sincronizzati. Usa la dashboard Brevo o l’API per crearli.

Trigger

customer_created

Si attiva quando un nuovo cliente viene creato nella tua piattaforma.

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

Si attiva quando le informazioni del cliente vengono modificate.

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

customer_deleted

Si attiva quando un cliente viene rimosso dalla tua piattaforma.

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

Azioni

Crea Contatto

Crea un nuovo contatto in Brevo quando viene creato un cliente.

Crea un nuovo contatto nel tuo account Brevo

Query Parameters

Parameter	Description
email string required	Indirizzo email del contatto
attributes object optional	Attributi del contatto
listIds array optional	ID delle liste a cui aggiungere il contatto
updateEnabled boolean optional	Aggiorna se il contatto esiste Default: `false`

Responses

201 Contatto creato con successo

400 Parametri della richiesta non validi

409 Il contatto esiste già

Aggiorna Contatto

Aggiorna un contatto esistente quando i dati del cliente cambiano.

Aggiorna gli attributi di un contatto esistente

Path Parameters

Parameter	Description
identifier string required	Email o ID del contatto

Query Parameters

Parameter	Description
attributes object optional	Attributi da aggiornare
listIds array optional	Liste a cui aggiungere il contatto
unlinkListIds array optional	Liste dalle quali rimuovere il contatto

Responses

204 Contatto aggiornato con successo

400 Parametri della richiesta non validi

404 Contatto non trovato

Elimina Contatto

Rimuove un contatto quando un cliente viene eliminato.

Elimina definitivamente un contatto da Brevo

Path Parameters

Parameter	Description
identifier string required	Email o ID del contatto

Responses

204 Contatto eliminato con successo

404 Contatto non trovato

Esempi di codice

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

Monitoraggio

Dashboard dello stato di sincronizzazione

Monitora le performance di sincronizzazione nella dashboard Tajo:

Tasso di successo della sync: percentuale di sincronizzazioni riuscite
Latenza media: tempo tra evento e aggiornamento Brevo
Tasso di errore: tentativi di sync falliti
Profondità della coda: operazioni di sync in attesa

Notifiche via webhook

Ricevi notifiche per gli eventi di sync:

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

Risoluzione dei problemi

Problemi comuni

Il contatto esiste già (409)

Abilita updateEnabled: true nella configurazione per aggiornare i contatti esistenti invece di fallire.

Errore	Causa	Soluzione
`Contact already exists`	Esiste un contatto con quell’email	Abilita `updateEnabled: true`
`Invalid attribute`	L’attributo non esiste in Brevo	Crea prima l’attributo in Brevo
`Rate limit exceeded`	Troppe richieste API	Usa la modalità di sync in batch
`Invalid email format`	Indirizzo email malformato	Valida le email prima della sync

Modalità debug

Abilita il logging di debug per la risoluzione dei problemi:

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

Skill correlate

Eventi Ordine - Sincronizza i dati degli ordini
Catalogo Prodotti - Sincronizza i dati dei prodotti
Eventi Carrello - Traccia l’attività del carrello

Prossimi passi

Configura le mappature di campo per la tua piattaforma
Imposta gli attributi personalizzati in Brevo
Abilita la sync in tempo reale per aggiornamenti istantanei

Sincronizzazione Clienti