後付けの連携タブではなく、エンジンそのもの。
多くのCRMは、「本体」の製品の傍らに、機能の限られた遅れがちなAPIを提供しています。GENECRMのウェブアプリ、モバイルアプリ、APIは、1つのバックエンドに対する3つのクライアントです。そのため、APIが画面上の機能に遅れることは決してありません。
アプリ内のどの機能もAPIから隔離されていません。同じレコード、同じ検証、同じオートメーションが、UIとすべての /v1 呼び出しを支えています。
ウェブ、iOS / Androidネイティブアプリ、御社の連携機能は、いずれも同じバックエンドと通信します。一度作れば、どこでも同じ挙動になります。
すべてのレスポンスは、テナント分離された実データに基づいています。AIがレコードを裏で書き換えることはありません。オートメーションもGENEコパイロットも、許可された範囲でのみ動作します。
OAuth 2.0のクライアントクレデンシャルとユーザー交換グラントは、GENECRMを自社UIの背後にヘッドレスで組み込むパートナーアプリのために設計されています。
必要なスコープで、自分で発行するキー
設定 → 開発者 からキーを発行できます。サポートへの依頼も待ち時間も不要です。レポート連携なら読み取り専用、レコードの作成・更新を行うなら読み書き可能といったスコープを設定でき、漏洩した場合は即座に無効化できます。
- セルフサービス — アプリ内の設定からキーの作成、ローテーション、無効化が可能
- 読み取り、または読み書きのスコープを設定。各キーはテナントとサービスIDに紐付きます
- すべてのリクエストで X-API-Key ヘッダーとして送信。セッションもCookieも不要
- キーごとの利用状況は GET /v1/usage で個別に確認できます
自らの名義で動作するアプリのためのクライアントクレデンシャル
OAuthクライアントを登録し、その client_id / secret を短命でローテーションされるアクセストークンと交換すれば、任意の /v1 エンドポイントで通常のBearerトークンとして使用できます。パートナーのコードベースに静的なAPIキーを置き続けることへの、エンタープライズ向けの代替手段です。
- POST /oauth/token — grant_type=client_credentials + client_id + client_secret
- 短命でスコープ付きのJWTを返します: { access_token, token_type: "Bearer", expires_in }
- 任意の /v1 リソースで Authorization: Bearer <token> として使用できます
- 組み込み / パートナーアプリでは、さらに実在ユーザーのIDと交換できます(下記参照)
/v1 配下のすべてのリソースが、同じ形式と同じ境界を持ちます。
以下のすべてのリソースは、同じリクエストとレスポンスの形式、同じページネーション(?limit=&offset=)、そして同じ行レベルセキュリティの境界を共有します。一覧取得も作成も、自テナントの行のみを対象とします。書き込みの対応範囲はリソースによって異なり、正確な一覧はOpenAPI仕様をご確認ください。
署名付きイベント、送信ログ、そして取りこぼしゼロ
必要なイベント(crm.contact.create、crm.lead.create、crm.opportunity.update など)にURLを購読登録してください。すべての送信にHMAC署名が付くためペイロードを信頼でき、すべての試行が記録され、失敗はデッドレターキューに入って再送信できます。
- POST /v1/webhooks — { url, events: [...] } が署名シークレットを返します(表示は一度きり)
- すべての送信に、生のボディに対する X-GeneCRM-Signature: sha256=<hmac> が付きます
- 送信履歴の全件は GET /v1/webhooks/deliveries で確認できます
- 失敗した送信は最大5回まで再試行され、その後 GET /v1/webhooks/events/failed に残り再送信できます
プランごとに計測し、リアルタイムで可視化。
毎分あたりのレート制限はプランごとに設定され、エッジで適用されます。月間の呼び出しクォータはこれとは別に、テナントごとに計測されます。いずれも照会できるため、利用状況が不意打ちになることはありません。
Premiumは約120リクエスト/分、Proは約600リクエスト/分。超過した場合は、黙って破棄されるのではなく、Retry-Afterヘッダー付きで429が返ります。
月間の呼び出しクォータは、これとは別にテナントごとに計測されます。使い切ると、期間がリセットされるかアップグレードされるまで、以降の呼び出しはHTTP 402 Payment Requiredを返します。
現在の期間の使用量をプランの上限と対比し、APIキーごとの内訳とともに確認できます。独自のダッシュボードを作るのも、リリース前に確認するだけでも構いません。
プランの上限と、どの制限機能が有効かを確認できます。Proプラン以降で利用できる api_access 自体も含まれます。
任意の言語でクライアントを生成できる仕様
APIの全体像は、APIを提供しているのと同じスキーマから生成されたOpenAPI / Swagger仕様に記述されています。そのため、実装との乖離が起きません。入門ガイドとセルフサービスのキー管理と合わせれば、数分で最初の呼び出しを行えます。
- /openapi.json で機械可読なOpenAPI仕様を提供 — 任意の言語のクライアントを生成できます
- PythonとTypeScriptのリファレンスクライアント、およびWebhook検証用のヘルパーを提供
- 入門ガイドが、最初のキー、最初の呼び出し、最初のWebhookまでをご案内します
- キーとOAuthクライアントはご自身で管理できます: 設定 → 開発者。サポートへの依頼は不要です
自社製品の中でGENECRMを動かす。
パートナーやプラットフォームとの連携で、単一のサービスアカウントを共有する必要はありません。OAuthアプリのトークンを実在するユーザーのIDと交換すれば、すべての操作がその人物に紐付けて記録されます。テナント分離の保証もそのまま維持されます。
組み込み時の3ステップの受け渡し
- 1. アプリレベルのトークン。 御社のバックエンドが、OAuthの client_id / secret をアプリスコープのBearerトークンと交換します。エンドポイントは
POST /oauth/tokenを使用します。 - 2. ユーザーの交換。 御社のバックエンドが
POST /v1/auth/exchangeを、アプリトークンとサインイン中のユーザーの外部IDおよびメールアドレスとともに呼び出します。GENECRMが該当ユーザーを検索または作成し、そのユーザー自身のアクセストークンを返します。 - 3. ユーザーごとのプロキシ。 御社のUIが
/v1/**を、そのユーザーのトークンとともに自社プロキシ経由で呼び出します。すべての書き込みが実在の人物に紐付けられ、行レベルセキュリティによってその事業所の範囲に限定されます。
バージョン管理された1つのAPI、2通りの認証方法(APIキーまたはOAuth 2.0)、単一のパス配下に揃ったすべてのリソース、信頼できる署名付きWebhook、そして上限に達する前に確認できる利用状況。
開発者から実際に寄せられる質問。
APIキーは、自社のスクリプトや社内ツール向けの手軽な方法です。設定 → 開発者 から発行し、X-API-Key として送信してください。OAuth 2.0のクライアントクレデンシャルは、パートナーアプリや連携機能が自らの名義で動作する場合に適しています。すべてのリクエストに静的なシークレットを埋め込む代わりに、短命でローテーションされるBearerトークンを使用します。
毎分あたりのレート制限はプランごとに設定されており(Premiumは約120リクエスト/分、Proは約600リクエスト/分)、超過すると Retry-After ヘッダー付きで429を返します。月間のAPI呼び出しクォータはこれとは別に計測され、使い切ると、期間がリセットされるかアップグレードされるまで402 Payment Requiredを返します。
すべての送信には署名が付きます。X-GeneCRM-Signature ヘッダーに sha256=<hmac> の形式で、エンドポイントのシークレット(作成時に一度だけ表示されます)を鍵としたリクエストボディのHMAC-SHA256が入ります。ペイロードを信頼する前に、同じ値を再計算し、一定時間比較で照合してください。署名がない、または一致しない送信は決して信頼しないでください。
送信はバックオフを挟みながら最大5回まで自動的に再試行されます。それでも失敗した場合、イベントはデッドレターキュー(GET /v1/webhooks/events/failed)に入り、エンドポイントの復旧後に任意のタイミングで再送信できます。イベントが失われることはありません。
作成されたワークスペースはいずれも独立したテナントなので、2つ目のワークスペースがそのまま開発環境になります。専用のキーを使って開発とテストを行い、準備ができたら連携先を本番ワークスペースに切り替えてください。テスト用と本番用でキーを使い分ける必要はありません。
すべてのリソースは /v1 配下にあります。同一バージョン内では、後方互換性を保つ形で項目やエンドポイントを追加します。互換性を壊す変更は、/v1 を黙って変更するのではなく、新しいバージョンとして提供します。
モバイルは独自のパスワードグラントを使用します。POST /v1/auth/token にメールアドレスとパスワードを送信すると、短命のアクセストークンとローテーションされるリフレッシュトークンが返され、ユーザーに再サインインを求めることなく更新されます。APIキーやOAuthアプリとは別のフローで、サインイン中のユーザーの範囲に限定されます。
GET /v1/usage は、現在の期間の使用量をプランの上限と対比し、APIキーごとの内訳とともに返します。GET /v1/entitlements は、プランの上限と、api_access 自体を含むどの制限機能が有効かを返します。