Conector de Stripe

Conector de Stripe

Conecta tu cuenta de Stripe con Brevo a través de Tajo para una sincronización completa de los datos de pago, la gestión del ciclo de vida de las suscripciones y la automatización del marketing basada en ingresos.

Resumen

Funcionalidades

• Sincronización de clientes - Sincroniza los clientes de Stripe con los contactos de Brevo, incluidos sus metadatos
• Seguimiento de pagos - Rastrea pagos exitosos, reembolsos y cargos fallidos
• Gestión de suscripciones - Sincroniza eventos del ciclo de vida de la suscripción para campañas de retención
• Datos de facturas - Sincroniza los detalles de las facturas para automatizar mensajes post-compra y renovaciones
• Atribución de ingresos - Asocia el valor de vida y el MRR a atributos de Brevo
• Eventos de webhook - Notificaciones de eventos en tiempo real para todas las actividades de pago
• Soporte multi-moneda - Gestiona pagos en varias monedas
• Seguimiento de Checkout sessions - Rastrea Stripe Checkout para recuperar pagos abandonados

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de Stripe con acceso a la API
2. Las claves API de Stripe (publishable key y secret key)
3. Una cuenta de Brevo con acceso a la API
4. Una cuenta de Tajo

Autenticación

Autenticación por clave API

Stripe usa autenticación bearer con tu secret key.

curl https://api.stripe.com/v1/customers \
  -u sk_live_YOUR_SECRET_KEY:

Claves API restringidas

Crea claves restringidas con permisos específicos para una seguridad mayor:

1. Ve a Stripe Dashboard > Developers > API Keys
2. Haz clic en “Create restricted key”
3. Concede solo los permisos que Tajo necesita

Permisos requeridos

customers: read
charges: read
payment_intents: read
subscriptions: read
invoices: read
events: read
products: read
prices: read

Configuración

Configuración básica

connectors:
  stripe:
    enabled: true
    secret_key: "${STRIPE_SECRET_KEY}"
    webhook_secret: "${STRIPE_WEBHOOK_SECRET}"

    # Data sync options
    sync:
      customers: true
      payments: true
      subscriptions: true
      invoices: true
      products: true

    # Brevo list assignment
    lists:
      all_customers: 20
      subscribers: 21
      churned: 22

Asignación de campos

Asocia los datos de cliente de Stripe con los atributos de contacto de Brevo:

Asignación de atributos personalizados

field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Payment metrics
  total_spent: TOTAL_SPENT
  payment_count: PAYMENT_COUNT
  last_payment_date: LAST_PAYMENT_DATE
  average_order_value: AOV

  # Subscription fields
  subscription_status: SUB_STATUS
  plan_name: PLAN_NAME
  mrr: MONTHLY_REVENUE
  subscription_start: SUB_START_DATE

  # Custom metadata
  metadata.customer_tier: VIP_TIER
  metadata.referral_source: REFERRAL_SOURCE

Endpoints de la API

Endpoints principales

Endpoints de suscripción

Endpoints de eventos

Eventos

Eventos de pago

Eventos de suscripción

Eventos de cliente

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 Stripe
await tajo.connectors.connect('stripe', {
  secretKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
});

Ejecutar la sincronización de clientes

// Full historical sync
await tajo.connectors.sync('stripe', {
  type: 'full',
  resources: ['customers', 'subscriptions', 'payments'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('stripe');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   customersSynced: 12500,
//   subscriptionsSynced: 8200,
//   paymentsSynced: 45000
// }

Gestionar webhooks de Stripe

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

app.post('/webhooks/stripe', async (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Forward to Tajo for Brevo sync
  await tajo.connectors.handleWebhook('stripe', {
    type: event.type,
    data: event.data.object
  });

  res.status(200).json({ received: true });
});

Límites de velocidad

Stripe aplica los siguientes límites de velocidad:

Resolución de problemas

Problemas habituales

Modo depuración

Habilita el logging detallado:

connectors:
  stripe:
    debug: true
    log_level: verbose
    log_webhooks: true

Probar la conexión

tajo connectors test stripe
# ✓ API connection successful
# ✓ Customers readable
# ✓ Subscriptions readable
# ✓ Payments readable
# ✓ Webhook endpoint verified

Buenas prácticas

1. Usa claves API restringidas - Crea claves con los permisos mínimos necesarios
2. Verifica siempre las firmas de los webhooks - Evita eventos de webhook falsificados
3. Gestiona la idempotencia - Usa los IDs de evento de Stripe para evitar procesamiento duplicado
4. Sincroniza los metadatos del cliente - Guarda los datos útiles para marketing en los metadata fields de Stripe
5. Monitoriza la entrega de webhooks - Revisa el Stripe Dashboard para entregas fallidas
6. Prueba primero en modo test - Valida tu integración con el modo test de Stripe y los test clocks

Seguridad

• Autenticación por clave API - Acceso basado en secret key con soporte para claves restringidas
• Verificación de firma de webhook - Validación de firma HMAC SHA-256
• Cifrado TLS - Toda la comunicación con la API se cifra vía HTTPS
• Cumplimiento PCI - Stripe gestiona el cumplimiento de PCI DSS para los datos de pago
• Whitelisting de IPs - Restricciones opcionales de IP para el acceso a la API

Recursos relacionados

• Documentación de la API de Stripe
• Guía de webhooks de Stripe
• Conector de Shopify
• Skill de sincronización de clientes
• API de contactos de Brevo