Konektor Stripe

Konektor Stripe

Propojte svůj účet Stripe s Brevo přes Tajo pro kompletní synchronizaci platebních dat, správu životního cyklu předplatného a marketingovou automatizaci řízenou příjmy.

Přehled

Funkce

• Synchronizace zákazníků – Synchronizujte zákazníky Stripe s kontakty Brevo včetně metadat
• Sledování plateb – Sledujte úspěšné platby, refundace a neúspěšné transakce
• Správa předplatného – Synchronizujte události životního cyklu předplatného pro retentní kampaně
• Data faktur – Synchronizujte podrobnosti faktur pro automatizaci po nákupu a obnovení
• Přiřazení příjmů – Mapujte celoživotní hodnotu a MRR na atributy Brevo
• Webhookové události – Notifikace o událostech v reálném čase pro všechny platební aktivity
• Podpora více měn – Zpracovávejte platby ve více měnách
• Sledování checkout relací – Sledujte Stripe Checkout pro obnovu opuštěných plateb

Předpoklady

Než začnete, ujistěte se, že máte:

1. Účet Stripe s přístupem k API
2. API klíče Stripe (veřejný a tajný klíč)
3. Účet Brevo s přístupem k API
4. Účet Tajo

Ověření

Ověření API klíčem

Stripe používá ověřování bearer tokenem s vaším tajným API klíčem.

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

Omezené API klíče

Vytvářejte omezené klíče s konkrétními oprávněními pro zvýšenou bezpečnost:

1. Přejděte do Stripe Dashboard > Developers > API Keys
2. Klikněte na “Create restricted key”
3. Udělte pouze oprávnění, která Tajo vyžaduje

Požadovaná oprávnění

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

Konfigurace

Základní nastavení

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

    # Možnosti synchronizace dat
    sync:
      customers: true
      payments: true
      subscriptions: true
      invoices: true
      products: true

    # Přiřazení seznamů Brevo
    lists:
      all_customers: 20
      subscribers: 21
      churned: 22

Mapování polí

Mapujte zákaznická data Stripe na atributy kontaktů Brevo:

Mapování vlastních atributů

field_mapping:
  # Standardní pole
  email: email
  name: FULLNAME
  phone: SMS

  # Platební metriky
  total_spent: TOTAL_SPENT
  payment_count: PAYMENT_COUNT
  last_payment_date: LAST_PAYMENT_DATE
  average_order_value: AOV

  # Pole předplatného
  subscription_status: SUB_STATUS
  plan_name: PLAN_NAME
  mrr: MONTHLY_REVENUE
  subscription_start: SUB_START_DATE

  # Vlastní metadata
  metadata.customer_tier: VIP_TIER
  metadata.referral_source: REFERRAL_SOURCE

Koncové body API

Základní koncové body

Koncové body předplatného

Koncové body událostí

Události

Platební události

Události předplatného

Zákaznické události

Příklady kódu

Inicializace konektoru

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

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

// Připojení Stripe
await tajo.connectors.connect('stripe', {
  secretKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
});

Spuštění synchronizace zákazníků

// Úplná historická synchronizace
await tajo.connectors.sync('stripe', {
  type: 'full',
  resources: ['customers', 'subscriptions', 'payments'],
  since: '2023-01-01'
});

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

Zpracování webhooků 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}`);
  }

  // Přepošlete do Tajo pro synchronizaci s Brevo
  await tajo.connectors.handleWebhook('stripe', {
    type: event.type,
    data: event.data.object
  });

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

Omezení rychlosti

Stripe vynucuje následující limity rychlosti:

Řešení problémů

Časté problémy

Režim ladění

Povolte podrobné protokolování:

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

Test připojení

tajo connectors test stripe
# ✓ Připojení API úspěšné
# ✓ Zákazníci čitelní
# ✓ Předplatná čitelná
# ✓ Platby čitelné
# ✓ Webhookový koncový bod ověřen

Osvědčené postupy

1. Používejte omezené API klíče – Vytvářejte klíče s minimálními požadovanými oprávněními
2. Vždy ověřujte podpisy webhooků – Zabraňte zfalšovaným webhookovým událostem
3. Zpracovávejte idempotenci – Používejte ID událostí Stripe pro prevenci duplicitního zpracování
4. Synchronizujte metadata zákazníků – Ukládejte data relevantní pro marketing do polí metadat Stripe
5. Monitorujte doručení webhooků – Kontrolujte Stripe Dashboard pro neúspěšná doručení
6. Nejprve použijte testovací režim – Ověřte svou integraci pomocí testovacího režimu Stripe a testovacích hodin

Zabezpečení

• Ověřování API klíčem – Přístup na základě tajného klíče s podporou omezeného klíče
• Ověření podpisu webhooku – Ověření podpisu HMAC SHA-256
• Šifrování TLS – Veškerá API komunikace šifrovaná přes HTTPS
• Soulad s PCI – Stripe zajišťuje soulad s PCI DSS pro platební data
• Whitelisting IP – Volitelná IP omezení pro přístup k API

Související zdroje

• Dokumentace Stripe API
• Průvodce webhooky Stripe
• Konektor Shopify
• Dovednost synchronizace zákazníků
• Brevo Contacts API