Conector Stripe

Conector Stripe

Conecte sua conta Stripe ao Brevo via Tajo para sincronização completa de dados de pagamento, gestão do ciclo de vida de assinaturas e automação de marketing orientada por receita.

Visão geral

Recursos

• Sincronização de clientes - Sincronize clientes do Stripe com contatos do Brevo incluindo metadados
• Rastreamento de pagamentos - Rastreie pagamentos bem-sucedidos, reembolsos e cobranças que falharam
• Gestão de assinaturas - Sincronize eventos do ciclo de vida de assinaturas para campanhas de retenção
• Dados de faturas - Sincronize detalhes de faturas para automação pós-compra e de renovação
• Atribuição de receita - Mapeie o valor vitalício e o MRR para atributos do Brevo
• Eventos por webhook - Notificações de eventos em tempo real para todas as atividades de pagamento
• Suporte multi-moeda - Gerencie pagamentos em várias moedas
• Rastreamento de sessões de checkout - Rastreie o Stripe Checkout para recuperação de pagamento abandonado

Pré-requisitos

Antes de começar, certifique-se de ter:

1. Uma conta Stripe com acesso à API
2. Chaves de API do Stripe (publishable e secret keys)
3. Uma conta Brevo com acesso à API
4. Uma conta Tajo

Autenticação

Autenticação por chave de API

O Stripe usa autenticação por bearer token com sua chave de API secreta.

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

Chaves de API restritas

Crie chaves restritas com permissões específicas para maior segurança:

1. Acesse Stripe Dashboard > Developers > API Keys
2. Clique em “Create restricted key”
3. Conceda apenas as permissões que o Tajo precisa

Permissões necessárias

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

Configuração

Configuração 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

Mapeamento de campos

Mapeie dados de clientes do Stripe para atributos de contato do Brevo:

Mapeamento 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 da API

Endpoints principais

Endpoints de assinatura

Endpoints de eventos

Eventos

Eventos de pagamento

Eventos de assinatura

Eventos de cliente

Exemplos de código

Inicializar o 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
});

Executar sincronização 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
// }

Tratar webhooks do 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 });
});

Limites de taxa

O Stripe aplica os seguintes limites de taxa:

Solução de problemas

Problemas comuns

Modo de depuração

Habilite logging detalhado:

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

Testar conexão

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

Melhores práticas

1. Use chaves de API restritas - Crie chaves com as permissões mínimas necessárias
2. Sempre verifique assinaturas de webhook - Previna eventos de webhook forjados
3. Trate a idempotência - Use IDs de evento do Stripe para evitar processamento duplicado
4. Sincronize metadados do cliente - Armazene dados relevantes para marketing nos campos de metadata do Stripe
5. Monitore a entrega de webhooks - Verifique o Stripe Dashboard para entregas que falharam
6. Use o modo test primeiro - Valide sua integração com o modo test e test clocks do Stripe

Segurança

• Autenticação por chave de API - Acesso baseado em chave secreta com suporte a chaves restritas
• Verificação de assinatura de webhook - Validação de assinatura HMAC SHA-256
• Criptografia TLS - Toda comunicação com a API é criptografada via HTTPS
• Conformidade PCI - O Stripe cuida da conformidade PCI DSS para dados de pagamento
• Whitelisting de IP - Restrições de IP opcionais para acesso à API

Recursos relacionados

• Documentação da API Stripe
• Guia de webhooks do Stripe
• Conector Shopify
• Skill de sincronização de clientes
• API de contatos do Brevo