Conector de Brevo

Conector de Brevo

Conecta tu cuenta de Brevo con Tajo para unificar la gestión de contactos, la mensajería transaccional por email, SMS y WhatsApp, y una automatización de marketing integral.

Resumen

Funcionalidades

• Mensajería multicanal - Envía email transaccional, SMS y WhatsApp desde una API unificada
• Gestión de contactos - Crea, actualiza y segmenta contactos con atributos personalizados
• Campañas de marketing - Crea y envía campañas de email de forma programática
• Seguimiento de eventos - Registra eventos personalizados y actividad web a través de Brevo Tracker
• Sincronización eCommerce - Sincroniza productos, pedidos y datos de carrito para campañas personalizadas
• Programas de fidelización - Gestiona suscripciones de fidelización, puntos y datos de miembros
• Soporte de webhooks - Notificaciones de eventos en tiempo real para eventos transaccionales, de marketing y de CRM
• Conversations - Integración del widget de chat en vivo y gestión programática de mensajes

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de Brevo (plan Free, Starter, Business o Enterprise)
2. Una clave API generada en Brevo Settings > API Keys
3. Una cuenta de Tajo con acceso a la API
4. Un dominio remitente verificado para el envío de emails

Autenticación

Brevo admite dos métodos de autenticación:

Autenticación con clave API (recomendada)

Incluye tu clave API en la cabecera api-key con cada petición. Es la mejor opción para integraciones directas y comunicación servidor a servidor.

curl -X GET "https://api.brevo.com/v3/account" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Autenticación OAuth 2.0

Usa OAuth 2.0 para integraciones privadas dentro de una organización que requieran acceso delegado y permisos específicos por usuario. OAuth proporciona un sistema basado en tokens con periodos de validez definidos.

Configuración

Configuración básica

connectors:
  brevo:
    enabled: true
    api_key: "${BREVO_API_KEY}"
    api_version: "v3"

    # Data sync options
    sync:
      contacts: true
      campaigns: true
      transactional: true
      events: true
      ecommerce: true

    # List assignment
    lists:
      all_customers: 5
      newsletter: 6
      buyers: 7

Asignación de campos

Asocia los campos de tus datos con los atributos de contacto de Brevo:

Asignación de atributos personalizados

field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Marketing fields
  opt_in: OPT_IN
  signup_source: SIGNUP_SOURCE
  preferred_language: LANGUAGE

  # eCommerce metrics
  orders_count: ORDER_COUNT
  total_spent: TOTAL_REVENUE
  last_order_date: LAST_ORDER_DATE

  # Loyalty fields
  loyalty_tier: VIP_TIER
  loyalty_points: LOYALTY_POINTS

Endpoints de la API

Endpoints principales

Endpoints eCommerce

Endpoints de campaña

Eventos

Eventos transaccionales

Eventos eCommerce

Ejemplos de código

Inicializar el conector

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

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

// Connect Brevo account
await tajo.connectors.connect('brevo', {
  apiKey: process.env.BREVO_API_KEY
});

Enviar email transaccional

// Send a transactional email via Brevo
await tajo.brevo.sendTransactionalEmail({
  to: [{ email: '[email protected]', name: 'John Doe' }],
  templateId: 12,
  params: {
    ORDER_ID: '12345',
    ORDER_TOTAL: '$59.99',
    DELIVERY_DATE: '2024-02-15'
  }
});

Sincronizar contactos

// Bulk import contacts to Brevo
await tajo.connectors.sync('brevo', {
  type: 'full',
  resources: ['contacts'],
  options: {
    listIds: [5, 6],
    updateExisting: true,
    emptyContactsAttributes: false
  }
});

// Check sync status
const status = await tajo.connectors.status('brevo');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 25400,
//   campaignsSent: 142,
//   eventsTracked: 89320
// }

Registrar eventos personalizados

// Track a custom event for a contact
await tajo.brevo.trackEvent({
  email: '[email protected]',
  event: 'product_purchased',
  eventdata: {
    id: 'txn_98765',
    data: {
      product_name: 'Premium Widget',
      price: 49.99,
      currency: 'USD'
    }
  }
});

Límites de velocidad

Brevo aplica límites de velocidad en tres niveles según tu plan:

Resolución de problemas

Problemas habituales

Modo depuración

Activa el registro detallado:

connectors:
  brevo:
    debug: true
    log_level: verbose
    log_webhooks: true

Probar la conexión

tajo connectors test brevo
# ✓ API connection successful
# ✓ Contacts API accessible
# ✓ Transactional email ready
# ✓ SMS sending configured
# ✓ Webhooks registered

Buenas prácticas

1. Rota las claves API - Rota las claves API periódicamente por seguridad
2. Verifica los webhooks - Valida las firmas de webhook con autenticación usuario/contraseña
3. Agrupa las importaciones de contactos - Usa la importación masiva para grandes conjuntos de datos en vez de llamadas individuales
4. Monitoriza los límites de velocidad - Consulta las cabeceras de límite para evitar errores 429
5. Usa el seguimiento de eventos - Implementa Brevo Tracker para tener datos completos del comportamiento del cliente
6. Configura la autenticación del remitente - Configura SPF, DKIM y DMARC para optimizar la entregabilidad

Seguridad

• Autenticación con clave API - Acceso basado en token secreto mediante la cabecera api-key
• OAuth 2.0 - Acceso delegado basado en tokens para integraciones privadas
• Verificación de webhooks - Autenticación con usuario y contraseña para llamadas de webhook seguras
• Cifrado TLS - Toda la comunicación con la API se cifra en tránsito
• Lista blanca de IPs - Restricciones de IP opcionales disponibles en planes Enterprise

Recursos relacionados

• Documentación de la API de Brevo
• Guía de autenticación de Brevo
• Límites de velocidad de Brevo
• Conector de Shopify
• Skill de sincronización de clientes
• API de contactos de Brevo