Cách Sử Dụng HubSpot API Hiệu Quả Năm 2026

TÓM TẮT

API của HubSpot cho phép các nhà phát triển tích hợp với các trung tâm CRM, marketing, bán hàng và dịch vụ một cách lập trình. Nó sử dụng xác thực OAuth 2.0 và ứng dụng riêng tư, các điểm cuối RESTful cho danh bạ, công ty, giao dịch, phiếu yêu cầu hỗ trợ, v.v., với giới hạn tốc độ dựa trên cấp độ gói đăng ký. Hướng dẫn này bao gồm thiết lập xác thực, các điểm cuối chính, webhook và các chiến lược tích hợp sản xuất.

Giới thiệu

HubSpot quản lý hơn 194.000 tài khoản khách hàng và hàng tỷ bản ghi CRM. Đối với các nhà phát triển xây dựng tích hợp CRM, tự động hóa marketing hoặc công cụ bán hàng, tích hợp API HubSpot không phải là tùy chọn mà là điều cần thiết để tiếp cận hơn 7 triệu người dùng.

Thực tế là: các doanh nghiệp mất 15-20 giờ mỗi tuần cho việc nhập dữ liệu thủ công giữa các hệ thống. Một tích hợp API HubSpot vững chắc sẽ tự động hóa việc đồng bộ hóa danh bạ, cập nhật giao dịch, quy trình làm việc marketing và báo cáo trên các nền tảng.

API của HubSpot là gì?

HubSpot cung cấp API RESTful để truy cập dữ liệu CRM và các tính năng tự động hóa marketing. API này xử lý:

• Danh bạ, công ty, giao dịch, phiếu yêu cầu hỗ trợ và các đối tượng tùy chỉnh
• Email marketing và trang đích
• Quy trình bán hàng và chuỗi hoạt động
• Phiếu yêu cầu hỗ trợ dịch vụ và cuộc hội thoại
• Phân tích và báo cáo
• Quy trình làm việc và tự động hóa
• Tệp và tài sản

Các tính năng chính

Tổng quan kiến trúc API

HubSpot sử dụng các API REST có phiên bản:

https://api.hubapi.com/

So sánh các phiên bản API

Quan trọng: HubSpot đã ngừng hỗ trợ xác thực bằng khóa API để chuyển sang OAuth 2.0 và ứng dụng riêng tư. Di chuyển tất cả các tích hợp ngay lập tức.

Bắt đầu: Thiết lập xác thực

Bước 1: Tạo tài khoản nhà phát triển HubSpot của bạn

Trước khi truy cập API:

1. Truy cập Cổng thông tin nhà phát triển HubSpot
2. Đăng nhập bằng tài khoản HubSpot của bạn (hoặc tạo một tài khoản mới)
3. Điều hướng đến Ứng dụng trong bảng điều khiển nhà phát triển
4. Nhấp vào Tạo ứng dụng

Bước 2: Chọn phương thức xác thực

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

Bước 3: Thiết lập ứng dụng riêng tư (Được khuyến nghị cho các tích hợp nội bộ)

Tạo một ứng dụng riêng tư để truy cập một cổng thông tin:

1. Truy cập Cài đặt > Tích hợp > Ứng dụng riêng tư
2. Nhấp vào Tạo một ứng dụng riêng tư
3. Cấu hình phạm vi:

contacts
crm.objects.companies
crm.objects.deals
crm.objects.tickets
automation
webhooks

1. Tạo mã truy cập
2. Sao chép và lưu trữ an toàn

# .env file
HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
HUBSPOT_PORTAL_ID="12345678"

Bước 4: Thiết lập OAuth 2.0 (Dành cho ứng dụng đa đối tượng thuê)

Cấu hình OAuth để truy cập nhiều cổng thông tin:

1. Truy cập Ứng dụng > Tạo ứng dụng
2. Cấu hình cài đặt xác thực:

const HUBSPOT_CLIENT_ID = process.env.HUBSPOT_CLIENT_ID;
const HUBSPOT_CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const HUBSPOT_REDIRECT_URI = process.env.HUBSPOT_REDIRECT_URI;

// Build authorization URL
const getAuthUrl = (state) => {
  const params = new URLSearchParams({
    client_id: HUBSPOT_CLIENT_ID,
    redirect_uri: HUBSPOT_REDIRECT_URI,
    scope: 'crm.objects.contacts.read crm.objects.contacts.write',
    state: state,
    optional_scope: 'crm.objects.deals.read'
  });

  return `https://app.hubspot.com/oauth/authorize?${params.toString()}`;
};

Bước 5: Trao đổi mã để lấy mã truy cập

Xử lý lệnh gọi lại OAuth:

const exchangeCodeForToken = async (code) => {
  const response = await fetch('https://api.hubspot.com/oauth/v1/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: HUBSPOT_CLIENT_ID,
      client_secret: HUBSPOT_CLIENT_SECRET,
      redirect_uri: HUBSPOT_REDIRECT_URI,
      code: code
    })
  });

  const data = await response.json();

  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token,
    expiresIn: data.expires_in,
    portalId: data.hub_portal_id
  };
};

// Handle callback
app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query;

  try {
    const tokens = await exchangeCodeForToken(code);

    // Store tokens in database
    await db.installations.create({
      portalId: tokens.portalId,
      accessToken: tokens.accessToken,
      refreshToken: tokens.refreshToken,
      tokenExpiry: Date.now() + (tokens.expiresIn * 1000)
    });

    res.redirect('/success');
  } catch (error) {
    console.error('OAuth error:', error);
    res.status(500).send('Authentication failed');
  }
});

Bước 6: Làm mới mã truy cập

Mã truy cập hết hạn sau 6 giờ:

const refreshAccessToken = async (refreshToken) => {
  const response = await fetch('https://api.hubspot.com/oauth/v1/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: HUBSPOT_CLIENT_ID,
      client_secret: HUBSPOT_CLIENT_SECRET,
      refresh_token: refreshToken
    })
  });

  const data = await response.json();

  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token, // Always save new refresh token
    expiresIn: data.expires_in
  };
};

// Middleware to ensure valid token
const ensureValidToken = async (portalId) => {
  const installation = await db.installations.findByPortalId(portalId);

  // Refresh if expires within 30 minutes
  if (installation.tokenExpiry < Date.now() + 1800000) {
    const newTokens = await refreshAccessToken(installation.refreshToken);

    await db.installations.update(installation.id, {
      accessToken: newTokens.accessToken,
      refreshToken: newTokens.refreshToken,
      tokenExpiry: Date.now() + (newTokens.expiresIn * 1000)
    });

    return newTokens.accessToken;
  }

  return installation.accessToken;
};

Bước 7: Thực hiện các cuộc gọi API đã xác thực

Tạo client API có thể tái sử dụng:

const HUBSPOT_BASE_URL = 'https://api.hubspot.com';

const hubspotRequest = async (endpoint, options = {}, portalId = null) => {
  const accessToken = portalId ? await ensureValidToken(portalId) : process.env.HUBSPOT_ACCESS_TOKEN;

  const response = await fetch(`${HUBSPOT_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`HubSpot API Error: ${error.message}`);
  }

  return response.json();
};

// Usage
const contacts = await hubspotRequest('/crm/v3/objects/contacts');

Làm việc với các đối tượng CRM

Tạo một liên hệ

Tạo hoặc cập nhật một liên hệ:

const createContact = async (contactData) => {
  const contact = {
    properties: {
      email: contactData.email,
      firstname: contactData.firstName,
      lastname: contactData.lastName,
      phone: contactData.phone,
      company: contactData.company,
      website: contactData.website,
      lifecyclestage: contactData.lifecycleStage || 'lead'
    }
  };

  const response = await hubspotRequest('/crm/v3/objects/contacts', {
    method: 'POST',
    body: JSON.stringify(contact)
  });

  return response;
};

// Usage
const contact = await createContact({
  email: 'john.doe@example.com',
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1-555-0123',
  company: 'Acme Corp',
  lifecycleStage: 'customer'
});

console.log(`Contact created: ${contact.id}`);

Thuộc tính liên hệ

Lấy một liên hệ

Lấy liên hệ bằng ID:

const getContact = async (contactId) => {
  const response = await hubspotRequest(`/crm/v3/objects/contacts/${contactId}`);
  return response;
};

// Usage
const contact = await getContact('12345');
console.log(`${contact.properties.firstname} ${contact.properties.lastname}`);
console.log(`Email: ${contact.properties.email}`);

Tìm kiếm liên hệ

Tìm kiếm bằng bộ lọc:

const searchContacts = async (searchCriteria) => {
  const response = await hubspotRequest('/crm/v3/objects/contacts/search', {
    method: 'POST',
    body: JSON.stringify({
      filterGroups: searchCriteria,
      properties: ['firstname', 'lastname', 'email', 'company'],
      limit: 100
    })
  });

  return response;
};

// Usage - Find contacts at specific company
const results = await searchContacts({
  filterGroups: [
    {
      filters: [
        {
          propertyName: 'company',
          operator: 'EQ',
          value: 'Acme Corp'
        }
      ]
    }
  ]
});

results.results.forEach(contact => {
  console.log(`${contact.properties.email}`);
});

Các toán tử lọc tìm kiếm

Tạo một công ty

Tạo bản ghi công ty:

const createCompany = async (companyData) => {
  const company = {
    properties: {
      name: companyData.name,
      domain: companyData.domain,
      industry: companyData.industry,
      numberofemployees: companyData.employees,
      annualrevenue: companyData.revenue,
      city: companyData.city,
      state: companyData.state,
      country: companyData.country
    }
  };

  const response = await hubspotRequest('/crm/v3/objects/companies', {
    method: 'POST',
    body: JSON.stringify(company)
  });

  return response;
};

// Usage
const company = await createCompany({
  name: 'Acme Corporation',
  domain: 'acme.com',
  industry: 'Technology',
  employees: 500,
  revenue: 50000000,
  city: 'San Francisco',
  state: 'CA',
  country: 'USA'
});

Liên kết các đối tượng

Liên kết liên hệ với các công ty:

const associateContactWithCompany = async (contactId, companyId) => {
  const response = await hubspotRequest(
    `/crm/v3/objects/contacts/${contactId}/associations/companies/${companyId}`,
    {
      method: 'PUT',
      body: JSON.stringify({
        types: [
          {
            associationCategory: 'HUBSPOT_DEFINED',
            associationTypeId: 1 // Contact to Company
          }
        ]
      })
    }
  );

  return response;
};

// Usage
await associateContactWithCompany('12345', '67890');

Các loại liên kết

Tạo một giao dịch

Tạo cơ hội bán hàng:

const createDeal = async (dealData) => {
  const deal = {
    properties: {
      dealname: dealData.name,
      amount: dealData.amount.toString(),
      dealstage: dealData.stage || 'appointmentscheduled',
      pipeline: dealData.pipelineId || 'default',
      closedate: dealData.closeDate,
      dealtype: dealData.type || 'newbusiness',
      description: dealData.description
    }
  };

  const response = await hubspotRequest('/crm/v3/objects/deals', {
    method: 'POST',
    body: JSON.stringify(deal)
  });

  return response;
};

// Usage
const deal = await createDeal({
  name: 'Acme Corp - Enterprise License',
  amount: 50000,
  stage: 'qualification',
  closeDate: '2026-06-30',
  type: 'newbusiness',
  description: 'Enterprise annual subscription'
});

// Associate with company and contact
await hubspotRequest(
  `/crm/v3/objects/deals/${deal.id}/associations/companies/${companyId}`,
  { method: 'PUT', body: JSON.stringify({ types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 5 }] }) }
);

await hubspotRequest(
  `/crm/v3/objects/deals/${deal.id}/associations/contacts/${contactId}`,
  { method: 'PUT', body: JSON.stringify({ types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 3 }] }) }
);

Các giai đoạn giao dịch (Quy trình mặc định)

Webhooks

Cấu hình Webhooks

Thiết lập webhook để nhận thông báo theo thời gian thực:

const createWebhook = async (webhookData) => {
  const response = await hubspotRequest('/webhooks/v3/my-app/webhooks', {
    method: 'POST',
    body: JSON.stringify({
      webhookUrl: webhookData.url,
      eventTypes: webhookData.events,
      objectType: webhookData.objectType,
      propertyName: webhookData.propertyName // Optional: filter by property change
    })
  });

  return response;
};

// Usage
const webhook = await createWebhook({
  url: 'https://myapp.com/webhooks/hubspot',
  events: [
    'contact.creation',
    'contact.propertyChange',
    'company.creation',
    'deal.creation',
    'deal.stageChange'
  ],
  objectType: 'contact'
});

console.log(`Webhook created: ${webhook.id}`);

Các loại sự kiện Webhook

Xử lý Webhooks

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/hubspot', express.json(), async (req, res) => {
  const signature = req.headers['x-hubspot-signature'];
  const payload = JSON.stringify(req.body);

  // Verify webhook signature
  const isValid = verifyWebhookSignature(payload, signature, process.env.HUBSPOT_CLIENT_SECRET);

  if (!isValid) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }

  const events = req.body;

  for (const event of events) {
    console.log(`Event: ${event.eventType}`);
    console.log(`Object: ${event.objectType} - ${event.objectId}`);
    console.log(`Property: ${event.propertyName}`);
    console.log(`Value: ${event.propertyValue}`);

    // Route to appropriate handler
    switch (event.eventType) {
      case 'contact.creation':
        await handleContactCreation(event);
        break;
      case 'contact.propertyChange':
        await handleContactUpdate(event);
        break;
      case 'deal.stageChange':
        await handleDealStageChange(event);
        break;
    }
  }

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

function verifyWebhookSignature(payload, signature, clientSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', clientSecret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Giới hạn tốc độ

Hiểu về giới hạn tốc độ

HubSpot áp dụng giới hạn tốc độ dựa trên cấp độ gói đăng ký:

Vượt quá giới hạn sẽ dẫn đến phản hồi HTTP 429 (Quá nhiều yêu cầu).

Tiêu đề giới hạn tốc độ

Triển khai xử lý giới hạn tốc độ

const makeRateLimitedRequest = async (endpoint, options = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await hubspotRequest(endpoint, options);

      // Log rate limit info
      const remaining = response.headers.get('X-HubSpot-RateLimit-Second-Remaining');
      if (remaining < 10) {
        console.warn(`Low rate limit remaining: ${remaining}`);
      }

      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

// Rate limiter class
class HubSpotRateLimiter {
  constructor(requestsPerSecond = 90) { // Stay under limit
    this.queue = [];
    this.interval = 1000 / requestsPerSecond;
    this.processing = false;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;
    this.processing = true;

    while (this.queue.length > 0) {
      const { requestFn, resolve, reject } = this.queue.shift();
      try {
        const result = await requestFn();
        resolve(result);
      } catch (error) {
        reject(error);
      }
      if (this.queue.length > 0) {
        await new Promise(r => setTimeout(r, this.interval));
      }
    }
    this.processing = false;
  }
}

Danh sách kiểm tra triển khai sản xuất

Trước khi đưa vào hoạt động chính thức:

• [ ] Sử dụng xác thực ứng dụng riêng tư hoặc OAuth 2.0
• [ ] Lưu trữ token một cách an toàn (cơ sở dữ liệu được mã hóa)
• [ ] Triển khai làm mới token tự động
• [ ] Thiết lập giới hạn tốc độ và hàng đợi yêu cầu
• [ ] Cấu hình điểm cuối webhook bằng HTTPS
• [ ] Triển khai xử lý lỗi toàn diện
• [ ] Thêm ghi nhật ký cho tất cả các cuộc gọi API
• [ ] Giám sát việc sử dụng giới hạn tốc độ
• [ ] Tạo runbook cho các vấn đề thường gặp

Các trường hợp sử dụng thực tế

Đồng bộ hóa CRM

Một công ty SaaS đồng bộ hóa dữ liệu khách hàng:

• Thử thách: Nhập dữ liệu thủ công giữa ứng dụng và HubSpot
• Giải pháp: Đồng bộ hóa theo thời gian thực thông qua webhooks và API
• Kết quả: Không cần nhập thủ công, độ chính xác dữ liệu 100%

Định tuyến khách hàng tiềm năng

Một công ty marketing tự động hóa việc phân phối khách hàng tiềm năng:

• Thử thách: Thời gian phản hồi khách hàng tiềm năng chậm
• Giải pháp: Định tuyến đến nhân viên bán hàng được kích hoạt bởi webhook
• Kết quả: Thời gian phản hồi 5 phút, tăng 40% tỷ lệ chuyển đổi

Kết luận

API của HubSpot cung cấp khả năng tự động hóa marketing và CRM toàn diện. Những điểm chính cần nhớ:

• Sử dụng OAuth 2.0 cho các ứng dụng đa đối tượng thuê, ứng dụng riêng tư cho các tích hợp nội bộ
• Giới hạn tốc độ khác nhau tùy theo cấp độ (100-400 yêu cầu/giây)
• Webhooks cho phép đồng bộ hóa theo thời gian thực
• Các đối tượng CRM hỗ trợ liên kết và thuộc tính tùy chỉnh
• Apidog tối ưu hóa việc kiểm thử API và cộng tác nhóm

Phần Câu hỏi thường gặp (FAQ)

Làm cách nào để xác thực với API của HubSpot?

Sử dụng OAuth 2.0 cho các ứng dụng đa đối tượng thuê hoặc ứng dụng riêng tư cho các tích hợp một cổng thông tin. Xác thực bằng khóa API đã ngừng hỗ trợ.

Giới hạn tốc độ của HubSpot là gì?

Giới hạn tốc độ dao động từ 100 yêu cầu/giây (Miễn phí) đến 400 yêu cầu/giây (Doanh nghiệp), với giới hạn hàng ngày từ 100.000 đến 1.000.000 yêu cầu.

Làm cách nào để tạo một liên hệ trong HubSpot?

Gửi POST đến /crm/v3/objects/contacts với các thuộc tính bao gồm email, tên, họ và bất kỳ trường tùy chỉnh nào.

Tôi có thể tạo thuộc tính tùy chỉnh không?

Có, hãy sử dụng API Thuộc tính để tạo các trường tùy chỉnh cho bất kỳ loại đối tượng nào.

Webhooks hoạt động như thế nào trong HubSpot?

Cấu hình webhooks trong cài đặt ứng dụng của bạn. HubSpot gửi các yêu cầu POST đến điểm cuối của bạn khi các sự kiện được chỉ định xảy ra.