Perfex CRM

Perfex CRM REST API — 使用例、Postman コレクション、コードスニペット

🌐 英語 · 简体中文 · Español · Português (BR) · Italiano · Français · Deutsch · Türkçe · Tiếng Việt · ไทย · العربية

Perfex CRM 向け REST API モジュール用の、すぐに使える Postman コレクション、コードスニペット（cURL、PHP、Python、JavaScript）、リソースの カタログです。Perfex CRM を AI エージェントやサードパーティアプリに接続する最も手軽な方法です。

Perfex CRM REST APIを使えば、シンプルな HTTP/JSON インターフェースを通じて、顧客、リード、請求書、見積書、プロジェクト、タスクなどを読み書きできます。CRM 連携、自動化、カスタムアプリに最適です。v3.0では、AI エージェント向けのMCP サーバー、本番環境向けのウェブフック、すぐに使えるZapier / Make / n8nのポーリング、一括操作、よりスマートなリストエンドポイントが追加されました。このリポジトリは、Themesic Interactiveの Perfex CRM 向け REST API モジュールを実用的に補完するもので、コピーして使えるサンプル、インポート可能な Postman コレクション、エンドポイントの完全なカタログを提供します。

• 🧩 モジュールを入手： https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/

• 📖 API ガイド／ライブドキュメント： https://perfexcrm.themesic.com/apiguide/

• 🧾 OpenAPI 3.0 仕様： GET https://yourdomain.com/api/openapi (参照用ファイル)

---

🚀 v3.0 の新機能

機能	エンドポイント	機能の説明
🤖 MCP サーバー	POST /api/mcp	Model Context Protocol（JSON-RPC 2.0）— Claude Desktop、ChatGPT、Cursor、n8n AI Agent、およびあらゆる MCP クライアントに、権限でフィルタリングされた 148 個の CRM ツールを公開します
🪝 Webhooks 2.0	/api/webhooks	124 個のイベント、REST による管理、再試行機能付きの非同期配信、SSRF 対策、HMAC 署名付きリクエスト
🔌 自動化（ポーリング）	/api/zapier/*	Zapier、Make.com、n8n およびポーリングベースのあらゆるツールですぐに使えるポーリングトリガー
⚡ バッチ	POST /api/batch	1 回のリクエストで最大 50 件の操作を実行（MCP と同じツール名）
📚 ナレッジベース	/api/knowledge_base	記事とグループの CRUD
🗒️ ノート	/api/notes	12 種類のエンティティに対応するポリモーフィックなノート
📄 リスト機能の強化	任意のリストエンドポイント	オプトインの ?page=&per_page=、?fields=、?sort=、?created_after=&created_before=
🛡️ 安全な書き込み	任意の POST	Idempotency-Key による再送処理、PUT での不明なフィールドの無視、X-RateLimit-* ヘッダー
📐 OpenAPI 3.0 仕様	GET /api/openapi	API 全体を機械可読な 1 つのドキュメントにまとめています — 74 個のパス、144 個の操作 — 数秒で Postman、Insomnia、または Stoplight にインポートできます（openapi/ にリファレンス版があります）

すべての機能はオプトインで、後方互換性があります。新しいパラメーターを指定しないリクエストでは、これまでとまったく同じレスポンスが返されます。

---

目次

フォルダー	内容
postman/	インポート可能な Postman のコレクションと環境（{{base_url}}、{{authtoken}}）— MCP、Webhooks、Batch、Automation、Knowledge Base、Notes を追加しました
snippets/curl/	よく使われる呼び出しのコピー＆ペースト用 curl コマンド
snippets/php/	PHP（cURL）の例
snippets/python/	Python（requests）の例
snippets/javascript/	JavaScript / Node（fetch）の例
docs/	認証、ページネーションとフィルタリング、webhook、MCP、自動化、カスタムテーブル、エラーとステータスコード

各言語のスニペットには、顧客、請求書、リードの例に加えて、v3 の機能である webhook、MCP、バッチ、自動化、ナレッジベース、ノートの例が含まれています。また、 ページネーション、フィールド選択、並べ替えを示す list_features ファイルもあります。

---

クイックスタート

Perfex CRM REST API へのすべてのリクエストは、Authtoken ヘッダーで認証されます。Perfex の管理画面で トークンを作成します。REST API module を有効にした後、API → API Management を開き、 https://yourdomain.com/api/... で API を呼び出します。

curl -H "authtoken: YOUR_API_TOKEN" https://yourdomain.com/api/customers

顧客のリストが JSON で返されます。ヘッダーとクエリパラメーターによる認証については docs/authentication.md を、PHP、Python、JavaScript での同じ呼び出しについては snippets/ を参照してください。

Postman コレクションを使う

1. Postman を開き、Import を選択して、postman/perfex-rest-api.postman_collection.json を読み込みます。
2. 環境 postman/perfex-rest-api.postman_environment.json をインポートします。
3. base_url に https://yourdomain.com/api を、authtoken にトークンを設定します。
4. 任意のリクエストを選び、Send をクリックします。

AI エージェントを接続する（MCP）

任意の MCP クライアント（Claude Desktop、Cursor、ChatGPT、n8n AI Agent）の接続先を POST https://yourdomain.com/api/mcp に設定し、authtoken ヘッダーを送信します。サーバーは、CRM の権限に応じてフィルタリングされたツールを提示します。docs/mcp.md と snippets/curl/mcp.sh を参照してください。

Claude、ChatGPT、その他の AI アシスタントでの使用

1 つの URL https://perfex-mcp.themesic.com/mcp で、任意のアシスタントを接続できます。Claude、ChatGPT、 Cursor、VS Code のセットアップ手順については、docs/connect-ai-assistants.md をご覧ください。

claude.ai、Cowork、Claude Code 用の Claude プラグイン（コネクター＋スキル）は、 claude-plugin/ にあります。使用するには、有効なライセンスを持つ REST API モジュールと MCP サーバーが有効になっていることが必要です。セットアップ、権限、プライバシーポリシーについては、 claude-plugin/README.md をご覧ください。

---

エンドポイント一覧

すべての CRUD エンドポイントは RESTful の規約に従います。ベースパス https://yourdomain.com/api の下で、GET は一覧取得、GET /:id は単一取得、POST は作成、PUT /:id は更新、DELETE /:id は削除です。

CRM の主要リソース

リソース	ベースパス	主な操作
顧客	/api/customers	一覧取得、取得、作成、更新、削除
連絡先	/api/contacts	一覧取得、取得、作成、更新、削除
リード	/api/leads	一覧取得、取得、作成、更新、削除
請求書	/api/invoices	一覧取得、取得、作成、更新、削除
見積もり	/api/estimates	一覧取得、取得、作成、更新、削除
クレジットノート	/api/credit_notes	一覧取得、取得、作成、更新
支払い	/api/payments	一覧取得、取得、作成
提案	/api/proposals	一覧取得、取得、作成、更新、削除
契約	/api/contracts	一覧取得、取得、作成、更新、削除
プロジェクト	/api/projects	一覧取得、取得、作成、更新、削除
タスク	/api/tasks	一覧取得、取得、作成、更新、削除
マイルストーン	/api/milestones	一覧取得、取得、作成、更新、削除
タイムシート	/api/timesheets	一覧取得、取得、作成、更新、削除
サブスクリプション	/api/subscriptions	一覧取得、取得、作成、更新
項目	/api/items	一覧取得、取得、作成、更新、削除
経費	/api/expenses	一覧取得、取得、作成、更新、削除
スタッフ	/api/staffs	一覧取得、取得、作成、更新、削除
カレンダー	/api/calendar	一覧取得、取得、作成、更新、削除
カスタムフィールド	/api/custom_fields	関連するタイプごとの一覧取得
共通（参照データ）	/api/common	国、税金、通貨、ステータス…

v3 プラットフォームと追加リソース

リソース	ベースパス	主な操作
MCP サーバー	/api/mcp	POST JSON-RPC 2.0：initialize、tools/list、tools/call
バッチ	/api/batch	1 回のリクエストで最大 50 件の操作を実行
Webhook	/api/webhooks	一覧取得、取得、作成、更新、削除、POST /:id/toggle、GET /events、GET /:id/logs
自動化（ポーリング）	/api/zapier	GET /resources、GET /poll/:resource、GET /test/:resource
ナレッジベース	/api/knowledge_base	一覧取得、取得、作成、更新、削除、/groups
ノート	/api/notes	:rel_type/:rel_id ごとの一覧取得、取得、作成、更新、削除

リソースごとの正確なリクエストフィールドについては、公式の API ガイド に記載されています。ここで紹介するスニペットでは、よくあるフローを扱います。

---

より便利な一覧エンドポイント（v3）

すべての一覧エンドポイントでは、任意のクエリパラメーターを指定できます。パラメーターを追加すると { data, meta } エンベロープが返され、 省略すると従来どおりの配列がそのまま返されます。

# Page 2, 20 per page, only id + company, newest first, created this year
curl -H "authtoken: YOUR_API_TOKEN" \
  "https://yourdomain.com/api/customers?page=2&per_page=20&fields=id,company&sort=-datecreated&created_after=2026-01-01"

パラメーター	例	効果
page、per_page	?page=2&per_page=20	ページネーション → { data, meta }
fields	?fields=id,company	指定した列のみを返す
sort	?sort=-datecreated,company	並べ替え（- は降順）
created_after、created_before	?created_after=2026-01-01	日付範囲で絞り込み

per_page は 1 ページの件数を指定するパラメーターです（1～100、デフォルトは 25）。limit は、 page も指定された場合にのみエイリアスとして受け付けられるため、?limit=5 だけではページネーションされません。?page=1&per_page=5 を使用してください。

docs/pagination-filtering.md と snippets/curl/list_features.sh をご覧ください。

---

2.x からのアップグレード

破壊的変更はありません。 v3 のリスト機能はすべてオプトイン方式です。

• 上記のパラメーターを何も送信しなければ、2.x と同じ通常の配列が返されます。 { data, meta } エンベロープが返されるのは、page または per_page を送信した場合のみです。
• エンドポイントの名前は変更されていません。 顧客のエンドポイントは以前から /api/customers です。
• PUT の不明なフィールドは、エラーを返す代わりに無視されます。
• POST リクエストでは、任意の Idempotency-Key ヘッダーを使用できます。同一のリトライでは重複を作成せず、保存済みのレスポンスが再送されます。

v3 を導入する際に知っておくべきことが 2 つあります。

• カスタムテーブルは 3.0.2 で許可リストによる管理に移行しました。詳しくは docs/custom-tables.md をご覧ください。
• 新しい権限行（Webhooks、Notes、Knowledge Base）を使うには、既存のトークンで有効にする必要があります。有効にするまでは、該当するエンドポイントは応答せず、MCP ツールも tools/list に表示されません。

---

よく利用される連携とユースケース

Perfex CRM REST API は、Perfex CRM を AI エージェントやサードパーティアプリケーションと連携するためによく利用されています。

• AI アシスタント（MCP） — /api/mcp を介して、Claude、ChatGPT、Cursor から CRM の読み取りと更新を行えます。
• Zapier / Make / n8n — すぐに使えるポーリングトリガー（/api/zapier/*）を使ったノーコード自動化が可能です。
• Webhooks — HMAC 署名付きで、Perfex のイベント（新しい請求書、新しいリード、124 種類のイベント）を Slack、Discord、または独自のバックエンドにプッシュできます。
• Google Sheets / Power Automate — 顧客、請求書、支払いをスプレッドシートやダッシュボードと同期できます。
• カスタムアプリとポータル — Perfex のデータを利用したモバイルアプリや顧客ポータルを構築できます。
• 会計と E コマース — 請求書や品目を外部の請求システムやショッププラットフォームと同期できます。

これらはすべて、REST API for Perfex CRM モジュールによって実現されています。

---

認証（概要）

方法	手順
ヘッダー（推奨）	Authtoken: YOUR_API_TOKEN
クエリパラメーター	?authtoken=YOUR_API_TOKEN（簡単なテストや Webhook に便利です）

トークンは API → API Management で作成し、リソースごとに権限を設定します。詳しくは docs/authentication.md をご覧ください。

---

よくある質問

Perfex CRM に REST API はありますか？ はい。REST API for Perfex CRM モジュールを使うと、顧客、リード、請求書、見積書、プロジェクト、タスクなどに対応する完全な RESTful HTTP/JSON API に加え、v3 の MCP サーバー、webhooks、batch、automation エンドポイントを利用できます。

Perfex CRM を AI エージェント / ChatGPT / Claude と連携できますか？ はい。v3 には POST /api/mcp で利用できる MCP サーバーが含まれており、権限に基づいてフィルタリングされた CRM ツールを、任意の Model Context Protocol クライアントに公開します。詳しくは docs/mcp.md をご覧ください。

Perfex CRM API の認証方法を教えてください。 Authtoken HTTP ヘッダー（または ?authtoken= クエリパラメーター）にトークンを指定します。詳しくは docs/authentication.md をご覧ください。

Perfex CRM API のベース URL は何ですか？ https://yourdomain.com/api です。たとえば、https://yourdomain.com/api/customers です。

Perfex CRM を Zapier、Make、n8n と連携できますか？ はい。v3 には /api/zapier/* にすぐに使えるポーリングトリガーがあり、Webhook も利用できます。詳しくは よく利用される連携 と docs/automation.md をご覧ください。

Perfex CRM 用の Postman コレクションはありますか？ はい。postman/perfex-rest-api.postman_collection.json と同梱の環境をインポートし、base_url と authtoken を設定すれば、すぐにリクエストを送信できます。

Perfex CRM API 経由で請求書を作成する方法を教えてください。 請求書フィールドと items[] 配列を指定して POST https://yourdomain.com/api/invoices を送信します。v3 では subtotal / total が自動計算されます。詳しくは snippets/curl/invoices.sh をご覧ください。

---

概要／サポート

このリポジトリは、次の商用モジュールのサンプル集です。

Perfex CRM 用 REST API — Perfex CRM をサードパーティアプリケーションに接続 Themesic Interactive 提供

• 🛒 購入／詳細： https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/
• 📖 ドキュメント： https://perfexcrm.themesic.com/apiguide/
• 💬 サポート： https://themesic.com/support

サンプルの追加に関する貢献を歓迎します。詳細は CONTRIBUTING.md をご覧ください。

ライセンス

このリポジトリのサンプルコードは、MIT License のもとで公開されています。「Perfex」はそれぞれの所有者の商標であり、REST API モジュールは Themesic Interactive の商用製品です。