チーム、ワークスペース、請求

API と Webhook

自社のソフトウェアを NextCRM と連携します。必要な権限だけを持つ API キーを作成し、REST API を呼び出し、リード・タスク・フォーム・連絡先・キャンペーン・通話が変わったときに署名付き Webhook を受け取れます。

約10分で読めます 2026年10月24日更新

このページの内容

各値の入手先
API キーを作成する
キーでできること
最初の呼び出し
すべての連携に共通するルール
Webhook
Lora と API
トラブルシューティング

API と Webhook を使うと、自社のシステム（ERP、データウェアハウス、Web サイトのバックエンド、自動化ツール）を NextCRM のワークスペースと連携できます。

REST API はリード、連絡先、タスク、メモの読み取りと変更、ファネル、フォーム送信、キャンペーン、チームメンバーの読み取りができます。
Webhook は、新しいリードやステージの変更などが起きた瞬間にサーバーへ通知します。

注意: 設定 > API と Webhook を開けるのはワークスペース管理者だけです。API アクセスは Business プラン、Agency プラン、Enterprise プランに含まれています。その他のプランでは既存のキーとエンドポイントは表示されますが、新規作成はできず、API 呼び出しは拒否されます。

各値の入手先

すべての値は NextCRM 自体から取得します。サードパーティのアカウントは必要ありません。

値	入手先
API キー	設定 > API と Webhook > API キーを作成。完全なキーは一度だけ表示されます。連携先（例えば n8n、Zapier、Make、または独自のコード）に Bearer トークンとしてコピーします。
署名シークレット	Webhook エンドポイントを追加したときに一度だけ表示され、シークレットを再発行の後にも再度表示されます。Webhook を受信するサーバーに保存します。
エンドポイント URL	ご自身のシステムまたは自動化ツールから取得します。例えば n8n の Webhook ノードの本番 URL です。https を使用する必要があります。

設定の順序: 必要な権限を持つ API キーを作成する > 最初の呼び出しを行う > イベントを指定して Webhook エンドポイントを追加する > サーバーで署名を検証する > テストイベントを送信する。

API キーを作成する

サイドバー下部のプロフィールカードをクリックし、設定を選んで API と Webhook カードを開き（API と Webhook を開く）、API キー タブのままにします。
API キーを作成 をクリックします。
キーの用途がわかる名前を入力します（例：「ERP 連携」）。
権限で、領域ごとに 読み取り と 書き込み を選びます。連携に本当に必要なものだけを選んでください。
必要に応じて 有効期限 を設定します（30 日、90 日、365 日、または日付指定）。
キーを作成 をクリックし、すぐに コピー でキーをコピーします。

警告: キーが表示されるのは一度だけです。NextCRM はキーの指紋（ハッシュ）しか保存しないため、サポートを含め誰も再表示できません。紛失した場合は取り消して新しいキーを作成してください。

一覧には、各キーのプレフィックス（例：ncrm_live_1a2b3c4d）、権限、作成者、最終使用日時、有効期限が表示されます。取り消す を使うとキーはすぐに使えなくなります。

キーでできること

キーはワークスペースの代理として、ワークスペース管理者の権限のうち選んだ権限の範囲で動作します。

権限	できること
リード（読み取り / 書き込み）	リードの一覧と参照、作成、変更、ステージ移動、割り当て、ごみ箱への移動と復元
連絡先（読み取り / 書き込み）	連絡先の一覧、参照、作成、変更、削除
タスク（読み取り / 書き込み）	タスクの一覧と参照、作成、変更、完了、アーカイブ
ファネルとステージ（読み取り）	ファネルとそのステージの参照
フォーム送信（読み取り）	フォームとその送信内容の参照
キャンペーン（読み取り）	キャンペーンとその結果の参照
メモとアクティビティ（読み取り / 書き込み）	リードのメモと履歴の参照、メモの追加と通話の記録
チームメンバー（読み取り）	メンバーの名前、メール、ロールの参照（リードやタスクの割り当て用）
Webhook（読み取り / 書き込み）	Webhook エンドポイントの参照、登録、削除

アプリと同じルールが適用されます。プランの上限（有効リードの上限を超えた新しいリードは リードの受信箱 に入ります）、ごみ箱（ごみ箱のリードは変更前に復元が必要で、API での削除は常にごみ箱への移動です）、そしてデータが他のワークスペースに渡ることはありません。チーム、ロール、請求、API キーの管理や完全削除など、人だけが行える操作はキーではできません。また、キーを作成した人がワークスペース管理者でなくなると、そのキーは使えなくなります。

キーで行った変更は、リードの履歴に API key <名前> として表示されます。

最初の呼び出し

キーを Authorization ヘッダーで送ります。ベース URL は https://…/api/v1 です。

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

リードを作成する例:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

すべてのエンドポイント、フィールド、curl の例を含む完全なリファレンスは API ドキュメント タブにあり、https://…/api/v1/docs で公開されています。OpenAPI 3.1 ファイルは https://…/api/v1/openapi.json です。

すべての連携に共通するルール

レスポンス は { "data": ..., "meta": { ... } }、エラーは { "error": { "code", "message", "details" } } の形式で、検証エラーにはフィールドの一覧が付きます。日時は ISO 8601（UTC）です。
ページ分割: 一覧は meta.next_cursor を返します。次のページは cursor に渡して取得します（limit は最大 100）。
冪等性: POST リクエストには Idempotency-Key ヘッダーを付けてください。同じキーで再試行すると、重複を作らずに最初の結果が返されます（24 時間）。
レート制限: キーごとに毎分 120 件、ワークスペースごとに毎分 600 件です。超えると API は Retry-After ヘッダー付きで 429 を返すので、その秒数だけ待ってください。
メンテナンス: NextCRM の更新中、API は Retry-After 付きで 503 MAINTENANCE を返します。Webhook は保留され、終了後に配信されます。
サーバーからのみ: API はサーバーから呼び出してください。ブラウザからは呼び出せず（CORS なし）、API キーを Web サイトやアプリに入れてはいけません。

Webhook

Webhook タブを開き、エンドポイントを追加 をクリックします。
サーバーの エンドポイント URL を入力します。https:// で始まり、インターネットからアクセスできる必要があります。内部、プライベート、クラウドのメタデータ用アドレスは拒否されます。
必要な イベント を選び、エンドポイントを保存 をクリックします。
署名シークレット（一度だけ表示）をコピーしてサーバーに保存します。
テストイベントを送信 をクリックし、サーバーが応答するか確認します。

利用できるイベント: lead.created、lead.updated、lead.stage_changed、lead.assigned、lead.trashed、lead.restored、task.created、task.completed、form.submitted、contact.created、contact.updated、campaign.sent、call.logged、nps.responded、customer.renewal_updated、customer.at_risk、booking.created、booking.rescheduled、booking.canceled、quote.sent、quote.accepted、quote.declined、automation.webhook。

見積書イベントの金額は、通貨の最小単位（例: セント）の整数です。subtotal_minor は明細値引き後の明細の合計、discount_minor は見積書全体への値引き、tax_minor は税額、total_minor は支払金額です。各明細の total_minor は、明細値引き後、見積書全体の値引きと税の前の金額です。

ファイルインポートで作成されたリードは、インポート完了後にインポートされたリードごとに lead.created を 1 件送信します。data の横に "context": { "source": "import", "import_batch_id": "..." } が含まれます。

各配信は、イベントを JSON（id、type、created_at、actor、data）で送る POST で、ヘッダー X-NextCRM-Event、X-NextCRM-Delivery、X-NextCRM-Timestamp、X-NextCRM-Signature が付きます。

署名を検証する

X-NextCRM-Signature は t=1760860800,v1=5f2b... の形式です。署名シークレットで <t>.<生のリクエストボディ> の HMAC-SHA256 を計算し、v1 と比較します。タイムスタンプが 5 分より古いリクエストは拒否してください。

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

再試行、配信ログ、シークレットの再発行

10 秒以内に任意の 2xx ステータスで応答してください。そうでない場合、NextCRM は間隔を広げながら（1、2、4 … 分）最大 8 回まで再試行します。
配信ログ には各配信のステータス、試行回数、応答コードが表示されます。再送信 で配信をもう一度キューに入れられます。
失敗が多く続くとエンドポイントは 自動的に無効 になり、すべてのワークスペース管理者に通知が届きます。エンドポイントを修正してから 有効にする をクリックしてください。
シークレットを再発行 すると新しい署名シークレットが作成されます。古いシークレットも 24 時間は署名に使われるため、イベントを失わずに切り替えられます。

Lora と API

Lora は API の説明、このページの表示、Webhook エンドポイントの一覧表示ができます。API キーの作成、表示、取り消しは行わず、署名シークレットを見ることもありません。これらはこのページでご自身で行ってください。

トラブルシューティング

応答	意味
`401 INVALID_API_KEY`、`API_KEY_REVOKED`、`API_KEY_EXPIRED`	キーが間違っている、取り消された、または期限切れです。新しいキーを作成してください。
`403 INSUFFICIENT_SCOPE`	キーにこの呼び出しの権限がありません。必要な権限を持つキーを作成してください。
`403 API_KEY_OWNER_NOT_ADMIN`	キーの作成者がワークスペース管理者ではなくなりました。現在の管理者が新しいキーを作成する必要があります。
`402 FEATURE_NOT_IN_PLAN`	プランに API アクセスが含まれていません。
`409 LEAD_IN_TRASH`	先にリードを復元してください（`POST /leads/{id}/restore`）。
`422 VALIDATION_FAILED`	フィールドと理由は `error.details` にあります。
`429 RATE_LIMITED`	`Retry-After` の秒数だけ待ってから続けてください。

すべてのガイド