Stripe 连接器
Stripe 连接器
通过 Tajo 将您的 Stripe 账户连接到 Brevo，实现完整的支付数据同步、订阅生命周期管理和收入驱动的营销自动化。
概览
| 属性 | 值 |
|---|---|
| 平台 | Stripe |
| 类别 | 电子商务 |
| 设置复杂度 | 简单 |
| 官方集成 | 是 |
| 同步数据 | 客户、支付、订阅、发票、事件 |
| API 基础 URL | https://api.stripe.com/v1 |
功能
- 客户同步 - 将 Stripe 客户（含元数据）与 Brevo 联系人同步
- 支付跟踪 - 追踪成功支付、退款和失败扣款
- 订阅管理 - 同步订阅生命周期事件，用于留存活动
- 发票数据 - 同步发票详情，用于购后和续费自动化
- 收入归因 - 将客户终身价值和 MRR 映射到 Brevo 属性
- Webhook 事件 - 所有支付活动的实时事件通知
- 多货币支持 - 处理多种货币的支付
- 结账会话跟踪 - 跟踪 Stripe Checkout，用于支付放弃恢复
前提条件
开始之前，请确保您已具备：
- 具有 API 访问权限的 Stripe 账户
- Stripe API 密钥（可发布密钥和密钥）
- 具有 API 访问权限的 Brevo 账户
- Tajo 账户
认证
API 密钥认证
Stripe 使用带有密钥的 Bearer 令牌认证。
curl https://api.stripe.com/v1/customers \ -u sk_live_YOUR_SECRET_KEY:API 密钥安全
切勿在客户端代码中暴露您的密钥。前端操作使用可发布密钥，密钥仅用于服务端。
受限 API 密钥
创建具有特定权限的受限密钥以增强安全性：
- 前往 Stripe 控制台 > 开发者 > API 密钥
- 点击”创建受限密钥”
- 仅授予 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 | 映射到 SMS 属性，用于 WhatsApp/短信 |
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 Webhook
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 请求/秒 | 每个密钥 |
| Webhook 投递 | 100,000 事件/天 | 每个端点 |
速率限制处理
超出限制时，Stripe 返回 429 Too Many Requests 响应。实施指数退避。使用带自动分页的列表端点批量检索数据。
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 401 Unauthorized | API 密钥无效 | 在 Stripe 控制台中检查密钥 |
| Webhook 签名验证失败 | Webhook 密钥不正确 | 从控制台重新复制 Webhook 签名密钥 |
| 客户未同步 | Stripe 客户无邮箱 | 确保 Stripe 客户记录已设置邮箱 |
| 订阅数据缺失 | 权限不足 | 更新受限密钥权限 |
| 重复事件 | Webhook 重试投递 | 使用事件 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 密钥 - 创建具有最低所需权限的密钥
- 始终验证 Webhook 签名 - 防止伪造的 Webhook 事件
- 处理幂等性 - 使用 Stripe 事件 ID 防止重复处理
- 同步客户元数据 - 在 Stripe 元数据字段中存储营销相关数据
- 监控 Webhook 投递 - 检查 Stripe 控制台中的失败投递
- 先使用测试模式 - 使用 Stripe 测试模式和测试时钟验证您的集成
安全
- API 密钥认证 - 具有受限密钥支持的基于密钥的访问
- Webhook 签名验证 - HMAC SHA-256 签名验证
- TLS 加密 - 所有 API 通信通过 HTTPS 加密
- PCI 合规 - Stripe 处理支付数据的 PCI DSS 合规
- IP 白名单 - 可选的 API 访问 IP 限制