---
title: "HubSpot コネクター"
description: "HubSpot CRM のコンタクト、企業、取引、チケット、マーケティングデータを Tajo 経由で Brevo と同期するための完全統合ガイド。"
url: https://tajo.io/jp/docs/connectors/crm/hubspot/
markdown: https://tajo.io/jp/docs/connectors/crm/hubspot.md
lang: ja-JP
robots: noindex
---

先行利用を申し込む

お名前と会社のメールアドレスを入力してください。Tajoへのアクセス申請を確認するためのリンクをメールでお送りします。

# HubSpot コネクター

コネクターのステータス: 開発中 構築中です。まだ検証されていません。

| 送信元フィールド | 送信先フィールド | サンプル値 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

HubSpot CRM を Tajo 経由で Brevo に接続して、双方向のコンタクト同期、取引追跡、エンゲージメントデータ、両プラットフォームにまたがる統一されたマーケティングオートメーションを実現します。

## 概要

| 項目 | 値 |
| --- | --- |
| **プラットフォーム** | HubSpot |
| **カテゴリー** | CRM |
| **セットアップ難易度** | 中 |
| **公式統合** | なし |
| **同期データ** | コンタクト、企業、取引、チケット、イベント |
| **API ベース URL** | `https://api.hubapi.com` |

## 機能

- **双方向コンタクト同期** - HubSpot と Brevo の間でコンタクトをリアルタイム同期
- **取引パイプライン追跡** - 売上ベースのセグメンテーションに取引ステージと金額を同期
- **企業データ同期** - コンタクトを企業レコードとファーモグラフィックデータに紐付け
- **チケット統合** - カスタマーヘルススコアリング向けにサポートチケットを追跡
- **エンゲージメント追跡** - メール開封、クリック、会議、通話、メモを同期
- **カスタムオブジェクト対応** - HubSpot カスタムオブジェクトを Brevo 属性にマッピング
- **ワークフロートリガー** - HubSpot ライフサイクルステージ変更で Brevo 自動化をトリガー
- **ウェブフックイベント** - CRM データ変更のリアルタイム通知

## 前提条件

開始する前に、以下をご用意ください。

1. HubSpot アカウント (Free、Starter、Professional、Enterprise いずれも可)
2. 必要なスコープを持つ HubSpot プライベートアプリまたは OAuth アプリ
3. API アクセス付きの Brevo アカウント
4. Tajo アカウント

## 認証

### プライベートアプリのアクセストークン (推奨)

HubSpot にプライベートアプリを作成し、きめ細かいスコープ管理で直接 API アクセスを行います。

1. HubSpot Settings > Integrations > Private Apps に移動
2. 新規プライベートアプリを作成
3. 必要なスコープを設定
4. アクセストークンをコピー

```bash
curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

### OAuth 2.0

ユーザー承認を必要とするマルチアカウント統合には OAuth 2.0 を使用します。

```bash
# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}
```

#### 必要なスコープ

```
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.schemas.custom.read
```

## 設定

### 基本セットアップ

```yaml
connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Data sync options
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: true
      engagements: true

    # Sync direction
    direction: bidirectional  # or 'hubspot_to_brevo' | 'brevo_to_hubspot'

    # List assignment in Brevo
    lists:
      all_contacts: 10
      qualified_leads: 11
      customers: 12
```

### フィールドマッピング

HubSpot のプロパティを Brevo コンタクト属性にマッピングします。

#### 既定のマッピング

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | コンタクトのメールアドレス (主識別子) |
| `firstname` optional | string | Brevo の FIRSTNAME 属性にマッピング |
| `lastname` optional | string | Brevo の LASTNAME 属性にマッピング |
| `phone` optional | string | WhatsApp/SMS 用の SMS 属性にマッピング |
| `company` optional | string | 紐づく企業名 |
| `lifecyclestage` optional | string | HubSpot ライフサイクルステージ (subscriber、lead、MQL、SQL、customer) |
| `hs_lead_status` optional | string | リード選定ステータス |
| `hubspot_owner_id` optional | string | 担当営業 ID |

#### カスタムプロパティマッピング

```yaml
field_mapping:
  # Standard fields
  email: email
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # CRM fields
  lifecyclestage: LIFECYCLE_STAGE
  hs_lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Deal metrics
  hs_total_deal_value: DEAL_VALUE
  num_associated_deals: DEAL_COUNT

  # Custom properties
  preferred_channel: PREFERRED_CHANNEL
  customer_segment: SEGMENT
```

## API エンドポイント

### CRM オブジェクト

| メソッド | エンドポイント | 説明 |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/contacts` | コンタクト一覧 |
| `POST` | `/crm/v3/objects/contacts` | コンタクトを作成 |
| `PATCH` | `/crm/v3/objects/contacts/{id}` | コンタクトを更新 |
| `GET` | `/crm/v3/objects/companies` | 企業一覧 |
| `GET` | `/crm/v3/objects/deals` | 取引一覧 |
| `POST` | `/crm/v3/objects/deals` | 取引を作成 |
| `GET` | `/crm/v3/objects/tickets` | チケット一覧 |

### アソシエーション

| メソッド | エンドポイント | 説明 |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | アソシエーションを取得 |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | アソシエーションを作成 |

### エンゲージメント

| メソッド | エンドポイント | 説明 |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/calls` | 通話エンゲージメント一覧 |
| `GET` | `/crm/v3/objects/emails` | メールエンゲージメント一覧 |
| `GET` | `/crm/v3/objects/meetings` | 会議一覧 |
| `GET` | `/crm/v3/objects/notes` | メモ一覧 |
| `GET` | `/crm/v3/objects/tasks` | タスク一覧 |

## イベント

### コンタクトイベント

| イベント | トリガー | 用途 |
| --- | --- | --- |
| `contact.creation` | 新規コンタクト作成 | ウェルカムフロートリガー |
| `contact.propertyChange` | コンタクトプロパティ更新 | 属性同期 |
| `contact.merge` | コンタクト統合 | 重複排除処理 |
| `contact.deletion` | コンタクト削除 | Brevo 側クリーンアップ |

### 取引イベント

| イベント | トリガー | 用途 |
| --- | --- | --- |
| `deal.creation` | 新規取引作成 | 営業通知 |
| `deal.propertyChange` | 取引ステージ変更 | パイプライン自動化 |
| `deal.deletion` | 取引削除 | 売上レポート |

### 企業イベント

| イベント | トリガー | 用途 |
| --- | --- | --- |
| `company.creation` | 新規企業追加 | ABM |
| `company.propertyChange` | 企業データ更新 | ファーモグラフィック同期 |

## コード例

### コネクターの初期化

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});
```

### コンタクト同期の実行

```javascript
// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
  type: 'full',
  resources: ['contacts', 'companies', 'deals'],
  direction: 'bidirectional',
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 34200,
//   companiesSynced: 5100,
//   dealsSynced: 2340
// }
```

### ウェブフックイベントの処理

```javascript
// Handle HubSpot webhook notifications
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature-v3');

  // Verify webhook signature
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      eventType: event.subscriptionType,
      objectId: event.objectId,
      propertyName: event.propertyName,
      propertyValue: event.propertyValue
    });
  }

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

## レート制限

HubSpot はプライベートアプリまたは OAuth アプリごとにレート制限を適用します。

| プラン | レート制限 | バースト制限 |
| --- | --- | --- |
| Free/Starter | 100 リクエスト/10 秒 | 150 リクエスト/10 秒 |
| Professional | 150 リクエスト/10 秒 | 200 リクエスト/10 秒 |
| Enterprise | 200 リクエスト/10 秒 | 250 リクエスト/10 秒 |
| API アドオン | 200 リクエスト/10 秒 | 250 リクエスト/10 秒 |

追加制限:

- **Search API**: アプリあたり 5 リクエスト/秒
- **バッチ操作**: バッチリクエストあたり 100 レコード
- **日次制限**: 500,000 リクエスト/日 (OAuth アプリ)

レート制限の処理

HubSpot は制限超過時に `429 Too Many Requests` を返します。指数バックオフを使用し、`X-HubSpot-RateLimit-*` ヘッダーを監視してください。

## トラブルシューティング

### よくある問題

| 問題 | 原因 | 解決策 |
| --- | --- | --- |
| 401 Unauthorized | 期限切れまたは無効なトークン | プライベートアプリトークンを再生成または OAuth トークンをリフレッシュ |
| コンタクトが同期されない | email プロパティ不足 | HubSpot コンタクトは Brevo 同期にメール必須 |
| 重複コンタクト | 重複排除ルール未設定 | HubSpot でマージルールを設定 |
| ウェブフック未受信 | 購読未有効 | ウェブフック購読を再登録 |
| プロパティ未マッピング | カスタムプロパティ未作成 | まず HubSpot でプロパティを作成 |

### デバッグモード

詳細ログを有効化します。

```yaml
connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### 接続テスト

```bash
tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered
```

## ベストプラクティス

1. **API キーよりプライベートアプリを利用** - API キーは非推奨。セキュリティ向上のためプライベートアプリを使用
2. **双方向同期は慎重に実装** - 同期元を追跡して無限ループを防止
3. **ライフサイクルステージをマッピング** - HubSpot ライフサイクルステージで Brevo 内のコンタクトをセグメント化
4. **API リクエストをバッチ化** - バルク操作にバッチエンドポイントを利用してレート制限内に収める
5. **ウェブフック配信を監視** - リトライロジックとデッドレター処理を設定
6. **増分同期を使用** - `lastmodifieddate` プロパティで変更分のみ同期

## セキュリティ

- **プライベートアプリトークン** - きめ細かい権限のスコープ付きアクセストークン
- **OAuth 2.0** - リフレッシュトークンローテーション対応の業界標準認可
- **ウェブフック署名** - HMAC ベースの署名検証 (v3)
- **TLS 暗号化** - すべての API 通信は転送時に暗号化
- **スコープ権限** - 統合ごとに必要最小限のスコープアクセス

## 関連リソース

- [HubSpot API ドキュメント](https://developers.hubspot.com/docs/api/overview)
- [HubSpot 認証ガイド](https://developers.hubspot.com/docs/api/working-with-oauth)
- [Salesforce コネクター](https://tajo.io/jp/docs/connectors/crm/salesforce)
- [顧客同期スキル](https://tajo.io/jp/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/jp/docs/contact-management)