Zoho拡張アプリ v3.0 の設定方法

Zoho拡張アプリ Ver. 3.0.0 がリリースされました。それにより、ZohoCRM v8 に対応し一新されたこと、フォームの設定方法がわかりづらかったので、こちらのドキュメントでご説明させていただきます。

拡張アプリのインストールと認証方法は GitHub の README をご確認ください。

a-blog cms で扱う Zoho CRM のデータ

まずは Zoho CRM の簡単な説明です。

a-blog cms で扱うZohoのデータには、タブ / レコード / 項目 というデータの構造があります。

1

タブ

データの種類を表す単位で、連絡先や取引先など同じ形のデータをまとめるもの。

2

レコード

タブに属する1件分のデータで一意のIDを持つ。

3

項目

最小単位のカラムで、氏名やメールなどが当たり、様々なタイプ（型）を持つ。

以下の画像は、実際の Zoho CRM管理画面です。（2026/2/26 時点）

また、タブと項目には API名 という識別子が付いています。Zoho CRM の管理画面「設定 > 開発者向け情報 > API と SDK」で等タブの一覧と各タブに対応する項目一覧のAPI名を確認できます。a-blog cms 側の設定でこのAPI名を使う場面があるため、確認方法を覚えておいてください。

フォーム設定

Zoho拡張アプリがインストールでき認証が完了すると、管理画面「フォーム管理」から対象のフォームIDを開くと、【Zoho Form 設定】 という見出しの設定項目が表示されます。

この画面では認証済みの Zoho CRM の情報（タブ一覧・項目一覧）を自動で取得しており、ドロップダウンで選択できるようになっています。また、「Zoho CRM連携を有効にする」にチェックを入れると連携が有効になります。

設定は以下の 3つのセクション で構成されています。

  1. タブのユニークキー設定

  2. Zohoと連携するa-blog cmsフィールドの設定

  3. Zohoリレーショナル設定

1. タブのユニークキー設定

「ユニークキー」とは、Zoho CRM 上でレコードを一意に識別するために使う項目のことです。このセクションでは どのタブに対してレコードを「追加」または「更新」するか を設定します。同じユニークキーを持つレコードがすでに存在する場合は「更新」、存在しない場合は「追加」という動作になります。

設定項目

項目名

説明

ユニークキーにする項目のAPI名

Zoho CRM側で一意性を判断するための項目のAPI名。例：Email

追加を許可するタブ名

このユニークキーを使ってレコードを新規追加するZohoのタブを選択

更新を許可するタブ名

このユニークキーを使ってレコードを更新するZohoのタブを選択

API名の確認方法

Zoho CRM の「設定 > 開発者向け情報 > API と SDK」を開き、対象のタブを選択すると項目一覧が表示されます。「API名」の列の値をコピーして使用してください。

標準的な項目のAPI名の例：

  • メール … Email

  • 姓 … Last_Name

  • 名 … First_Name

  • 電話 … Phone

2. Zohoと連携するa-blog cmsフィールドの設定

このセクションでは a-blog cms のフォームフィールドと Zoho CRM の項目を紐づける 設定を行います。フォームが送信されると、ここで設定したマッピングに従って Zoho CRM にデータが送られます。

同じフォームフィールドを複数のタブに紐づけたい場合は、行を追加して同じフィールド名で別のタブ・項目を設定します。

ユニークキーとの組み合わせ

設定項目

項目名

説明

a-blog cmsのフォームフィールド名

a-blog cms のフォームで使用しているカスタムフィールド名（例：name、email）

固定値チェックボックス

チェックを入れると、フィールド名に入力したテキストをそのまま値として送信。グローバル変数（例：%{BLOG_NAME}）も使用可能

タブ名

送信先の Zoho CRM タブを選択

項目名

タブ内の送信先の項目を選択

追加

このフィールドをレコード追加時に送信するか

更新

このフィールドをレコード更新時に送信するか

3. Zoho リレーショナル設定

Zoho CRM では、タブ間のデータを ルックアップフィールド を使って関連付けることができます。例えば「商談タブ」に「この商談は誰（連絡先タブのレコード）との商談か」という紐付けを持たせることができます。

このセクションでは、フォーム送信時に Zoho CRM 上のタブ間の関連付けを自動で行う ための設定をします。

Zoho CRM のルックアップフィールドについて

ルックアップフィールドとは、あるタブのレコードから別のタブのレコードを参照するための特殊な項目です。例えば商談タブに「関連見込み客」というルックアップフィールドがある場合、そこには見込み客タブのレコードIDが格納され、2つのレコードが紐づきます。

設定項目

項目名

説明

a-blog cmsのカスタムフィールド名

関連付けのキーとなるフォームフィールド名（例：email）

関連元タブ名

ルックアップフィールドを持っている側のタブ（例：商談）

ルックアップID

関連元タブに存在するルックアップフィールドのAPI名（例：Contact_Role）

関連先タブ名

ルックアップフィールドが参照する先のタブ（例：連絡先）

比較フィールド

関連先タブの中から該当レコードを特定するために使う項目（例：Email）

上記の例では「フォームの email フィールドの値と、連絡先の メール項目が一致するレコードを検索し、商談タブのルックアップフィールドに紐づける」という設定です。

ポイント: 関連先タブのレコードがすでに存在している必要があります。フォーム送信時に自動的に依存関係が解決され、正しい順序でAPIが呼び出されます。

フォーム送信の流れ

設定が完了すると、a-blog cms のフォームが送信されたときに以下の順序で処理が実行されます。

  1. フォーム送信データを受け取る

  2. フィールド設定に従って Zoho CRM へ送信するレコードを構築

  3. ユニークキー設定を元に、各タブへの追加・更新を判断

  4. リレーショナル設定を元に、タブ間の関連付けを解決

  5. Zoho CRM API へデータを送信（依存関係のある順に実行）

また、見込み客と連絡先は顧客情報を扱う特別なタブです。見込み客タブと連絡先タブ共に連携設定されている場合、連絡先タブに一致する情報がなければ見込み客タブを検索し、見込み客にも一致する情報がなければ見込み客タブに追加します。これでフォームから送られてきた顧客情報が、すでに取引がある顧客なのか自動で判別がつくようになります。

トラブルシューティング

タブや項目がドロップダウンに表示されない場合
認証情報が正しく設定されているか確認してください。また、ドロップダウン横の「キャッシュクリア」ボタンをクリックすると最新データを再取得できます。

フォーム送信後に Zoho CRM にデータが反映されない場合
config.server.php で HOOK_ENABLE が有効になっているか確認してください。

define('HOOK_ENABLE', 1);