团队、工作区与账单

API 与 Webhook

将您自己的软件连接到 NextCRM：创建只具有所需权限的 API 密钥，调用 REST API，并在线索、任务、表单、联系人、营销活动或通话发生变化时接收签名的 Webhook。

阅读约需 8 分钟更新于 2026年10月24日

本页内容

各项值的获取位置
创建 API 密钥
密钥可以做什么
第一次调用
所有集成都应遵守的规则
Webhook
Lora 与 API
故障排除

通过 API 与 Webhook，您自己的系统（ERP、数据仓库、网站后端、自动化工具）可以与 NextCRM 工作区协同工作：

REST API 可以读取和修改线索、联系人、任务和备注，并读取漏斗、表单提交、营销活动和团队成员；
Webhook 会在发生变化时立即通知您的服务器，例如出现新线索或线索进入其他阶段。

注意： 只有工作区管理员可以打开设置 > API 与 Webhook。API 访问包含在 Business、Agency 和 Enterprise 套餐中。在其他套餐中，现有密钥和端点仍然可见，但无法新建，API 调用会被拒绝。

各项值的获取位置

所有值都来自 NextCRM 本身，无需任何第三方账户。

值	获取位置
API 密钥	设置 > API 与 Webhook > 创建 API 密钥。完整密钥只显示一次；请将其作为 Bearer 令牌复制到您的集成中（例如 n8n、Zapier、Make 或您自己的代码）。
签名密钥	在您添加 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 密钥放进网站或应用。

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，并在 data 旁附带 "context": { "source": "import", "import_batch_id": "..." }。

每次投递都是一个 POST 请求，正文是事件 JSON（id、type、created_at、actor、data），并带有以下请求头：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` 秒后再继续。

全部指南