以下は オープンソース版 VtigerCRM v8系（例：8.4） を外部システム連携するために、開発エンジニアがそのまま着手できるレベルを狙った API仕様書＋開発手引き（実装ガイド） です。
※Vtiger OSS の標準APIは、基本的に webservice.php を叩く “REST(Webservices)” です。公式Developer Guide（Community）に操作仕様がまとまっています。 (community.vtiger.com)

1. 全体像（何ができるか／どう繋ぐか）

1.1 APIの位置づけ

  • Vtiger OSS v8系は Webservices（REST APIs） を提供し、HTTP(S)経由でレコードの 作成・取得・更新・削除・検索・差分同期 ができます。 (community.vtiger.com)
  • 典型的な連携パターン
  • 双方向同期：相手側のID（外部ID）をVtigerのカスタム項目に保持し相互参照
  • 片方向取り込み：Vtigerに集約（営業・サポート・請求など）
  • 差分同期（sync）＋補完取得（retrieve/query）：更新時刻を基準に追跡

1.2 ベースURL・エンドポイント

  • 基本エンドポイント：
    https://<your-vtiger-host>/webservice.php (community.vtiger.com)
  • リクエスト形式：
  • HTTP：GET / POST
  • Content-Type：application/x-www-form-urlencoded (community.vtiger.com)
  • レスポンス形式（共通）：
  • 成功：{ success: true, result: {...} }
  • 失敗：{ success: false, error: { message: String, code: String } } (community.vtiger.com)

2. 認証方式（ログイン手順／セッション）

Vtiger Webservices のログインは 2段階です。 (community.vtiger.com)

2.1 事前準備：Access Key の取得

  • Vtiger画面の My Preferences でユーザーごとの Access Key を確認します。 (community.vtiger.com)
  • これはパスワードではなく、APIログインに使うキーです（漏洩しないように保護）。

2.2 Step1：Challenge取得（GET）

Request

GET /webservice.php?operation=getchallenge&username=<USERNAME>

Response（例）

{
  "success": true,
  "result": {
    "token": "TOKENSTRING",
    "serverTime": 1700000000,
    "expireTime": 1700018000
  }
}

仕様：token / serverTime / expireTime (community.vtiger.com)

2.3 Step2：Login（POST）

Request

POST /webservice.php
Content-Type: application/x-www-form-urlencoded

operation=login
username=<USERNAME>
accessKey=<MD5(token + access_key)>

Response（例）

{
  "success": true,
  "result": {
    "sessionName": "xxxxxxxxxxxx",
    "userId": "19x1",
    "version": "0.22",
    "vtigerVersion": "8.4.0"
  }
}

sessionName を以降のAPI呼び出しに使用 (community.vtiger.com)

2.4 ログアウト（POST）

POST /webservice.php

operation=logout
sessionName=<sessionName>

(community.vtiger.com)

3. データモデルの把握（listtypes / describe）

3.1 利用可能モジュール一覧（GET）

GET /webservice.php?operation=listtypes&sessionName=<sessionName>

(community.vtiger.com)

3.2 モジュールのフィールド仕様取得（GET）

GET /webservice.php?operation=describe&sessionName=<sessionName>&elementType=<TYPE>

(community.vtiger.com)

describe の活用ポイント

  • 必須項目（mandatory）・型（datatype）・選択肢（picklist）・参照関係（reference）などを取得し、連携側のマッピング定義に反映
  • UIでフィールド追加した場合も describe で追随できるため、マッピング定義の生成に便利

4. CRUD（作成・取得・更新・削除）

ここからが連携実装の主戦場です。
“element” は基本的に JSONをURLエンコードして渡す 形です。 (community.vtiger.com)

4.1 Create（POST）

POST /webservice.php

operation=create
sessionName=<sessionName>
element=<URLENCODED(JSON)>
elementType=<TYPE>

(community.vtiger.com)

element（例：Contacts 作成）

{
  "firstname": "Taro",
  "lastname": "Yamada",
  "email": "taro@example.com",
  "assigned_user_id": "19x1"
}

4.2 Retrieve（GET）

GET /webservice.php?operation=retrieve&sessionName=<sessionName>&id=<WEBSERVICE_ID>

(community.vtiger.com)

4.3 Update（POST）

POST /webservice.php

operation=update
sessionName=<sessionName>
element=<URLENCODED(JSON)>

(community.vtiger.com)

重要（事故りやすい点）

  • Updateは「部分更新」に見えて、実装/運用によっては 未指定フィールドが空扱いになる 事故が起きがちです。安全策として retrieve → 差分反映 → update を推奨、という説明が広く共有されています（フォーク/実装差もあるため保守的に）。 (blog.crm-now.de)

4.4 Delete（POST）

POST /webservice.php

operation=delete
sessionName=<sessionName>
id=<WEBSERVICE_ID>

(community.vtiger.com)

5. 検索・抽出（query）

5.1 Query（GET）

GET /webservice.php?operation=query&sessionName=<sessionName>&query=<QUERY>

(community.vtiger.com)

クエリ構文： (community.vtiger.com)

SELECT * | <column_list> | <count(*)>
FROM <object>
[WHERE <conditionals>]
[ORDER BY <column_list>]
[LIMIT [<m>, ] <n>]

制約（必読）

  • 単一モジュールのみ（JOIN不可）
  • Query結果は 最大100件に制限（limitでページング） (community.vtiger.com)

例：Contacts から email, firstname を20件

SELECT firstname,lastname,email FROM Contacts ORDER BY modifiedtime DESC LIMIT 0,20;

6. 差分同期（sync）— 外部連携の要

6.1 Sync（GET）

GET /webservice.php?operation=sync
  &sessionName=<sessionName>
  &modifiedTime=<TIMESTAMP>
  [&elementType=<TYPE>]

(community.vtiger.com)

設計指針（おすすめ）

  • 外部連携側で lastSyncedTime を保持
  • sync(modifiedTime=lastSyncedTime) で変更一覧を取得
  • 変更されたIDを retrieve で詳細取得（必要なら）
  • 成功したら lastSyncedTime を更新（サーバ時刻基準が安全）

7. Webservice ID の扱い（ID形式と変換）

VtigerのWebservicesではレコードIDがしばしば "<moduleId>x<recordId>" 形式になります。
例：18x61900 のように、モジュールの内部IDとレコードIDを結合する、という説明が一般に共有されています。 (Stack Overflow)

連携での実務ポイント

  • 外部システムのIDは、Vtiger側のカスタム項目（例：external_id）に保存して相互参照に使う
  • 逆にVtigerのWebservice IDも外部側に保存し、更新時のキーにする

8. エラー設計（code / message）と典型トラブル

8.1 レスポンス上の基本形式

失敗時：success:false かつ error.code / error.message が返る (community.vtiger.com)

8.2 よくある落とし穴

  • getchallenge は GET：誤ってPOSTすると認証エラーになる事例がよくあります。 (Stack Overflow)
  • 権限不足：ユーザーのプロファイル/ロールで対象モジュールやフィールドが見えないと ACCESS_DENIED 系になりがち
  • query構文エラー：括弧や演算子の制約で QUERY_SYNTAX_ERROR が出ることがあります（JOIN不可・括弧のグルーピング不可などの影響） (community.vtiger.com)

9. 実装手引き（推奨アーキテクチャ／開発ステップ）

9.1 開発開始チェックリスト

  1. 接続先URL確認：/webservice.php が到達できる
  2. API用ユーザー作成（管理者を使い回さない）
  3. My Preferences から Access Key を取得 (community.vtiger.com)
  4. listtypes / describe で連携対象モジュール・必須項目・型を確定 (community.vtiger.com)
  5. 最小CRUD疎通（例：Contacts 1件を create→retrieve→update→delete）
  6. 本番データ同期は sync を軸に設計 (community.vtiger.com)

9.2 マッピング設計のコツ

  • describeの結果を“正”にして、外部→Vtiger変換を自動生成できる構造にする
  • picklist は外部の値をVtiger側選択肢へマップ（不正値はエラー/保留）
  • reference 型（担当者・組織など）は、先に参照先を解決してIDをセット

9.3 更新戦略（安全運用）

  • 原則：retrieve → 差分反映 → update（空更新事故を避ける） (blog.crm-now.de)
  • 衝突解決：
  • 「外部が正」/「Vtigerが正」/「modifiedtimeで新しい方」などルールを決める
  • 双方向なら外部ID項目＋modifiedtimeで整合を取りやすい

9.4 運用・セキュリティ

  • 必ずHTTPS（証明書・TLS）
  • Access Key はVault等で安全に保管、ログに出さない
  • API用ユーザーは 必要最小権限（参照だけ、作成だけ等）
  • 監査：誰がAPIで作った/更新したかを追えるように、assigned_user_idや更新ログを運用で確認

10. 参考：クイックサンプル（擬似コード）

10.1 ログインして sessionName を得る

1) GET  /webservice.php?operation=getchallenge&username=admin
2) token を取得
3) md5(token + access_key) を計算
4) POST /webservice.php (operation=login, username, accessKey)
5) result.sessionName を保持

（手順・パラメータ仕様は公式の通り） (community.vtiger.com)

10.2 Contacts を作成

POST /webservice.php
 operation=create
 sessionName=...
 elementType=Contacts
 element=<urlencoded json>

(community.vtiger.com)

11. 補足：クライアントライブラリ

  • Vtiger側公式ガイドでは、Webservices用クライアントとして vtwsclib の存在に言及があります（言語別で叩ける、という位置づけ）。 (community.vtiger.com)

既存ユーザのログイン