Trình Kết Nối Brevo

Trình Kết Nối Brevo

Kết nối tài khoản Brevo của bạn với Tajo để quản lý contacts hợp nhất, gửi tin nhắn giao dịch qua email, SMS và WhatsApp, và marketing automation toàn diện.

Tổng Quan

Tính Năng

• Tin nhắn đa kênh - Gửi email giao dịch, SMS và WhatsApp từ một API hợp nhất
• Quản lý contacts - Tạo, cập nhật và phân đoạn contacts với thuộc tính tùy chỉnh
• Marketing campaigns - Tạo và gửi email campaigns theo chương trình
• Theo dõi sự kiện - Theo dõi custom events và hoạt động website qua Brevo Tracker
• Đồng bộ eCommerce - Đồng bộ products, orders và cart data cho campaigns cá nhân hóa
• Loyalty programs - Quản lý loyalty subscriptions, points và member data
• Webhook support - Thông báo sự kiện theo thời gian thực cho transactional, marketing và CRM events
• Conversations - Tích hợp live chat widget và quản lý messages theo chương trình

Yêu Cầu

Trước khi bắt đầu, hãy đảm bảo bạn có:

1. Tài khoản Brevo (Free, Starter, Business, hoặc Enterprise)
2. API key được tạo từ Brevo Settings > API Keys
3. Tài khoản Tajo với quyền truy cập API
4. Domain gửi email đã xác minh

Xác Thực

Brevo hỗ trợ hai phương thức xác thực:

Xác Thực API Key (Khuyến Nghị)

Bao gồm API key trong header api-key với mỗi request. Tốt nhất cho tích hợp trực tiếp và giao tiếp server-to-server.

curl -X GET "https://api.brevo.com/v3/account" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Xác Thực OAuth 2.0

Sử dụng OAuth 2.0 cho tích hợp riêng tư trong tổ chức yêu cầu quyền truy cập ủy quyền và quyền hạn theo người dùng. OAuth cung cấp hệ thống token với thời gian hiệu lực xác định.

Cấu Hình

Thiết Lập Cơ Bản

connectors:
  brevo:
    enabled: true
    api_key: "${BREVO_API_KEY}"
    api_version: "v3"

    # Tùy chọn đồng bộ dữ liệu
    sync:
      contacts: true
      campaigns: true
      transactional: true
      events: true
      ecommerce: true

    # Gán danh sách
    lists:
      all_customers: 5
      newsletter: 6
      buyers: 7

Ánh Xạ Trường

Ánh xạ trường dữ liệu sang thuộc tính liên hệ Brevo:

Ánh Xạ Thuộc Tính Tùy Chỉnh

field_mapping:
  # Trường tiêu chuẩn
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Trường marketing
  opt_in: OPT_IN
  signup_source: SIGNUP_SOURCE
  preferred_language: LANGUAGE

  # Số liệu eCommerce
  orders_count: ORDER_COUNT
  total_spent: TOTAL_REVENUE
  last_order_date: LAST_ORDER_DATE

  # Trường Loyalty
  loyalty_tier: VIP_TIER
  loyalty_points: LOYALTY_POINTS

API Endpoints

Endpoints Cốt Lõi

Endpoints eCommerce

Endpoints Campaign

Sự Kiện

Sự Kiện Giao Dịch

Sự Kiện eCommerce

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
});

// Kết nối tài khoản Brevo
await tajo.connectors.connect('brevo', {
  apiKey: process.env.BREVO_API_KEY
});

Gửi Email Giao Dịch

// Gửi email giao dịch qua Brevo
await tajo.brevo.sendTransactionalEmail({
  to: [{ email: '[email protected]', name: 'Nguyễn Văn A' }],
  templateId: 12,
  params: {
    ORDER_ID: '12345',
    ORDER_TOTAL: '1.499.000₫',
    DELIVERY_DATE: '2024-02-15'
  }
});

Đồng Bộ Contacts

// Import contacts theo lô sang Brevo
await tajo.connectors.sync('brevo', {
  type: 'full',
  resources: ['contacts'],
  options: {
    listIds: [5, 6],
    updateExisting: true,
    emptyContactsAttributes: false
  }
});

// Kiểm tra trạng thái đồng bộ
const status = await tajo.connectors.status('brevo');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 25400,
//   campaignsSent: 142,
//   eventsTracked: 89320
// }

Theo Dõi Custom Events

// Theo dõi custom event cho liên hệ
await tajo.brevo.trackEvent({
  email: '[email protected]',
  event: 'product_purchased',
  eventdata: {
    id: 'txn_98765',
    data: {
      product_name: 'Premium Widget',
      price: 49.99,
      currency: 'USD'
    }
  }
});

Giới Hạn Tốc Độ

Brevo enforces giới hạn tốc độ theo ba tầng dựa trên gói của bạn:

Khắc Phục Sự Cố

Sự Cố Phổ Biến

Chế Độ Debug

Bật verbose logging:

connectors:
  brevo:
    debug: true
    log_level: verbose
    log_webhooks: true

Kiểm Tra Kết Nối

tajo connectors test brevo
# ✓ API connection successful
# ✓ Contacts API accessible
# ✓ Transactional email ready
# ✓ SMS sending configured
# ✓ Webhooks registered

Thực Hành Tốt Nhất

1. Sử dụng API key rotation - Thay đổi API keys định kỳ để bảo mật
2. Triển khai xác minh webhook - Xác thực chữ ký webhook với username/password authentication
3. Batch contact imports - Sử dụng bulk import cho datasets lớn thay vì gọi API riêng lẻ
4. Theo dõi giới hạn tốc độ - Kiểm tra headers giới hạn tốc độ để tránh lỗi 429
5. Sử dụng event tracking - Triển khai Brevo Tracker để có dữ liệu hành vi khách hàng toàn diện
6. Thiết lập xác thực người gửi đúng cách - Cấu hình SPF, DKIM và DMARC để deliverability tối ưu

Bảo Mật

• Xác thực API Key - Truy cập dựa trên token bí mật qua header api-key
• OAuth 2.0 - Truy cập ủy quyền dựa trên token cho tích hợp riêng tư
• Xác minh Webhook - Xác thực username và password cho webhook calls an toàn
• Mã hóa TLS - Tất cả giao tiếp API được mã hóa trong quá trình truyền
• IP whitelisting - Giới hạn IP tùy chọn có sẵn trên gói Enterprise

Tài Nguyên Liên Quan

• Tài Liệu API Brevo
• Hướng Dẫn Xác Thực Brevo
• Giới Hạn Tốc Độ Brevo
• Trình Kết Nối Shopify
• Customer Sync Skill
• Brevo Contacts API