Stripe конектор

Stripe конектор

Свържи своя акаунт в Stripe с Brevo чрез Tajo за пълна синхронизация на данни за плащания, управление на жизнения цикъл на абонаментите и маркетингова автоматизация, задвижвана от приходи.

Преглед

Функции

• Синхронизация на клиенти – Синхронизирай клиентите от Stripe с контактите в Brevo, включително метаданни
• Проследяване на плащания – Проследявай успешни плащания, рефанди и неуспешни chargeове
• Управление на абонаменти – Синхронизирай събития от жизнения цикъл на абонамент за кампании за задържане
• Данни за фактури – Синхронизирай детайли от фактури за автоматизация след покупка и подновяване
• Атрибуция на приходи – Мапвай lifetime value и MRR към атрибути в Brevo
• Уебхук събития – Известия в реално време за всички дейности по плащания
• Поддръжка на много валути – Обработка на плащания в множество валути
• Проследяване на checkout сесии – Проследявай Stripe Checkout за възстановяване на изоставени плащания

Предварителни условия

Преди да започнеш, увери се, че имаш:

1. Акаунт в Stripe с API достъп
2. API ключове на Stripe (publishable и secret ключове)
3. Акаунт в Brevo с API достъп
4. Акаунт в Tajo

Автентикация

Автентикация с API ключ

Stripe използва bearer token автентикация с твоя secret API ключ.

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

Ограничени API ключове

Създавай ограничени ключове с конкретни разрешения за повишена сигурност:

1. Отиди в Stripe Dashboard > Developers > API Keys
2. Щракни върху “Create restricted key”
3. Предостави само разрешенията, които Tajo изисква

Необходими разрешения

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

Конфигурация

Основна настройка

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

Мапване на полета

Мапвай данни за клиенти в Stripe към атрибути на контактите в Brevo:

Мапване на персонализирани атрибути

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

API крайни точки

Основни крайни точки

Крайни точки за абонаменти

Крайни точки за събития

Събития

Събития от плащания

Събития от абонаменти

Клиентски събития

Примери с код

Инициализация на конектора

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

Стартиране на синхронизация на клиенти

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

Обработка на 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 });
});

Ограничения на заявките

Stripe налага следните ограничения на заявките:

Отстраняване на проблеми

Чести проблеми

Режим за дебъг

Активирай подробно логване:

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

Тест на връзката

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

Добри практики

1. Използвай ограничени API ключове – Създавай ключове с минимално необходимите разрешения
2. Винаги верифицирай подписите на уебхуците – Предотвратявай подправени уебхук събития
3. Обработвай idempotency – Използвай Stripe event IDs, за да предотвратиш дублирана обработка
4. Синхронизирай клиентски метаданни – Съхранявай маркетингово релевантни данни в metadata полета на Stripe
5. Мониторирай доставката на уебхуци – Проверявай Stripe Dashboard за неуспешни доставки
6. Първо използвай test mode – Валидирай интеграцията с Stripe test mode и test clocks

Сигурност

• Автентикация с API ключ – Достъп на база secret key с поддръжка на ограничени ключове
• Верификация на подпис на уебхук – HMAC SHA-256 валидация на подпис
• TLS криптиране – Цялата API комуникация е криптирана чрез HTTPS
• PCI съвместимост – Stripe осигурява PCI DSS съвместимост за данни за плащания
• IP whitelisting – Опционални IP ограничения за API достъп

Свързани ресурси

• Stripe API документация
• Ръководство за Stripe Webhooks
• Shopify конектор
• Customer Sync скил
• Brevo Contacts API