Connettore Stripe

Connettore Stripe

Collega il tuo account Stripe a Brevo tramite Tajo per una sincronizzazione completa dei dati di pagamento, la gestione del ciclo di vita degli abbonamenti e l’automazione marketing basata sui ricavi.

Panoramica

Funzionalità

• Sincronizzazione clienti - Sincronizza i clienti Stripe con i contatti Brevo inclusi i metadati
• Tracciamento pagamenti - Traccia pagamenti riusciti, rimborsi e addebiti falliti
• Gestione abbonamenti - Sincronizza gli eventi del ciclo di vita degli abbonamenti per campagne di retention
• Dati delle fatture - Sincronizza i dettagli delle fatture per automazioni post-acquisto e di rinnovo
• Attribuzione dei ricavi - Mappa lifetime value e MRR agli attributi Brevo
• Eventi webhook - Notifiche in tempo reale per tutte le attività di pagamento
• Supporto multi-valuta - Gestisci pagamenti in più valute
• Tracciamento sessioni di checkout - Traccia Stripe Checkout per il recupero dei pagamenti abbandonati

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Stripe con accesso API
2. Chiavi API Stripe (chiavi publishable e secret)
3. Un account Brevo con accesso API
4. Un account Tajo

Autenticazione

Autenticazione tramite API Key

Stripe utilizza l’autenticazione bearer token con la tua chiave API secret.

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

API Key con restrizioni

Crea chiavi con restrizioni e permessi specifici per maggiore sicurezza:

1. Vai nella Stripe Dashboard > Developers > API Keys
2. Clicca su “Create restricted key”
3. Concedi solo i permessi che Tajo richiede

Permessi richiesti

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

Configurazione

Setup di base

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

Mappatura dei campi

Mappa i dati cliente Stripe agli attributi di contatto Brevo:

Mappatura attributi personalizzati

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

Endpoint API

Endpoint principali

Endpoint abbonamenti

Endpoint eventi

Eventi

Eventi di pagamento

Eventi di abbonamento

Eventi cliente

Esempi di codice

Inizializza il connettore

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

Esegui sincronizzazione clienti

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

Gestisci i webhook di 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 });
});

Limiti di velocità

Stripe applica i seguenti limiti di velocità:

Risoluzione dei problemi

Problemi comuni

Modalità debug

Abilita il logging dettagliato:

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

Testa la connessione

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

Best practice

1. Usa chiavi API con restrizioni - Crea chiavi con i permessi minimi richiesti
2. Verifica sempre le firme dei webhook - Previeni eventi webhook falsificati
3. Gestisci l’idempotenza - Usa gli ID degli eventi Stripe per prevenire elaborazioni duplicate
4. Sincronizza i metadati cliente - Archivia dati rilevanti per il marketing nei campi metadata di Stripe
5. Monitora la consegna dei webhook - Controlla la Stripe Dashboard per consegne fallite
6. Usa prima la modalità test - Convalida la tua integrazione con la modalità test di Stripe e i test clock

Sicurezza

• Autenticazione API Key - Accesso basato su secret key con supporto per chiavi con restrizioni
• Verifica firma webhook - Validazione firma HMAC SHA-256
• Cifratura TLS - Tutte le comunicazioni API cifrate tramite HTTPS
• Conformità PCI - Stripe gestisce la conformità PCI DSS per i dati di pagamento
• IP whitelisting - Restrizioni IP opzionali per l’accesso API

Risorse correlate

• Documentazione API Stripe
• Guida ai webhook di Stripe
• Connettore Shopify
• Skill Customer Sync
• API Contatti Brevo