Trình Kết Nối Stripe
Trình Kết Nối Stripe
Kết nối Stripe với Brevo qua Tajo để đồng bộ dữ liệu thanh toán, theo dõi trạng thái subscription và kích hoạt chiến dịch marketing dựa trên billing events.
Tổng Quan
| Thuộc Tính | Giá Trị |
|---|---|
| Nền Tảng | Stripe |
| Danh Mục | Thương Mại Điện Tử |
| Độ Phức Tạp Thiết Lập | Trung Bình |
| Tích Hợp Chính Thức | Có |
| Dữ Liệu Đồng Bộ | Customers, Payments, Subscriptions, Invoices |
| URL API | https://api.stripe.com/v1 |
Tính Năng
- Đồng bộ customers - Nhập Stripe customers sang liên hệ Brevo với dữ liệu billing
- Theo dõi subscriptions - Đồng bộ trạng thái subscription sang thuộc tính Brevo
- Sự kiện payment - Forward payment success, failure và refund sang Brevo
- Quản lý invoices - Kích hoạt email nhắc nhở theo sự kiện invoice
- Phân đoạn theo plan - Tạo segments Brevo theo Stripe subscription plans
- Churned customers - Nhận diện và segment khách hàng đã hủy subscription
Yêu Cầu
Trước khi bắt đầu, hãy đảm bảo bạn có:
- Tài khoản Stripe
- Stripe API keys (secret key)
- Stripe webhook endpoint secret
- Tài khoản Brevo với quyền truy cập API
- Tài khoản Tajo
Xác Thực
API Key Authentication
curl "https://api.stripe.com/v1/customers" \ -H "Authorization: Bearer YOUR_SECRET_KEY"Lấy API keys trong Stripe Dashboard > Developers > API keys.
Bảo Mật API Key
Stripe secret keys cấp quyền truy cập đầy đủ vào tài khoản. Không bao giờ expose secret keys phía client. Sử dụng Restricted Keys với quyền tối thiểu cần thiết cho tích hợp.
Xác Minh Webhook
// Xác minh Stripe webhook signatureconst event = stripe.webhooks.constructEvent( req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);Cấu Hình
Thiết Lập Cơ Bản
connectors: stripe: enabled: true secret_key: "${STRIPE_SECRET_KEY}" webhook_secret: "${STRIPE_WEBHOOK_SECRET}"
sync: customers: true subscriptions: true invoices: true payment_intents: false
# Ánh xạ plan sang danh sách Brevo plan_list_mapping: "price_starter": 30 "price_pro": 31 "price_enterprise": 32Ánh Xạ Trường
Ánh Xạ Mặc Định
| Parameter | Type | Description |
|---|---|---|
email required | string | Địa chỉ email Stripe customer (định danh duy nhất) |
name optional | string | Tên đầy đủ Stripe customer |
phone optional | string | Số điện thoại billing |
subscriptions.data[0].status optional | string | Trạng thái subscription hiện tại |
subscriptions.data[0].plan.id optional | string | ID plan hiện tại |
balance optional | integer | Số dư tài khoản customer (cents) |
API Endpoints
| Phương Thức | Endpoint | Mô Tả |
|---|---|---|
GET | /v1/customers | Liệt kê customers |
GET | /v1/customers/{id} | Lấy customer |
GET | /v1/subscriptions | Liệt kê subscriptions |
GET | /v1/invoices | Liệt kê invoices |
GET | /v1/payment_intents | Liệt kê payment intents |
POST | /v1/webhook_endpoints | Tạo webhook endpoint |
Sự Kiện
| Sự Kiện | Kích Hoạt | Trường Hợp Sử Dụng |
|---|---|---|
customer.created | Customer Stripe mới | Kích hoạt email chào mừng |
customer.subscription.created | Subscription mới | Gửi onboarding sequence |
customer.subscription.updated | Plan thay đổi | Cập nhật thuộc tính Brevo |
customer.subscription.deleted | Subscription hủy | Kích hoạt win-back campaign |
invoice.payment_succeeded | Thanh toán thành công | Xác nhận renewal |
invoice.payment_failed | Thanh toán thất bại | Thông báo khẩn cấp |
charge.refunded | Hoàn tiền xử lý | Follow-up refund |
Ví Dụ Code
Khởi Tạo Trình Kết Nối
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
await tajo.connectors.connect('stripe', { secretKey: process.env.STRIPE_SECRET_KEY, webhookSecret: process.env.STRIPE_WEBHOOK_SECRET});Đồng Bộ Subscriptions Sang Brevo
// Đồng bộ Stripe subscriptions sang liên hệ Brevoawait tajo.connectors.sync('stripe', { type: 'full', resources: ['customers', 'subscriptions'], options: { includeTrialing: true, includeCanceled: false, expandMetadata: true }});Xử Lý Webhook Stripe
// Xử lý Stripe webhookapp.post('/webhooks/stripe', async (req, res) => { const sig = req.headers['stripe-signature'];
try { const event = stripe.webhooks.constructEvent( req.rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET );
await tajo.connectors.handleWebhook('stripe', { type: event.type, payload: event.data.object });
res.json({ received: true }); } catch (err) { res.status(400).send(`Webhook Error: ${err.message}`); }});Giới Hạn Tốc Độ
| Tài Nguyên | Giới Hạn |
|---|---|
| Live mode | 100 yêu cầu/giây |
| Test mode | 25 yêu cầu/giây |
| Search API | 20 yêu cầu/giây |
Khắc Phục Sự Cố
| Sự Cố | Nguyên Nhân | Giải Pháp |
|---|---|---|
| 401 Unauthorized | API key không hợp lệ | Kiểm tra secret key trong Stripe dashboard |
| Webhook signature fail | Secret không khớp | Xác minh STRIPE_WEBHOOK_SECRET đúng endpoint |
| Missing customers | Filter không đúng | Kiểm tra date range filter |
| Subscriptions thiếu | Subscription đã xóa | Bật include_canceled nếu cần dữ liệu lịch sử |