Sincronización de Clientes

Sincroniza automáticamente los datos de clientes de tu plataforma de e-commerce con los contactos de Brevo. Esta skill garantiza que tu lista de contactos de Brevo siempre refleje tu base de clientes actual.

Resumen

Propiedad	Valor
Categoría	Sincronización de Datos
Estado	Estable
Versión	2.1
Triggers	`customer_created`, `customer_updated`, `customer_deleted`
Acciones	Crear Contacto, Actualizar Contacto, Eliminar Contacto

Cómo 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]

Detección de Eventos: Escucha los eventos del ciclo de vida del cliente desde tu plataforma
Mapeo de Datos: Mapea los campos de la plataforma a los atributos de contacto de Brevo
Sincronización por API: Crea, actualiza o elimina contactos mediante la API de Brevo
Manejo de Errores: Reintenta operaciones fallidas con retroceso exponencial

Configuración

Configuración 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

Mapeo de Campos

Mapea los campos de cliente de tu plataforma a los atributos de contacto de Brevo:

Mapeos de Campos Predeterminados

Parameter	Type	Description
`email` required	string	Dirección de email del cliente. Se utiliza como identificador único en Brevo.
`firstName` optional	string	Nombre del cliente. Se mapea al atributo FIRSTNAME. Default: `FIRSTNAME`
`lastName` optional	string	Apellido del cliente. Se mapea al atributo LASTNAME. Default: `LASTNAME`
`phone` optional	string	Número de teléfono en formato E.164. Se mapea al atributo SMS para WhatsApp/SMS. Default: `SMS`
`acceptsMarketing` optional	boolean	Estado de opt-in de marketing. Controla el estado de suscripción al email. Default: `true`

Atributos Personalizados

Agrega mapeos de atributos personalizados para datos 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

Crea los atributos primero

Crea los atributos primero: Los atributos personalizados deben crearse en Brevo antes de poder sincronizarse. Usa el panel o la API de Brevo para crearlos.

Triggers

customer_created

Se dispara cuando se crea un nuevo cliente en tu 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

Se dispara cuando se modifica la información del cliente.

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

customer_deleted

Se dispara cuando se elimina un cliente de tu plataforma.

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

Acciones

Crear Contacto

Crea un nuevo contacto en Brevo cuando se crea un cliente.

Crea un nuevo contacto en tu cuenta de Brevo

Query Parameters

Parameter	Description
email string required	Dirección de email del contacto
attributes object optional	Atributos del contacto
listIds array optional	IDs de listas a las que añadir el contacto
updateEnabled boolean optional	Actualizar si el contacto existe Default: `false`

Responses

201 Contacto creado correctamente

400 Parámetros de solicitud inválidos

409 El contacto ya existe

Actualizar Contacto

Actualiza un contacto existente cuando cambian los datos del cliente.

Actualiza los atributos de un contacto existente

Path Parameters

Parameter	Description
identifier string required	Email o ID del contacto

Query Parameters

Parameter	Description
attributes object optional	Atributos a actualizar
listIds array optional	Listas a las que añadir el contacto
unlinkListIds array optional	Listas de las que eliminar el contacto

Responses

204 Contacto actualizado correctamente

400 Parámetros de solicitud inválidos

404 Contacto no encontrado

Eliminar Contacto

Elimina un contacto cuando se elimina un cliente.

Elimina permanentemente un contacto de Brevo

Path Parameters

Parameter	Description
identifier string required	Email o ID del contacto

Responses

204 Contacto eliminado correctamente

404 Contacto no encontrado

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

Monitoreo

Panel de Estado de Sincronización

Monitorea el rendimiento de sincronización en el panel de Tajo:

Tasa de Éxito de Sincronización: Porcentaje de sincronizaciones exitosas
Latencia Promedio: Tiempo desde el evento hasta la actualización en Brevo
Tasa de Errores: Intentos de sincronización fallidos
Profundidad de Cola: Operaciones de sincronización pendientes

Notificaciones por Webhook

Recibe notificaciones de eventos de sincronización:

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

Solución de Problemas

Problemas Comunes

El contacto ya existe (409)

Habilita updateEnabled: true en tu configuración para actualizar los contactos existentes en lugar de fallar.

Error	Causa	Solución
`Contact already exists`	Ya existe un contacto con ese email	Habilita `updateEnabled: true`
`Invalid attribute`	El atributo no existe en Brevo	Crea primero el atributo en Brevo
`Rate limit exceeded`	Demasiadas solicitudes a la API	Usa el modo de sincronización por lotes
`Invalid email format`	Dirección de email malformada	Valida los emails antes de sincronizar

Modo Debug

Habilita el registro de depuración para solucionar problemas:

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

Skills Relacionadas

Eventos de Pedidos - Sincroniza datos de pedidos
Catálogo de Productos - Sincroniza datos de productos
Eventos de Carrito - Rastrea la actividad del carrito

Próximos Pasos

Configura los mapeos de campos para tu plataforma
Configura atributos personalizados en Brevo
Habilita la sincronización en tiempo real para actualizaciones instantáneas

Sincronización de Clientes