Stripe コネクター
Stripe コネクター
Stripe アカウントを Tajo 経由で Brevo に接続して、完全な決済データ同期、サブスクリプションのライフサイクル管理、売上ドリブンなマーケティングオートメーションを実現します。
概要
| 項目 | 値 |
|---|---|
| プラットフォーム | Stripe |
| カテゴリー | eコマース |
| セットアップ難易度 | 容易 |
| 公式統合 | あり |
| 同期データ | 顧客、決済、サブスクリプション、請求書、イベント |
| API ベース URL | https://api.stripe.com/v1 |
機能
- 顧客同期 - Stripe の顧客をメタデータも含めて Brevo コンタクトに同期
- 決済追跡 - 成功した決済、返金、失敗した課金を追跡
- サブスクリプション管理 - リテンションキャンペーン向けにサブスクリプションライフサイクルイベントを同期
- 請求書データ - 購入後や更新の自動化に請求書情報を同期
- 売上アトリビューション - 生涯価値や MRR を Brevo 属性にマッピング
- ウェブフックイベント - すべての決済アクティビティのリアルタイム通知
- マルチ通貨対応 - 複数通貨の決済を処理
- チェックアウトセッション追跡 - Stripe Checkout を追跡して放棄決済の回復を支援
前提条件
開始する前に、以下をご用意ください。
- API アクセス付きの Stripe アカウント
- Stripe API キー (公開可能キーとシークレットキー)
- API アクセス付きの Brevo アカウント
- Tajo アカウント
認証
API キー認証
Stripe はシークレット API キーを使ったベアラートークン認証を使用します。
curl https://api.stripe.com/v1/customers \ -u sk_live_YOUR_SECRET_KEY:API キーのセキュリティ
シークレットキーをクライアントサイドのコードに絶対に公開しないでください。フロントエンドには公開可能キーを使用し、シークレットキーはサーバー側のみで使用します。
制限付き API キー
セキュリティ強化のため、特定の権限のみを持つ制限付きキーを作成します。
- Stripe Dashboard > Developers > API Keys に移動
- 「Create restricted key」をクリック
- Tajo に必要な権限のみ付与
必要な権限
customers: readcharges: readpayment_intents: readsubscriptions: readinvoices: readevents: readproducts: readprices: 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_SOURCEAPI エンドポイント
コアエンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
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 Stripeawait tajo.connectors.connect('stripe', { secretKey: process.env.STRIPE_SECRET_KEY, webhookSecret: process.env.STRIPE_WEBHOOK_SECRET});顧客同期の実行
// Full historical syncawait tajo.connectors.sync('stripe', { type: 'full', resources: ['customers', 'subscriptions', 'payments'], since: '2023-01-01'});
// Check sync statusconst 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接続テスト
tajo connectors test stripe# ✓ API connection successful# ✓ Customers readable# ✓ Subscriptions readable# ✓ Payments readable# ✓ Webhook endpoint verifiedベストプラクティス
- 制限付き API キーを使用 - 必要最小限の権限のキーを作成
- 常にウェブフック署名を検証 - なりすましイベントを防止
- 冪等性を担保 - Stripe イベント ID で重複処理を防ぐ
- 顧客メタデータを同期 - マーケティング関連データを Stripe メタデータに格納
- ウェブフック配信を監視 - Stripe Dashboard で失敗した配信を確認
- まずテストモードで検証 - Stripe テストモードとテストクロックで統合を検証
セキュリティ
- API キー認証 - シークレットキーベースのアクセス、制限付きキー対応
- ウェブフック署名検証 - HMAC SHA-256 署名検証
- TLS 暗号化 - すべての API 通信を HTTPS で暗号化
- PCI 準拠 - Stripe が決済データの PCI DSS 準拠を担保
- IP ホワイトリスト - API アクセスの任意の IP 制限