---

name: hubspot-integration description: HubSpot CRM 集成的专家模式，包括 OAuth 认证、CRM 对象、关联、批量操作、Webhooks 和自定义对象。涵盖 Node.js 和 Python SDK。 risk: unknown source: vibeship-spawner-skills (Apache 2.0) date_added: 2026-02-27

HubSpot 集成

HubSpot CRM 集成的专家模式，包括 OAuth 认证、CRM 对象、关联、批量操作、Webhooks 和自定义对象。涵盖 Node.js 和 Python SDK。

模式

OAuth 2.0 认证

公共应用的安全认证

使用场景: 构建公共应用或多账户集成

模板

// OAuth 2.0 flow for HubSpot
import { Client } from "@hubspot/api-client";

const CLIENT_ID = process.env.HUBSPOT_CLIENT_ID;
const CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const REDIRECT_URI = process.env.HUBSPOT_REDIRECT_URI;
const SCOPES = "crm.objects.contacts.read crm.objects.contacts.write";

function getAuthUrl(): string {
  const authUrl = new URL("https://app.hubspot.com/oauth/authorize");
  authUrl.searchParams.set("client_id", CLIENT_ID);
  authUrl.searchParams.set("redirect_uri", REDIRECT_URI);
  authUrl.searchParams.set("scope", SCOPES);
  return authUrl.toString();
}

async function handleOAuthCallback(code: string) {
  const response = await fetch("https://api.hubapi.com/oauth/v1/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
      code: code,
    }),
  });
  const tokens = await response.json();
  await storeTokens(tokens);
  return tokens;
}

async function refreshAccessToken(refreshToken: string) {
  const response = await fetch("https://api.hubapi.com/oauth/v1/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken,
    }),
  });
  return response.json();
}

function createClient(accessToken: string): Client {
  return new Client({ accessToken });
}

注意事项

• 访问令牌在 30 分钟后过期
• 在过期前刷新令牌
• 安全存储刷新令牌
• 每 6 个月轮换令牌

私有应用令牌

单账户集成的认证方式

使用场景: 为单个 HubSpot 账户构建内部集成

模板

import { Client } from "@hubspot/api-client";

const hubspotClient = new Client({
  accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN,
});

async function getContacts() {
  try {
    const response = await hubspotClient.crm.contacts.basicApi.getPage(
      100,
      undefined,
      ["firstname", "lastname", "email", "phone"],
    );
    return response.results;
  } catch (error) {
    if (error.code === 429) {
      const retryAfter = error.headers?.["retry-after"] || 10;
      await sleep(retryAfter * 1000);
      return getContacts();
    }
    throw error;
  }
}

注意事项

• 私有应用令牌不会过期
• 所有私有应用共享每日速率限制
• 每个私有应用有自己的突发限制
• 建议：每 6 个月轮换一次

CRM 对象 CRUD 操作

创建、读取、更新、删除 CRM 记录

使用场景: 处理联系人、公司、交易、工单

模板

import { Client } from "@hubspot/api-client";

const hubspotClient = new Client({
  accessToken: process.env.HUBSPOT_TOKEN,
});

async function createContact(data: {
  email: string;
  firstname: string;
  lastname: string;
}) {
  const response = await hubspotClient.crm.contacts.basicApi.create({
    properties: {
      email: data.email,
      firstname: data.firstname,
      lastname: data.lastname,
    },
  });
  return response;
}

async function getContact(contactId: string) {
  const response = await hubspotClient.crm.c