Trình Kết Nối HubSpot

Trình Kết Nối HubSpot

Kết nối tài khoản HubSpot của bạn với Brevo qua Tajo để đồng bộ liên hệ hai chiều, quản lý giao dịch, và hợp nhất dữ liệu CRM với các chiến dịch marketing.

Tổng Quan

Tính Năng

• Đồng bộ liên hệ hai chiều - Đồng bộ liên hệ HubSpot với Brevo bao gồm thuộc tính tùy chỉnh
• Đồng bộ công ty - Nhập dữ liệu công ty và liên kết với liên hệ trong Brevo
• Đồng bộ đường ống giao dịch - Ánh xạ giai đoạn giao dịch HubSpot sang thuộc tính Brevo
• Đồng bộ vé - Đồng bộ vé hỗ trợ khách hàng với Brevo để theo dõi đa kênh
• Theo dõi sự kiện - Chuyển tiếp hoạt động email và form HubSpot sang Brevo
• Đồng bộ danh sách - Ánh xạ danh sách HubSpot sang danh sách liên hệ Brevo
• Thuộc tính tùy chỉnh - Đồng bộ thuộc tính tùy chỉnh HubSpot sang thuộc tính Brevo
• Phân đoạn - Sử dụng dữ liệu HubSpot cho phân đoạn nâng cao trong Brevo

Yêu Cầu

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

1. Tài khoản HubSpot (Starter, Professional, hoặc Enterprise)
2. Quyền truy cập API HubSpot hoặc Private App token
3. Tài khoản Brevo với quyền truy cập API
4. Tài khoản Tajo

Xác Thực

Private App (Khuyến Nghị)

HubSpot khuyến nghị sử dụng Private Apps để xác thực API, cung cấp token truy cập có phạm vi.

curl https://api.hubapi.com/crm/v3/objects/contacts \
  -H "Authorization: Bearer YOUR_PRIVATE_APP_TOKEN"

Tạo Private App trong HubSpot Settings > Integrations > Private Apps.

Phạm Vi Cần Thiết

CRM Scopes:
  crm.objects.contacts.read
  crm.objects.contacts.write
  crm.objects.companies.read
  crm.objects.deals.read
  crm.lists.read

Marketing Scopes:
  content

Timeline Scopes:
  timeline

OAuth 2.0

Để tích hợp công khai hoặc yêu cầu quyền riêng biệt:

# Bước 1: Chuyển hướng đến authorization URL
https://app.hubspot.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &scope=crm.objects.contacts.read
  &redirect_uri=YOUR_REDIRECT_URI

# Bước 2: Đổi mã lấy token
curl -X POST https://api.hubapi.com/oauth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI&code=CODE"

Cấu Hình

Thiết Lập Cơ Bản

connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Tùy chọn đồng bộ dữ liệu
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: false
      events: true

    # Ánh xạ danh sách sang Brevo
    list_mapping:
      "All Contacts": 1
      "Newsletter": 2
      "Customers": 3

Ánh Xạ Trường

Ánh xạ thuộc tính HubSpot 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
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # Trường CRM
  lifecyclestage: LIFECYCLE_STAGE
  lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Chỉ số tương tác
  hs_email_open_count: EMAIL_OPENS
  hs_email_click_count: EMAIL_CLICKS
  hs_last_sales_activity_timestamp: LAST_ACTIVITY

  # Thuộc tính tùy chỉnh
  custom_plan_type: PLAN_TYPE
  custom_mrr: MONTHLY_REVENUE

API Endpoints

Liên Hệ

Giao Dịch

Công Ty

Danh Sách

Sự Kiện

Sự Kiện Liên Hệ

Sự Kiện Giao Dịch

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 HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});

Đồng Bộ Liên Hệ Sang Brevo

// Đồng bộ tăng dần từ HubSpot sang Brevo
await tajo.connectors.sync('hubspot', {
  type: 'incremental',
  resources: ['contacts', 'companies'],
  since: '2024-01-01',
  batchSize: 100
});

// Kiểm tra trạng thái đồng bộ
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 12500,
//   companiesSynced: 890,
//   dealsSynced: 3400
// }

Xử Lý Webhook HubSpot

// Xử lý webhook HubSpot
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature');

  // Xác minh chữ ký webhook
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      type: event.subscriptionType,
      objectId: event.objectId,
      payload: event
    });
  }

  res.status(200).send('OK');
});

Giới Hạn Tốc Độ

Giới hạn bổ sung:

• Upsert theo lô: 100 bản ghi mỗi yêu cầu
• Tìm kiếm: 200 yêu cầu/phút
• Lịch sử thuộc tính: 100 yêu cầu/phút

Khắc Phục Sự Cố

Sự Cố Phổ Biến

Chế Độ Debug

connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true

Kiểm Tra Kết Nối

tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies accessible
# ✓ Deals readable
# ✓ Webhooks configured

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

1. Sử dụng Private Apps - Ưu tiên Private Apps hơn API keys cũ vì kiểm soát phạm vi tốt hơn
2. Đồng bộ tăng dần - Sử dụng khoảng thời gian để tránh xử lý lại dữ liệu lịch sử
3. Xử lý trùng lặp - HubSpot deduplicate theo email; đảm bảo email nhất quán
4. Ánh xạ trường tùy chỉnh - Tạo thuộc tính Brevo tương ứng trước khi đồng bộ
5. Theo dõi webhook - Sử dụng HubSpot webhooks để cập nhật theo thời gian thực thay vì polling

Bảo Mật

• Xác thực Private App - Token có phạm vi với kiểm soát chi tiết
• OAuth 2.0 - Xác thực dựa trên token cho tích hợp công khai
• Xác minh Webhook - Xác minh chữ ký HMAC SHA-256
• Mã hóa TLS - Tất cả giao tiếp API được mã hóa qua HTTPS
• Quản lý phạm vi - Giới hạn quyền truy cập API chỉ những trường cần thiết

Tài Nguyên Liên Quan

• Tài Liệu API HubSpot
• Hướng Dẫn Private Apps HubSpot
• Trình Kết Nối Salesforce
• Trình Kết Nối Brevo
• Customer Sync Skill