HubSpotカスタムコードによるCRM拡張｜ワークフロー・API・カスタムカードの開発

「HubSpotの標準機能だけでは、自社固有のビジネスロジックを実装できない」

「外部システムとの連携を自動化したいが、iPaaSでは対応しきれない」

——こうしたケースでは、カスタムコードによるCRM拡張が有力な選択肢になります。

HubSpotのカスタムコード機能とは、ワークフロー内でNode.jsやPythonのコードを実行したり、APIを使って外部システムと連携したり、レコード画面にカスタムカード（UI Extensions）を追加したりできる開発者向けの拡張機能のことです。

この記事では、カスタムコードの3つの活用パターンと、それぞれの実装方法、設計上の注意点を解説します。

この記事でわかること

• HubSpotカスタムコードの3つの活用パターン
• ワークフロー内カスタムコードの実装方法
• HubSpot APIの基本と主な活用シーン
• カスタムカード（UI Extensions）の概要と設計
• カスタムコード開発の注意点とベストプラクティス

カスタムコードの3つの活用パターン

パターン1: ワークフロー内のカスタムコードアクション

ワークフローの中で、標準アクションでは実現できない処理をNode.jsまたはPythonで実装します。Professional以上のプランで利用可能です。

活用例:

• 取引が受注ステージに移行したら、12ヶ月分の請求レコードを自動作成
• フォーム送信時に外部API（与信チェック、郵便番号→住所変換等）を呼び出し
• 複雑な条件分岐のビジネスロジック（標準のif/thenでは表現しきれないもの）
• カスタムオブジェクトの一括作成・更新

パターン2: HubSpot API による外部連携

HubSpotのREST APIを使って、外部システムとデータを双方向にやり取りします。

活用例:

• 基幹システム（ERP/会計ソフト）との受注データ同期
• 外部のBIツールへのデータエクスポート
• 自社プロダクトのユーザー行動データのCRM同期
• 請求書発行システムとの連携

パターン3: カスタムカード（UI Extensions）

HubSpotのレコード画面（コンタクト・会社・取引等）に、独自のUIコンポーネントを追加します。

活用例:

• 外部システムのデータをレコード画面にリアルタイム表示
• 独自の計算結果やスコアをビジュアル表示
• ワンクリックで外部APIを呼び出すアクションボタン
• 取引レコード内に請求管理のミニダッシュボードを表示

ワークフロー内カスタムコードの実装

基本的な流れ

1. ワークフローを新規作成（または既存ワークフローを編集）
2. アクションに「カスタムコード」を追加
3. 言語を選択（Node.js 20 / Python）
4. コードを記述
5. 入力プロパティ・出力プロパティを設定
6. テスト実行で動作確認

実装例: 受注時に請求レコードを自動生成

取引が「受注」ステージに移行した際に、月額料金×契約期間分の請求カスタムオブジェクトレコードを自動生成する例です。

// Node.js example (simplified)
const hubspot = require('@hubspot/api-client');

exports.main = async (event, callback) => {
  const hubspotClient = new hubspot.Client({
    accessToken: process.env.SECRET_TOKEN
  });

  const dealId = event.object.objectId;
  const monthlyAmount = event.inputFields['monthly_amount'];
  const contractMonths = event.inputFields['contract_months'];

  // 契約月数分の請求レコードを作成
  for (let i = 0; i < contractMonths; i++) {
    const billingDate = new Date();
    billingDate.setMonth(billingDate.getMonth() + i);

    await hubspotClient.crm.objects.basicApi.create(
      'billing_records', // カスタムオブジェクト
      {
        properties: {
          billing_amount: monthlyAmount,
          billing_date: billingDate.toISOString(),
          status: 'scheduled',
          deal_id: dealId
        }
      }
    );
  }

  callback({ outputFields: { records_created: contractMonths } });
};

カスタムコードの制限事項

• 実行時間: 最大20秒
• メモリ: 128MB
• 外部ライブラリ: @hubspot/api-client, axios, lodash等の一部のみ利用可能
• シークレット: 環境変数でAPIキー等を安全に管理

HubSpot APIの基本

主なAPIカテゴリ

API認証

HubSpotのAPIはPrivate App Token（旧API Key）で認証します。

1. HubSpotの設定 → 統合 → Private Apps
2. 新しいPrivate Appを作成
3. 必要なスコープ（権限）を設定
4. トークンを取得

スコープは最小限に設定するのがベストプラクティスです。全権限を付与してしまうと、トークンが漏洩した場合のリスクが大きくなります。

実装例: 外部システムからのデータ同期

// 外部の請求管理システムからHubSpotに請求データを同期
const axios = require('axios');

const HUBSPOT_TOKEN = 'your-private-app-token';

async function syncBillingData(externalBillingId, dealId) {
  // 外部システムから請求データを取得
  const billingData = await axios.get(
    `https://billing-system.example.com/api/invoices/${externalBillingId}`
  );

  // HubSpotの取引を更新
  await axios.patch(
    `https://api.hubapi.com/crm/v3/objects/deals/${dealId}`,
    {
      properties: {
        billing_status: billingData.data.status,
        last_payment_date: billingData.data.lastPaymentDate
      }
    },
    {
      headers: {
        Authorization: `Bearer ${HUBSPOT_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  );
}

APIレート制限

HubSpotのAPIにはレート制限があります。

• Private App: 1秒あたり100リクエスト（Professional）、1秒あたり200リクエスト（Enterprise）
• バッチAPI: 1リクエストで最大100件のレコードを一括操作可能

大量データの処理にはバッチAPIの活用が必須です。1件ずつAPIを叩くと、レート制限に引っかかる上にパフォーマンスも悪化します。

カスタムカード（UI Extensions）

概要

カスタムカードは、HubSpotのレコード画面の右側パネルに独自のUIコンポーネントを表示する機能です。HubSpot Developer Platformの一部として提供されています。

開発環境

• フレームワーク: React ベース
• 開発ツール: HubSpot CLI（hs-cli）
• ホスティング: HubSpotのサーバーレス環境
• 言語: JavaScript/TypeScript

活用パターン

外部データの表示カード

取引レコードを開いたときに、外部の請求管理システムの支払い状況を自動表示。営業担当が「この顧客の請求は滞っていないか」をHubSpotの画面だけで確認できます。

アクションボタンカード

「契約書を生成」「請求書を発行」といったボタンを配置し、ワンクリックで外部APIを呼び出し。画面を行き来する手間が省けます。

カスタムコード開発の注意点

1. 標準機能でできないか先に検討

カスタムコードは強力ですが、メンテナンスコストが発生します。まず計算プロパティ・ワークフローの標準アクション・iPaaS（Zapier/Yoom）で代替できないか検討し、それでも対応できない場合にカスタムコードを使うという優先順位が重要です。

2. エラーハンドリング

ワークフロー内のカスタムコードでエラーが発生した場合、ワークフロー全体が停止します。try-catchでエラーをハンドリングし、エラー時の通知（管理者へのメール）を仕組み化しておきましょう。

3. サンドボックスでのテスト

カスタムコードの変更は、必ずサンドボックス環境でテストしてから本番にデプロイしましょう。特にCRMデータを更新するコードは、意図しないデータ変更のリスクがあります。

4. ドキュメント化

カスタムコードは開発者以外には理解しにくいため、何をするコードか・なぜ必要か・入出力の仕様をドキュメント化しておくことが重要です。開発者が退職した後にメンテナンスできなくなるリスクを防ぎます。

5. シークレットの管理

APIキーやトークンをコード内にハードコードせず、HubSpotのシークレット管理機能を使って環境変数として保存しましょう。

まとめ

HubSpotのカスタムコード機能は、標準機能では対応しきれないビジネスロジックや外部連携を実現する強力な拡張手段です。

まずは標準機能とiPaaSで対応できる範囲を把握し、それでも不足する部分にカスタムコードを適用するのがベストプラクティスです。ワークフロー内カスタムコードで業務ロジックの自動化から始め、必要に応じてAPI連携やカスタムカードに拡張していきましょう。

HubSpotの導入・活用についてお気軽にご相談ください

StartLinkでは、HubSpotの導入設計からカスタム開発まで、企業様の状況に合わせた支援を行っています。

「カスタムコードで業務を自動化したい」「外部システムとのAPI連携を相談したい」——そんなお悩みをお持ちでしたら、ぜひ一度ご相談ください。

無料相談はこちら → StartLink お問い合わせ

よくある質問（FAQ）

Q1. カスタムコードを使うにはプログラミングスキルが必要ですか？

はい、Node.jsまたはPythonの基本的なプログラミングスキルが必要です。ただし、単純な外部APIの呼び出しやプロパティの計算であれば、テンプレートを参考にして実装できるレベルです。高度な開発が必要な場合は、HubSpotの開発パートナーに依頼するのも選択肢です。

Q2. ワークフローのカスタムコードはどのプランで使えますか？

カスタムコードアクションはProfessional以上のプランで利用可能です。API連携はすべてのプランで利用可能ですが、レート制限がプランによって異なります。カスタムカード（UI Extensions）はDeveloper Platformの一部で、Enterprise以上が推奨されます。

Q3. iPaaS（Zapier/Yoom）とカスタムコードの使い分けは？

iPaaSは「ツールAでイベント発生→ツールBにアクション」というシンプルな連携に向いています。複雑な条件分岐、ループ処理、データの加工・変換が必要な場合や、APIの呼び出し頻度が高い場合はカスタムコードの方が適しています。コスト面では、iPaaSは月額費用がかかりますが、開発・メンテナンスコストは低いというトレードオフがあります。

Q4. HubSpotのAPIドキュメントはどこにありますか？

HubSpotの開発者ドキュメント（developers.hubspot.com）に詳細なAPIリファレンスがあります。エンドポイント別のサンプルコード、認証方法、レート制限の説明が充実しています。HubSpot Developer Communityも活発で、開発上の疑問はそこで解決できるケースが多いです。

この記事は2025年3月時点の情報に基づいています。HubSpotの機能は定期的にアップデートされるため、最新情報はHubSpot公式サイトでご確認ください。

関連記事:

• HubSpotワークフロー設計ガイド
• HubSpot Enterprise活用ガイド
• HubSpotアプリ連携の設計方法