Коннектор Stripe

Коннектор Stripe

Подключите аккаунт Stripe к Brevo через Tajo для полной синхронизации платёжных данных, управления жизненным циклом подписок и маркетинговой автоматизации на основе данных о выручке.

Обзор

Возможности

• Синхронизация клиентов, синхронизация клиентов Stripe с контактами Brevo, включая метаданные
• Отслеживание платежей, трекинг успешных платежей, возвратов и неудачных списаний
• Управление подписками, синхронизация событий жизненного цикла подписок для кампаний удержания
• Данные по счетам, синхронизация деталей счетов для автоматизации после покупки и при продлении
• Атрибуция выручки, сопоставление LTV и MRR с атрибутами Brevo
• Webhook-события, уведомления о событиях в реальном времени для всех платёжных операций
• Поддержка нескольких валют, обработка платежей в разных валютах
• Отслеживание сессий Checkout, трекинг Stripe Checkout для восстановления незавершённых платежей

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

1. Аккаунт Stripe с доступом к API
2. API-ключи Stripe (публичный и секретный)
3. Аккаунт Brevo с доступом к API
4. Аккаунт Tajo

Аутентификация

Аутентификация по API Key

Stripe использует Bearer-аутентификацию с секретным API-ключом.

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

Ограниченные API Keys

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

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

    # Параметры синхронизации данных
    sync:
      customers: true
      payments: true
      subscriptions: true
      invoices: true
      products: true

    # Назначение листов Brevo
    lists:
      all_customers: 20
      subscribers: 21
      churned: 22

Сопоставление полей

Сопоставьте данные клиентов Stripe с атрибутами контактов Brevo:

Сопоставление пользовательских атрибутов

field_mapping:
  # Стандартные поля
  email: email
  name: FULLNAME
  phone: SMS

  # Метрики платежей
  total_spent: TOTAL_SPENT
  payment_count: PAYMENT_COUNT
  last_payment_date: LAST_PAYMENT_DATE
  average_order_value: AOV

  # Поля подписки
  subscription_status: SUB_STATUS
  plan_name: PLAN_NAME
  mrr: MONTHLY_REVENUE
  subscription_start: SUB_START_DATE

  # Пользовательские метаданные
  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
});

// Подключение Stripe
await tajo.connectors.connect('stripe', {
  secretKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
});

Запуск синхронизации клиентов

// Полная историческая синхронизация
await tajo.connectors.sync('stripe', {
  type: 'full',
  resources: ['customers', 'subscriptions', 'payments'],
  since: '2023-01-01'
});

// Проверка статуса синхронизации
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}`);
  }

  // Пересылка в Tajo для синхронизации с Brevo
  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 Keys, создавайте ключи с минимально необходимыми разрешениями
2. Всегда проверяйте подписи вебхуков, предотвращайте поддельные события вебхуков
3. Обрабатывайте идемпотентность, используйте ID событий Stripe для предотвращения дублирующейся обработки
4. Синхронизируйте метаданные клиентов, храните маркетинговые данные в полях метаданных Stripe
5. Мониторинг доставки вебхуков, проверяйте Stripe Dashboard для выявления неудачных доставок
6. Сначала используйте test mode, валидируйте интеграцию с тестовым режимом и тестовыми часами Stripe

Безопасность

• Аутентификация по API Key, доступ на основе секретных ключей с поддержкой ограниченных ключей
• Верификация подписей вебхуков, HMAC SHA-256 валидация подписей
• TLS-шифрование, все API-коммуникации зашифрованы через HTTPS
• PCI-совместимость, Stripe обеспечивает соответствие PCI DSS для платёжных данных
• IP-разрешение, опциональные IP-ограничения для доступа к API

Связанные ресурсы

• Документация Stripe API
• Руководство по вебхукам Stripe
• Коннектор Shopify
• Скилл синхронизации клиентов
• Brevo Contacts API