0-1 この教科書について
対象読者・学習目標・全体構成を確認する。
📖 対象読者
HubSpot を業務で利用しており、API・CLI・カスタムコードを使ってより高度な自動化・拡張・インテグレーションを実現したいエンジニアを対象としています。 CRM・Marketing・CMS などの各 Hub の基本操作はある程度理解していることを前提としています。
🎯 この教科書で学べること
HubSpot API の全体像から、カスタムオブジェクト設計・CMS テーマ開発・ワークフロー拡張・Webhook 設計・OAuth アプリ開発・HubSpot MCP Server を使った AI 駆動開発まで、 実務で即使える知識とコード例を体系的に学べます。
Chapter 0
全体マップ
Developer Portal・認証・環境構築
Chapter 1
CLI & 開発ワークフロー
CLI v8.0.0・ローカル開発・GitHub Actions
Chapter 2
CRM API 完全ガイド
Objects / Search / Associations / Batch API
Chapter 3
Marketing & CMS API
Forms / Email / Blog / HubDB API
Chapter 4
カスタムオブジェクト設計
スキーマ設計・プロパティ型・アソシエーション
Chapter 5
CMS テーマ & テンプレート
テーマ構造・HubL 実践・レスポンシブ設計
Chapter 6
CMS モジュール設計
fields.json・カスタムモジュール・meta.json
Chapter 7
ワークフロー拡張
Custom Code Action・Serverless Functions
Chapter 8
Webhook & イベント駆動
Webhook 設計・署名検証・外部システム連携
Chapter 9
App & OAuth 設計
Public App・OAuth 2.0・Marketplace 申請
Chapter 10
MCP Server & AI 開発
HubSpot MCP・Claude Code / Cursor 連携
Chapter 11
セキュリティ & 本番運用
トークン管理・レート制限・エラーハンドリング
0-2 HubSpot 開発エコシステムの全体像
開発者が関わるレイヤーと、各レイヤーで使うツール・API を整理する。
AI / MCP
HubSpot MCP Server
Claude Code
Cursor
↕
開発ツール
HubSpot CLI v8
VS Code
GitHub Actions
Sandbox
↕
API 層
CRM API
CMS API
Marketing API
Webhooks
OAuth 2.0
↕
HubSpot
CRM / Objects
CMS Hub
Workflows
Marketing Hub
Data Hub
↕
外部連携
SFA / ERP
データウェアハウス
Slack / Notion
カスタムアプリ
ポイント：
開発者として HubSpot に関わるとき、「どのレイヤーで何を実現したいのか」を最初に明確にすることが重要です。
CRM データの読み書きには CRM API、Web サイトのカスタマイズには CMS CLI、外部システムとのリアルタイム連携には Webhook、
そして AI を活用した開発加速には MCP Server が適しています。
0-3 Developer Portal の使い方
開発の起点となる Developer Portal（app.hubspot.com）の主要機能を把握する。
| 機能 | 場所 | 主な用途 |
|---|---|---|
| Private App | 設定 → インテグレーション → Private Apps | 社内ツール向けのアクセストークン（推奨） |
| Public App | 開発者アカウント → Apps | 他社ポータルに接続する OAuth アプリ |
| API キー（旧） | 設定 → インテグレーション → API キー | 非推奨。新規利用は避ける |
| Sandbox | 設定 → Sandbox | 本番データに影響しない開発・テスト環境 |
| API リファレンス | developers.hubspot.com | エンドポイント仕様・パラメータの確認 |
| App Marketplace | ecosystem.hubspot.com | 公開アプリの審査・掲載申請 |
⚠ API キーは非推奨：
旧来の API キー（hapikey パラメータ）は 2022年11月以降、新規作成が廃止されています。
既存のインテグレーションを更新する際は必ず Private App Token への移行を行ってください。
0-4 認証方式の選び方
HubSpot API の認証は用途によって3種類ある。状況に応じて適切な方式を選択する。
| 認証方式 | 適したケース | スコープ制御 | 推奨度 |
|---|---|---|---|
| Private App Token | 自社ポータルへのみアクセスする内部ツール | ◎ 細かく設定可能 | ★ 推奨 |
| OAuth 2.0 | 複数ポータルに接続するパブリックアプリ | ◎ ユーザー同意ベース | 標準 |
| API キー（旧） | 旧来のインテグレーション（移行推奨） | ✗ スコープ制御なし | 非推奨 |
🔑 Private App Token の特徴
Private App Token は、特定の HubSpot ポータルに紐づいたアクセストークンです。 作成時に必要なスコープのみを付与できるため、最小権限の原則に従いやすく、セキュリティ上の観点から社内ツールには最適です。 トークンは Bearer 認証で使用し、定期的なローテーションが推奨されます。
0-5 Private App Token の作成手順
実際にトークンを作成し、API を呼び出すまでの流れ。
-
1HubSpot ポータルにログイン 右上のプロフィールアイコン → 「設定（⚙）」を開く。
-
2Private Apps メニューを開く 左サイドバー → 「インテグレーション」→「Private Apps」→「Private App を作成」。
-
3アプリ名と説明を入力 用途がわかる名前をつける（例：
crm-sync-internal）。 -
4スコープを選択 「スコープ」タブから必要な権限のみにチェックを入れる。Read / Write を分けて最小権限に留めること。
-
5アプリを作成してトークンをコピー 「アプリを作成」をクリック後、表示されるトークンをコピー。再表示はできないため安全な場所に保管する。
cURL
# Private App Token を使った API 呼び出し例
curl -X GET \
"https://api.hubapi.com/crm/v3/objects/contacts?limit=10" \
-H "Authorization: Bearer YOUR_PRIVATE_APP_TOKEN" \
-H "Content-Type: application/json"
スコープ選択のコツ：
最初から全スコープを付与せず、
crm.objects.contacts.read のように機能単位で付与する習慣をつけましょう。
後から追加は可能ですが、広すぎるスコープはセキュリティリスクになります。
0-6 開発環境のセットアップ
Node.js・HubSpot CLI・環境変数の設定を行い、開発を開始できる状態にする。
📋 前提条件
Node.js 20 以上（LTS 推奨）・npm・Git が必要です。
HubSpot CLI v8.0.0 以降は Node.js 18 未満では動作しません。
node -v で確認してください。
Terminal
# Node.js バージョン確認
node -v # v20.x.x 以上であること
npm -v
# HubSpot CLI のインストール
npm install -g @hubspot/cli@latest
# バージョン確認
hs --version # 8.x.x 以上であること
Terminal — CLI 認証
# HubSpot CLI に認証情報を登録
hs auth
# 対話式で以下を入力：
# → Portal ID（ポータルの数字 ID）
# → Personal CMS Access Key または Personal Access Key
# 登録済みポータルの確認
hs config list
.env — 環境変数ファイル
# プロジェクトルートに .env ファイルを作成
HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
HUBSPOT_PORTAL_ID=12345678
NODE_ENV=development
⚠ .env を Git にコミットしない：
.gitignore に必ず .env を追加してください。
トークンが誤ってリポジトリに含まれた場合は、即座に無効化し新しいトークンを発行してください。
.gitignore
# HubSpot 開発プロジェクトの .gitignore
node_modules/
.env
.env.local
.env.*.local
dist/
.hubspot/
*.log
0-7 Sandbox の活用
本番データへの影響を避けるために、Sandbox 環境で開発・テストを行う。
| 種類 | 特徴 | 利用可能プラン |
|---|---|---|
| Developer Sandbox | 空のポータル。本番データなし。API・CLI の動作検証に最適 | 無料（開発者アカウント） |
| Standard Sandbox | 本番データのコピーを含む。より本番に近い状態でテスト可能 | Enterprise |
開発者アカウントの取得：
developers.hubspot.com から無料の開発者アカウントを作成すると、
Developer Sandbox ポータルが付与されます。API 開発・CLI 検証・カスタムオブジェクトのテストはすべてここで行いましょう。
0-8 API レート制限の基礎知識
HubSpot API にはレート制限があり、超過するとエラーになる。事前に把握しておく。
| 制限の種類 | 上限 | 備考 |
|---|---|---|
| 10秒あたりのリクエスト数 | 100 リクエスト / 10秒 | 最も一般的な制限。超過で 429 エラー |
| 1日あたりのリクエスト数 | プランによる（無料: 250,000） | Enterprise では大幅に引き上げ可能 |
| Burst 制限 | 100 リクエスト / 10秒 | バースト的なリクエストに注意 |
| Batch API | 1リクエストで最大 100 件 | 大量処理は Batch API で効率化 |
Node.js — レート制限への対処
// 429 エラー時のリトライ実装例（exponential backoff）
async function apiCallWithRetry(fn, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
if (error.response?.status === 429 && attempt < maxRetries - 1) {
const wait = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s...
await new Promise(r => setTimeout(r, wait));
} else {
throw error;
}
}
}
}
0-9 SDK の選択
HubSpot は公式 SDK を提供している。言語によって使い分ける。
| 言語 | パッケージ | 特徴 | 推奨度 |
|---|---|---|---|
| Node.js | @hubspot/api-client |
公式。TypeScript 型定義付き。最も充実 | ★ 推奨 |
| Python | hubspot-api-client |
公式。Data Hub との連携スクリプトに多用 | 推奨 |
| PHP | hubspot/hubspot-php |
コミュニティ版。公式サポート外 | 参考 |
| その他 | REST API 直接呼び出し | curl / fetch / axios など。全言語対応 | 汎用 |
Node.js — SDK のセットアップ
# インストール
npm install @hubspot/api-client
// 使用例（TypeScript / JavaScript）
import { Client } from '@hubspot/api-client';
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
});
// コンタクト一覧を取得
const contacts = await hubspotClient.crm.contacts.basicApi.getPage(
10, // limit
undefined, // after（ページネーション）
['email', 'firstname', 'lastname'] // properties
);
console.log(contacts.results);
0-10 この章のまとめ
次章（CLI & 開発ワークフロー）に進む前に、重要ポイントを整理する。
✅ Chapter 0 チェックリスト
- HubSpot 開発エコシステムの全体像（API層・ツール層・AI層）を理解した
- Developer Portal の主要機能（Private App・Sandbox・API リファレンス）を把握した
- Private App Token を作成し、必要なスコープのみを付与した
- API キー（旧）が非推奨であることを確認した
- Node.js 20 以上 + HubSpot CLI v8.x をインストールした
- hs auth でポータル認証を完了した
- .env ファイルを作成し、.gitignore に追加した
- Developer Sandbox ポータルを取得（または作成予定）した
- レート制限（100 req/10秒）と exponential backoff の考え方を理解した
- Node.js SDK（@hubspot/api-client）の基本的な使い方を確認した
次章（Chapter 1）について：
HubSpot CLI v8.0.0 の詳細な使い方、ローカル開発環境の構築、GitHub Actions を使った CI/CD パイプラインの設定を学びます。
CLI の基本コマンドから、テーマ・モジュールのアップロード自動化まで、実践的なワークフローを構築します。