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ínhGiá Trị
Nền TảngStripe
Danh MụcThương Mại Điện Tử
Độ Phức Tạp Thiết LậpTrung Bình
Tích Hợp Chính Thức
Dữ Liệu Đồng BộCustomers, Payments, Subscriptions, Invoices
URL APIhttps://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ó:

  1. Tài khoản Stripe
  2. Stripe API keys (secret key)
  3. Stripe webhook endpoint secret
  4. Tài khoản Brevo với quyền truy cập API
  5. Tài khoản Tajo

Xác Thực

API Key Authentication

Terminal window
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 signature
const 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ứcEndpointMô Tả
GET/v1/customersLiệt kê customers
GET/v1/customers/{id}Lấy customer
GET/v1/subscriptionsLiệt kê subscriptions
GET/v1/invoicesLiệt kê invoices
GET/v1/payment_intentsLiệt kê payment intents
POST/v1/webhook_endpointsTạo webhook endpoint

Sự Kiện

Sự KiệnKích HoạtTrường Hợp Sử Dụng
customer.createdCustomer Stripe mớiKích hoạt email chào mừng
customer.subscription.createdSubscription mớiGửi onboarding sequence
customer.subscription.updatedPlan thay đổiCập nhật thuộc tính Brevo
customer.subscription.deletedSubscription hủyKích hoạt win-back campaign
invoice.payment_succeededThanh toán thành côngXác nhận renewal
invoice.payment_failedThanh toán thất bạiThông báo khẩn cấp
charge.refundedHoà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ệ Brevo
await tajo.connectors.sync('stripe', {
type: 'full',
resources: ['customers', 'subscriptions'],
options: {
includeTrialing: true,
includeCanceled: false,
expandMetadata: true
}
});

Xử Lý Webhook Stripe

// Xử lý Stripe webhook
app.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ênGiới Hạn
Live mode100 yêu cầu/giây
Test mode25 yêu cầu/giây
Search API20 yêu cầu/giây

Khắc Phục Sự Cố

Sự CốNguyên NhânGiải Pháp
401 UnauthorizedAPI key không hợp lệKiểm tra secret key trong Stripe dashboard
Webhook signature failSecret không khớpXác minh STRIPE_WEBHOOK_SECRET đúng endpoint
Missing customersFilter không đúngKiểm tra date range filter
Subscriptions thiếuSubscription đã xóaBật include_canceled nếu cần dữ liệu lịch sử

Tài Nguyên Liên Quan

Subscribe to updates

developer-docs

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

Trợ lý AI

Xin chào! Hãy hỏi tôi về tài liệu.

Bắt đầu miễn phí với Brevo