วิธีใช้ HubSpot API ปี 2026

สรุปสาระสำคัญ

API ของ HubSpot ช่วยให้นักพัฒนาสามารถผสานรวมกับ CRM, การตลาด, การขาย และศูนย์บริการ (service hubs) ได้โดยอัตโนมัติ โดยใช้การยืนยันตัวตนด้วย OAuth 2.0 และ Private App รวมถึง RESTful endpoints สำหรับผู้ติดต่อ, บริษัท, ดีล, ตั๋วสนับสนุน และอื่นๆ พร้อมการจำกัดจำนวนคำขอ (rate limits) ตามระดับการสมัครสมาชิก คู่มือนี้ครอบคลุมการตั้งค่าการยืนยันตัวตน, endpoints หลัก, webhooks และกลยุทธ์การผสานรวมสำหรับการใช้งานจริง

บทนำ

HubSpot จัดการบัญชีลูกค้ากว่า 194,000 บัญชี และบันทึก CRM หลายพันล้านรายการ สำหรับนักพัฒนาที่สร้างการผสานรวม CRM, ระบบการตลาดอัตโนมัติ หรือเครื่องมือการขาย การผสานรวมกับ HubSpot API ไม่ใช่ทางเลือก แต่เป็นสิ่งจำเป็นสำหรับการเข้าถึงผู้ใช้งานกว่า 7 ล้านคน

นี่คือความเป็นจริง: ธุรกิจต่างๆ เสียเวลา 15-20 ชั่วโมงต่อสัปดาห์ไปกับการป้อนข้อมูลด้วยตนเองระหว่างระบบ การผสานรวม HubSpot API ที่แข็งแกร่งจะช่วยให้การซิงโครไนซ์ผู้ติดต่อ, การอัปเดตดีล, เวิร์กโฟลว์การตลาด และการรายงานข้ามแพลตฟอร์มเป็นไปโดยอัตโนมัติ

HubSpot API คืออะไร?

HubSpot มี RESTful API สำหรับการเข้าถึงข้อมูล CRM และฟังก์ชันการทำงานด้านการตลาดอัตโนมัติ API จัดการสิ่งต่อไปนี้:

• ผู้ติดต่อ, บริษัท, ดีล, ตั๋วสนับสนุน และออบเจกต์ที่กำหนดเอง
• อีเมลการตลาดและหน้า Landing Page
• ไปป์ไลน์การขายและลำดับการขาย
• ตั๋วสนับสนุนและบทสนทนา
• การวิเคราะห์และรายงาน
• เวิร์กโฟลว์และระบบอัตโนมัติ
• ไฟล์และเนื้อหา

คุณสมบัติหลัก

ภาพรวมสถาปัตยกรรม API

HubSpot ใช้ REST API ที่มีเวอร์ชัน:

https://api.hubapi.com/

การเปรียบเทียบเวอร์ชัน API

สำคัญ: HubSpot ได้ยกเลิกการใช้งาน API key authentication และหันมาใช้ OAuth 2.0 และ Private Apps แทน โปรดย้ายการผสานรวมทั้งหมดทันที

เริ่มต้นใช้งาน: การตั้งค่าการยืนยันตัวตน

ขั้นตอนที่ 1: สร้างบัญชีนักพัฒนา HubSpot ของคุณ

ก่อนเข้าถึง API:

1. เยี่ยมชม HubSpot Developer Portal
2. ลงชื่อเข้าใช้ด้วยบัญชี HubSpot ของคุณ (หรือสร้างบัญชีใหม่)
3. ไปที่ Apps ในแดชบอร์ดนักพัฒนา
4. คลิก Create app

ขั้นตอนที่ 2: เลือกวิธีการยืนยันตัวตน

HubSpot รองรับวิธีการยืนยันตัวตนสองวิธี:

ขั้นตอนที่ 3: ตั้งค่า Private App (แนะนำสำหรับการผสานรวมภายใน)

สร้าง Private App สำหรับการเข้าถึงพอร์ทัลเดียว:

1. ไปที่ Settings > Integrations > Private Apps
2. คลิก Create a private app
3. กำหนดค่าสิทธิ์ (scopes):

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

1. สร้างโทเค็นการเข้าถึง
2. คัดลอกและจัดเก็บอย่างปลอดภัย

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

ขั้นตอนที่ 4: ตั้งค่า OAuth 2.0 (สำหรับแอปแบบหลายผู้เช่า)

กำหนดค่า OAuth สำหรับการเข้าถึงหลายพอร์ทัล:

1. ไปที่ Apps > Create app
2. กำหนดค่าการตั้งค่าการยืนยันตัวตน:

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

ขั้นตอนที่ 5: แลกเปลี่ยนโค้ดเพื่อรับ Access Token

จัดการ OAuth callback:

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

ขั้นตอนที่ 6: รีเฟรช Access Token

Access token จะหมดอายุหลังจาก 6 ชั่วโมง:

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

ขั้นตอนที่ 7: เรียกใช้ API ที่มีการยืนยันตัวตน

สร้างไคลเอนต์ API ที่นำกลับมาใช้ใหม่ได้:

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

การทำงานกับออบเจกต์ CRM

การสร้างผู้ติดต่อ

สร้างหรืออัปเดตผู้ติดต่อ:

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

คุณสมบัติผู้ติดต่อ

การดึงข้อมูลผู้ติดต่อ

ดึงข้อมูลผู้ติดต่อด้วย 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}`);

การค้นหาผู้ติดต่อ

ค้นหาด้วยตัวกรอง:

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

ตัวดำเนินการตัวกรองการค้นหา

การสร้างบริษัท

สร้างบันทึกบริษัท:

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

การเชื่อมโยงออบเจกต์

เชื่อมโยงผู้ติดต่อกับบริษัท:

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

ประเภทการเชื่อมโยง

การสร้างดีล

สร้างโอกาสการขาย:

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

ขั้นตอนของดีล (Default Pipeline)

Webhooks

การกำหนดค่า Webhooks

ตั้งค่า webhooks สำหรับการแจ้งเตือนแบบเรียลไทม์:

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

ประเภทเหตุการณ์ Webhook

การจัดการ 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')
  );
}

การจำกัดจำนวนคำขอ

ทำความเข้าใจเกี่ยวกับการจำกัดจำนวนคำขอ

HubSpot บังคับใช้การจำกัดจำนวนคำขอตามระดับการสมัครสมาชิก:

การเกินขีดจำกัดจะส่งผลให้ได้รับข้อความตอบกลับ HTTP 429 (Too Many Requests)

เฮดเดอร์การจำกัดจำนวนคำขอ

การนำการจัดการการจำกัดจำนวนคำขอไปใช้

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

รายการตรวจสอบสำหรับการนำไปใช้งานจริง

ก่อนที่จะเปิดใช้งานจริง:

• [ ] ใช้การยืนยันตัวตนด้วย Private App หรือ OAuth 2.0
• [ ] จัดเก็บโทเค็นอย่างปลอดภัย (ในฐานข้อมูลที่เข้ารหัส)
• [ ] ใช้การรีเฟรชโทเค็นอัตโนมัติ
• [ ] ตั้งค่าการจำกัดจำนวนคำขอและการจัดคิวคำขอ
• [ ] กำหนดค่า webhook endpoint ด้วย HTTPS
• [ ] ใช้การจัดการข้อผิดพลาดที่ครอบคลุม
• [ ] เพิ่มการบันทึกสำหรับการเรียกใช้ API ทั้งหมด
• [ ] ตรวจสอบการใช้งานการจำกัดจำนวนคำขอ
• [ ] สร้าง Runbook สำหรับปัญหาทั่วไป

กรณีการใช้งานจริง

การซิงโครไนซ์ CRM

บริษัท SaaS ทำการซิงค์ข้อมูลลูกค้า:

• ความท้าทาย: การป้อนข้อมูลด้วยตนเองระหว่างแอปและ HubSpot
• วิธีแก้ปัญหา: การซิงค์แบบเรียลไทม์ผ่าน webhooks และ API
• ผลลัพธ์: ไม่มีการป้อนข้อมูลด้วยตนเอง, ความถูกต้องของข้อมูล 100%

การจัดเส้นทาง Lead

เอเจนซี่การตลาดทำให้การจัดจำหน่าย Lead เป็นไปโดยอัตโนมัติ:

• ความท้าทาย: เวลาตอบสนองต่อ Lead ช้า
• วิธีแก้ปัญหา: การจัดเส้นทางไปยังตัวแทนขายโดยใช้ Webhook เป็นตัวกระตุ้น
• ผลลัพธ์: เวลาตอบสนอง 5 นาที, เพิ่มอัตราการแปลง 40%

สรุป

HubSpot API มีความสามารถด้าน CRM และการตลาดอัตโนมัติที่ครอบคลุม ประเด็นสำคัญ:

• ใช้ OAuth 2.0 สำหรับแอปแบบหลายผู้เช่า, Private Apps สำหรับการผสานรวมภายใน
• การจำกัดจำนวนคำขอจะแตกต่างกันไปตามระดับ (100-400 คำขอ/วินาที)
• Webhooks ช่วยให้สามารถซิงโครไนซ์ข้อมูลแบบเรียลไทม์ได้
• ออบเจกต์ CRM รองรับการเชื่อมโยงและคุณสมบัติที่กำหนดเอง
• Apidog ช่วยให้การทดสอบ API และการทำงานร่วมกันในทีมง่ายขึ้น

ส่วนคำถามที่พบบ่อย

ฉันจะยืนยันตัวตนกับ HubSpot API ได้อย่างไร?

ใช้ OAuth 2.0 สำหรับแอปแบบหลายผู้เช่า หรือ Private Apps สำหรับการผสานรวมพอร์ทัลเดียว การยืนยันตัวตนด้วย API key ถูกยกเลิกแล้ว

การจำกัดจำนวนคำขอของ HubSpot คืออะไร?

การจำกัดจำนวนคำขอมีตั้งแต่ 100 คำขอ/วินาที (ฟรี) ถึง 400 คำขอ/วินาที (Enterprise) โดยมีขีดจำกัดรายวันตั้งแต่ 100,000 ถึง 1 ล้านคำขอ

ฉันจะสร้างผู้ติดต่อใน HubSpot ได้อย่างไร?

ส่งคำขอ POST ไปยัง /crm/v3/objects/contacts พร้อมด้วยคุณสมบัติ เช่น อีเมล, ชื่อจริง, นามสกุล และฟิลด์ที่กำหนดเองใดๆ

ฉันสามารถสร้างคุณสมบัติที่กำหนดเองได้หรือไม่?

ได้ คุณสามารถใช้ Properties API เพื่อสร้างฟิลด์ที่กำหนดเองสำหรับออบเจกต์ทุกประเภท

Webhooks ทำงานอย่างไรใน HubSpot?

กำหนดค่า webhooks ในการตั้งค่าแอปของคุณ HubSpot จะส่งคำขอ POST ไปยัง endpoint ของคุณเมื่อเกิดเหตุการณ์ที่ระบุ