Stripe コネクター

Stripe コネクター

Stripe アカウントを Tajo 経由で Brevo に接続して、完全な決済データ同期、サブスクリプションのライフサイクル管理、売上ドリブンなマーケティングオートメーションを実現します。

概要

項目
プラットフォームStripe
カテゴリーeコマース
セットアップ難易度容易
公式統合あり
同期データ顧客、決済、サブスクリプション、請求書、イベント
API ベース URLhttps://api.stripe.com/v1

機能

  • 顧客同期 - Stripe の顧客をメタデータも含めて Brevo コンタクトに同期
  • 決済追跡 - 成功した決済、返金、失敗した課金を追跡
  • サブスクリプション管理 - リテンションキャンペーン向けにサブスクリプションライフサイクルイベントを同期
  • 請求書データ - 購入後や更新の自動化に請求書情報を同期
  • 売上アトリビューション - 生涯価値や MRR を Brevo 属性にマッピング
  • ウェブフックイベント - すべての決済アクティビティのリアルタイム通知
  • マルチ通貨対応 - 複数通貨の決済を処理
  • チェックアウトセッション追跡 - Stripe Checkout を追跡して放棄決済の回復を支援

前提条件

開始する前に、以下をご用意ください。

  1. API アクセス付きの Stripe アカウント
  2. Stripe API キー (公開可能キーとシークレットキー)
  3. API アクセス付きの Brevo アカウント
  4. Tajo アカウント

認証

API キー認証

Stripe はシークレット API キーを使ったベアラートークン認証を使用します。

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

API キーのセキュリティ

シークレットキーをクライアントサイドのコードに絶対に公開しないでください。フロントエンドには公開可能キーを使用し、シークレットキーはサーバー側のみで使用します。

制限付き 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 コンタクト属性にマッピングします。

既定のマッピング

Parameter Type Description
email required
string

顧客のメールアドレス (一意の識別子)

name optional
string

顧客のフルネーム、FIRSTNAME/LASTNAME に分割

phone optional
string

WhatsApp/SMS 用の SMS 属性にマッピング

currency optional
string

顧客の既定通貨

created optional
timestamp

Stripe での顧客作成日

metadata optional
object

Stripe からのカスタムキーバリューメタデータ

subscriptions optional
array

有効なサブスクリプションの詳細

balance optional
integer

顧客アカウント残高 (セント単位)

カスタム属性マッピング

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 エンドポイント

コアエンドポイント

メソッドエンドポイント説明
GET/v1/customersすべての顧客を一覧取得
POST/v1/customers顧客を作成
GET/v1/customers/{id}顧客を取得
POST/v1/customers/{id}顧客を更新
GET/v1/chargesすべての課金を一覧取得
GET/v1/payment_intents支払いインテントを一覧取得

サブスクリプションエンドポイント

メソッドエンドポイント説明
GET/v1/subscriptionsサブスクリプション一覧を取得
GET/v1/subscriptions/{id}サブスクリプションを取得
GET/v1/invoices請求書一覧を取得
GET/v1/invoices/upcoming予定された請求書を取得
GET/v1/products商品一覧を取得
GET/v1/prices価格一覧を取得

イベントエンドポイント

メソッドエンドポイント説明
GET/v1/eventsイベント一覧を取得
GET/v1/events/{id}イベントを取得

イベント

決済イベント

イベントトリガー用途
payment_intent.succeeded決済完了注文確認
payment_intent.payment_failed決済失敗回復メール
charge.refunded返金処理返金通知
charge.dispute.createdチャージバック発生ディスピュート対応

サブスクリプションイベント

イベントトリガー用途
customer.subscription.created新規サブスクリプションオンボーディングフロー
customer.subscription.updatedプラン変更アップグレード/ダウングレードフロー
customer.subscription.deletedサブスクリプション解約解約予防
customer.subscription.trial_will_endトライアル終了 3 日前トライアル転換キャンペーン
invoice.payment_failedサブスクリプション決済失敗督促メールシーケンス

顧客イベント

イベントトリガー用途
customer.created新規顧客追加ウェルカムメール
customer.updated顧客データ変更属性同期
customer.deleted顧客削除クリーンアップ

コード例

コネクターの初期化

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 は以下のレート制限を適用します。

種類制限詳細
ライブモード100 読取リクエスト/秒シークレットキーごと
ライブモード100 書込リクエスト/秒シークレットキーごと
テストモード25 リクエスト/秒シークレットキーごと
ウェブフック配信100,000 イベント/日エンドポイントごと

レート制限の処理

Stripe は制限超過時に 429 Too Many Requests を返します。指数バックオフを実装してください。バルクデータ取得には自動ページネーション対応のリストエンドポイントを活用してください。

トラブルシューティング

よくある問題

問題原因解決策
401 Unauthorized無効な API キーStripe Dashboard でシークレットキーを確認
ウェブフック署名失敗ウェブフックシークレットが不正Dashboard からウェブフック署名シークレットを再コピー
顧客が同期されないStripe 顧客にメールがないStripe 顧客レコードにメールアドレスを設定
サブスクリプションデータが欠落権限不足制限付きキーの権限を更新
重複イベントウェブフックの再配信イベント ID による冪等性を実装

デバッグモード

詳細ログを有効化します。

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

接続テスト

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

ベストプラクティス

  1. 制限付き API キーを使用 - 必要最小限の権限のキーを作成
  2. 常にウェブフック署名を検証 - なりすましイベントを防止
  3. 冪等性を担保 - Stripe イベント ID で重複処理を防ぐ
  4. 顧客メタデータを同期 - マーケティング関連データを Stripe メタデータに格納
  5. ウェブフック配信を監視 - Stripe Dashboard で失敗した配信を確認
  6. まずテストモードで検証 - Stripe テストモードとテストクロックで統合を検証

セキュリティ

  • API キー認証 - シークレットキーベースのアクセス、制限付きキー対応
  • ウェブフック署名検証 - HMAC SHA-256 署名検証
  • TLS 暗号化 - すべての API 通信を HTTPS で暗号化
  • PCI 準拠 - Stripe が決済データの PCI DSS 準拠を担保
  • IP ホワイトリスト - API アクセスの任意の IP 制限

関連リソース

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

AIアシスタント

こんにちは!ドキュメントについて何でもお聞きください。

Brevoで無料で始める