Konektor Stripe

Konektor Stripe

Połącz swoje konto Stripe z Brevo przez Tajo dla pełnej synchronizacji danych płatności, zarządzania cyklem życia subskrypcji i automatyzacji marketingu opartej na przychodach.

Przegląd

Funkcje

• Synchronizacja klientów - Synchronizuj klientów Stripe z kontaktami Brevo wraz z metadanymi
• Śledzenie płatności - Śledź udane płatności, zwroty i nieudane obciążenia
• Zarządzanie subskrypcjami - Synchronizuj zdarzenia cyklu życia subskrypcji dla kampanii retencyjnych
• Dane faktur - Synchronizuj szczegóły faktur dla automatyzacji po zakupie i przy odnowieniu
• Atrybucja przychodów - Mapuj wartość życiową i MRR na atrybuty Brevo
• Zdarzenia webhooków - Powiadomienia o zdarzeniach w czasie rzeczywistym dla wszystkich aktywności płatniczych
• Obsługa wielu walut - Obsługuj płatności w wielu walutach
• Śledzenie sesji Checkout - Śledź Stripe Checkout dla odzyskiwania porzuconych płatności

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

1. Konto Stripe z dostępem do API
2. Klucze API Stripe (klucz publiczny i sekretny)
3. Konto Brevo z dostępem do API
4. Konto Tajo

Uwierzytelnianie

Uwierzytelnianie kluczem API

Stripe używa uwierzytelniania tokenem bearer z Twoim sekretnym kluczem API.

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

Ograniczone klucze API

Twórz ograniczone klucze z określonymi uprawnieniami dla zwiększonego bezpieczeństwa:

1. Przejdź do Stripe Dashboard > Developers > API Keys
2. Kliknij “Create restricted key”
3. Przyznaj tylko uprawnienia wymagane przez Tajo

Wymagane uprawnienia

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

Konfiguracja

Podstawowa konfiguracja

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

Mapowanie pól

Mapuj dane klientów Stripe na atrybuty kontaktów Brevo:

Niestandardowe mapowanie atrybutów

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

Endpointy API

Główne endpointy

Endpointy subskrypcji

Endpointy zdarzeń

Zdarzenia

Zdarzenia płatności

Zdarzenia subskrypcji

Zdarzenia klientów

Przykłady kodu

Inicjalizacja konektora

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

Uruchom synchronizację klientów

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

Obsługa webhooków 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 });
});

Limity API

Stripe egzekwuje następujące limity szybkości:

Rozwiązywanie problemów

Typowe problemy

Tryb debug

Włącz szczegółowe logowanie:

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

Test połączenia

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

Najlepsze praktyki

1. Używaj ograniczonych kluczy API - Twórz klucze z minimalnymi wymaganymi uprawnieniami
2. Zawsze weryfikuj podpisy webhooków - Zapobiegaj sfałszowanym zdarzeniom webhooków
3. Obsługuj idempotentność - Używaj ID zdarzeń Stripe, aby zapobiec duplikowaniu przetwarzania
4. Synchronizuj metadane klientów - Przechowuj dane istotne dla marketingu w polach metadanych Stripe
5. Monitoruj dostarczanie webhooków - Sprawdzaj Stripe Dashboard pod kątem nieudanych dostarczeń
6. Najpierw używaj trybu testowego - Waliduj integrację z trybem testowym Stripe i zegarami testowymi

Bezpieczeństwo

• Uwierzytelnianie kluczem API - Dostęp oparty na kluczu sekretnym z obsługą ograniczonego klucza
• Weryfikacja podpisu webhooka - Walidacja podpisu HMAC SHA-256
• Szyfrowanie TLS - Cała komunikacja API szyfrowana przez HTTPS
• Zgodność PCI - Stripe obsługuje zgodność PCI DSS dla danych płatności
• Allowlisting IP - Opcjonalne ograniczenia IP dla dostępu API

Powiązane zasoby

• Dokumentacja Stripe API
• Przewodnik webhooków Stripe
• Konektor Shopify
• Skill synchronizacji klientów
• Brevo Contacts API