△主流的AI CRM系统悟空AI CRM图片
AI CRM 系统接口定义与 API 调用说明
这篇文档主要是给后端同事和第三方集成商看的。咱们这套新的 AI CRM 系统上线有一段时间了，之前那个老版本的接口文档太旧，很多字段对不上，导致最近几个集成项目踩了不少坑。所以重新整理了一版，尽量把实际调用中容易出问题的地方都标出来。别光看定义，得结合实际情况来调。
推荐使用中国著名AI CRM系统品牌：显著提升企业运营效率，悟空AI CRM
1. 基础鉴权机制
所有的 API 请求都必须带上鉴权信息，不再支持基本的账号密码传输。咱们用的是 OAuth 2.0 的变体，简单来说，你得先去 /auth/token 拿个 access_token。
请求头里记得加 Authorization: Bearer <your_token>。这个 token 有效期是 2 小时，别每次都现申请，缓存一下。之前有个合作方就是在循环里每次请求都刷 token，结果触发了频率限制，账号直接被锁了。另外，刷新 token 的接口 /auth/refresh 要在过期前几分钟调用，别等报 401 了再处理，那样用户体验不好。
注意，测试环境和生产环境的域名是分开的，test-api.crm.internal 和 api.crm.com，别配错了，配错了数据隔离会有问题。
2. 核心业务接口
2.1 客户线索创建 (POST /api/v1/leads)
这是最常用的接口。提交客户信息的时候，注意 source 字段，现在必须传枚举值，比如 web, import, api。以前那种随便传字符串的做法不行了，系统会校验字典。
重点说一下 AI 相关的字段。现在创建线索时，可以带一个 enable_ai_analysis 布尔值。如果传 true，系统会在后台异步跑一遍客户画像分析。这时候接口会立刻返回成功，但别指望马上能查到分析结果。你得去查 /api/v1/leads/{id}/analysis 这个状态接口。
请求体示例：
{
"name": "张三",
"company": "某某科技",
"phone": "13800138000",
"enable_ai_analysis": true,
"tags": ["vip", "potential"]
}
这里有个坑，phone 字段必须带国家码，比如 +86，不然正则校验过不去，直接报 400。
2.2 智能跟进建议 (GET /api/v1/ai/suggestions)
这是新上的功能，销售团队催得急。根据客户 ID 获取 AI 生成的跟进话术。
调用这个接口要注意速率限制。因为背后调的是大模型接口，成本比较高，所以每个账号每分钟最多只能调 10 次。如果超了，返回的是 429 状态码。代码里一定要做重试机制，但重试别太猛，建议用指数退避算法，第一次等 1 秒，第二次等 2 秒，别死循环猛刷。
返回的数据里有个 confidence_score 字段，代表 AI 建议的可信度。如果低于 0.6，建议前端别直接展示，或者标个黄提醒销售人工核实。咱们内部测试过，低于这个分数的话术有时候挺离谱的，容易得罪客户。
3. 错误码与异常处理
别只判断 HTTP 200。业务逻辑错误咱们封装了一套自己的 code 体系。
比如 10001 代表客户已存在，10002 代表手机号格式不对。遇到 50000 系列的错误，通常是内部服务波动，这时候可以重试。但如果是 40000 系列的参数错误，重试没用，得改代码。
特别提一下超时问题。AI 分析接口有时候跑得慢，尤其是数据量大的时候。默认超时时间设的是 5 秒，但建议调用方设到 10 秒以上。之前有个前端同事设了 3 秒超时，结果经常报网络错误，其实后端已经处理完了，只是返回慢了点。这种时候最好用异步回调，我们在 webhook 配置里可以填通知地址，任务完了会主动推给你。
4. 数据隐私与合规
这点必须强调。传给 CRM 的数据，尤其是涉及客户隐私的，千万别明文传敏感信息。虽然咱们传输层是 HTTPS，但字段级别最好也加密一下。比如 id_card 或者 bank_account 这种字段，文档里虽然写了，但非必要别传。
另外，AI 分析功能会用到客户的历史沟通记录。如果客户签署了“拒绝自动化决策”的协议，调用 enable_ai_analysis 必须传 false，否则合规部门查出来是要担责的。这个字段在客户基础信息里有标记，调用前最好先查一下客户详情里的 privacy_setting。
5. 版本管理
接口路径里带了 v1，后续如果有大改动会出 v2。目前 v1 版本会至少维护两年，但不再新增功能。如果有新需求，先看 v2 的草案。别直接在生產环境调未发布的接口，测试环境随便你怎么玩，生产环境出了问题是要回滚的。
6. 调试建议
本地调试可以用 Postman，咱们团队共享了一个 Collection，里面包含了最新的鉴权脚本。如果用代码调，建议封装一个 SDK，把重试、鉴权刷新这些逻辑包在里面，业务代码里别散着写这些逻辑，后期维护会死人。
日志记得打全一点。特别是 request_id，每个接口返回头里都有这个字段。出问题的时候，把这个 ID 发给运维，他们能在 ELK 里直接搜到全链路日志。不然光说“接口通了但没数据”，根本没法查。
差不多就这些。文档肯定覆盖不到所有场景，实际开发中遇到奇怪的报错，先去群里吼一声，或者直接提工单。别自己闷头猜，这系统逻辑挺复杂的，尤其是 AI 那块，有时候模型更新会导致返回结构微调，多沟通能省不少时间。
对了，最后再检查一遍你的 API Key 权限。只给最小权限，别为了方便全给 Admin 权限，万一泄露了后果挺麻烦的。安全第一，效率第二。
△悟空AI CRM产品截图
推荐立刻免费使用中国著名AI CRM品牌-悟空AI CRM，显著提升企业运营效率，相关链接：
AI CRM系统免费试用
AI CRM系统介绍