使用开放平台接入和管理外部系统
功能介绍
开放平台用于将企小码中的客户、客户群、风险、超时、统计及已有 AI 分析结果接入企业自己的系统。例如，将客户信息同步到 CRM、将风险和超时统计展示在 BI 看板中，或由工单系统接收风险、超时事件后继续处理。
接入后能获取的内容，取决于接口开放范围、应用获得的数据权限，以及企小码中实际已有的数据。开启某类数据权限，不等于可以获取后台页面中的全部内容，也不会自动产生原本没有的数据。
入口：web 端管理后台 → 系统设置 → 开放平台。
一、先确认能获取什么
以下为开放数据类别及典型内容，具体字段、查询条件和返回范围以正式接口文档为准。
| 数据类别 | 可获取的典型内容 | 可以用来做什么 |
|---|---|---|
| 客户数据 | 客户标识、名称、企业、类型、来源、归属员工、添加时间、备注、客户标签、跟进状态等 | 同步客户资料，关联 CRM 中的客户记录 |
| 客户群数据 | 群标识、群名称、群主、创建时间、人数、成员标识、成员类型及归属关系等 | 维护客户群档案，分析群成员及归属关系 |
| 员工数据 | 员工、客户、客户群、部门、标签、规则及事件的标识 | 将企小码中的业务对象与企业系统中的记录建立关联 |
| 风险数据 | 风险事件、类型、命中规则、触发时间、等级、相关对象、审计状态及已有审计结果 | 建立风险台账，筛选待处理事件，关联外部工单 |
| 超时数据 | 超时类型、规则、触发时间、时长、回复状态、审计结果，以及支持场景中的申诉数据 | 跟踪响应情况，整理待处理超时和申诉记录 |
| 统计数据 | 客户、客户群、风险、超时的数量、趋势、分布和排行等 | 制作 BI 看板、经营报表和服务质量报表 |
| AI 分析结果 | 已有 AI 分析状态、建议等级、分析原因、自动审计结果，以及已有会话总结结果等 | 解读风险和超时原因，筛选重点事件，辅助生成复盘报告 |
二、哪些内容获取不到
| 不开放的内容 | 对接时应如何理解 |
|---|---|
| 聊天原文、完整聊天上下文 | 不能通过本开放平台同步完整聊天记录，也不能据此让外部 AI 重新阅读原始对话 |
| 原始消息中的文件、图片、语音、视频 | 不提供原始消息附件或文件流 |
| 客户手机号、微信号、客户头像、客户群头像 | 不能依靠开放平台补齐这些资料；客户标识不等于手机号或微信号 |
AI 相关接口仅提供已有分析结果，不支持直接调用模型分析新的内容。
三、页面中有哪些功能
| 页面或区域 | 可以做什么 |
|---|---|
| API 应用 | 创建和查找外部系统使用的应用，管理各应用的接入配置 |
| API 应用 → 基础信息 | 查看应用名称、描述、App ID、创建及编辑信息，重置密钥，停用或删除应用 |
| API 应用 → 数据权限 | 配置该应用可以读取的数据 |
| API 应用 → IP 白名单 | 管理允许发起接口请求的来源 IP |
| 调用日志 | 查看接口调用情况，排查接入问题 |
仅在后台创建 API 应用，不会自动将数据同步到其他系统。 管理员负责创建应用和授权，企业技术人员或系统服务商负责开发接口调用、保存数据及联调。
四、如何接入开放 API
第 1 步：确认对接需求和接口资料
先与技术人员确定：
- 要接入哪个系统，例如 CRM 或 BI 看板。
- 需要哪些数据，例如客户资料、风险记录、超时统计。
- 数据需要多久更新一次，由技术人员安排接口查询和同步。
- 外部系统调用接口时使用的服务器公网出口 IP。
正式开发前，还需要取得与当前版本对应的接口文档，确认服务地址、认证与签名方法、接口字段、查询范围、分页方式、频率限制及错误码。若还没有接口文档，请先联系对接人员获取。
【企微文档】开放平台 API 接口资料
第 2 步：创建应用并保存凭证
- 进入「开放平台 → API 应用」。
- 点击左下角「创建 API 应用」。
- 按页面提示填写应用信息并完成创建。建议应用名称直接体现用途，例如“CRM 客户同步”或“BI 风险看板”。
- 复制 App ID 和 App Secret，并妥善保存。
建议不同接入系统分别使用应用，便于独立调整权限和排查问题。
| 凭证 | 用途 | 管理方式 |
|---|---|---|
| App ID | 标识具体应用 | 可在应用基础信息中查看和复制 |
| App Secret | 用于调用认证或签名，具体方法见接口文档 | 完整值仅在创建或重置后展示一次；交给负责对接的技术人员安全配置 |
不要将 App Secret 放在公开页面、截图或普通问题反馈中。关闭展示窗口后若没有保存完整密钥，需要通过「重置密钥」获取新的密钥。
第 3 步：配置数据权限并保存
- 在左侧选择刚创建的应用。
- 打开「数据权限」。
- 根据接入需求配置该应用可以读取的数据，并按页面提示保存。
例如，CRM 需要客户资料和风险状态，BI 看板需要客户、风险和超时指标。请与技术人员确认所用接口需要哪些权限，只授权实际需要的数据。
第 4 步：配置 IP 白名单
- 在该应用中打开「IP 白名单」。
- 向技术人员确认发起接口请求的服务器公网出口 IP。
- 按页面提示配置允许调用的来源 IP。
这里需要的是接入系统服务器的出口 IP，不是管理员电脑的内网 IP。服务器迁移或出口 IP 变化后，应同步检查白名单，避免影响调用。
第 5 步：由技术人员完成对接并验证
将 App ID、App Secret、已授权的数据类别及接口文档交给负责对接的人员，完成外部系统配置。
建议先用少量业务数据验证：
- 外部系统发起一次查询。
- 进入「开放平台 → 调用日志」，找到对应请求。
- 查看请求结果；失败时根据日志中的错误信息处理。
- 对照外部系统收到的数据，确认字段、业务对象及时间范围符合预期。
- 验证通过后，再按接口文档安排日常同步。批量数据分批处理，避免高频重复查询。
五、接入后如何管理
| 管理需求 | 操作位置与方法 | 操作后的影响或注意事项 |
|---|---|---|
| 调整应用可读取的数据 | 选择应用 → 数据权限 → 调整授权并保存 | 调整前与接入方确认，避免关闭其正在使用的数据权限 |
| 找不到 App Secret，或怀疑密钥泄露 | 选择应用 → 基础信息 → 重置密钥 | 新密钥只展示一次，需妥善保存并更新外部系统；操作前与接入方协调，按重置提示完成更换 |
| 暂停某个系统的接入 | 选择应用 → 基础信息 → 停用应用 | 停用后接口调用会失败，App ID、密钥、数据权限和 IP 白名单仍保留，可再次启用 |
| 永久移除接入应用 | 选择应用 → 基础信息 → 删除应用，输入应用名称确认 | 删除后无法恢复，历史调用日志继续保留；仅暂停使用时优先停用 |
| 服务器迁移或出口 IP 变化 | 选择应用 → IP 白名单 → 更新地址 | 建议迁移前加入新出口 IP，验证完成后再移除不再使用的旧地址 |
注意：应用显示「启用中」后，调用仍需符合凭证、数据权限、IP 白名单及接口频率等要求。
停用应用、关闭权限或删除应用，不等于删除外部系统已经保存的数据。 已同步的数据需要由企业在接收系统中另行管理。
六、调用失败时怎么排查
进入「开放平台 → 调用日志」，找到相应应用在问题发生时间的调用记录，根据调用结果和错误信息排查。
| 遇到的情况 | 优先检查与处理 |
|---|---|
| 数据权限未授权 | 检查是否选对应用，对应业务对象权限是否开启并保存 |
| 密钥或签名校验失败 | 请技术人员核对 App ID 与 Secret 是否属于同一应用、是否仍在使用重置前的密钥，以及签名是否符合接口文档 |
| 应用已停用 | 确认该系统仍需使用后，启用对应应用并重新验证 |
| IP 不在白名单 | 确认实际服务器公网出口 IP，并更新白名单；尤其检查服务器迁移、代理或网关变化 |
| 请求频率过高 | 降低轮询频率，批量任务分批执行，按接口返回的提示重试 |
| 今日调用量已达上限 | 暂停重复请求，按正式限额说明安排后续任务；需要更高额度时联系对接人员确认 |
| 调用成功但没有数据 | 核对查询条件、时间范围，以及企小码中是否实际存在符合条件的数据；成功不代表一定有匹配记录 |
| 没有找到调用日志 | 清除不必要的筛选，核对应用和时间；再请技术人员确认请求是否已发出、是否使用正确地址和企业配置 |
联系技术支持时，请提供：发生时间、应用名称或 App ID、请求 ID、失败原因，以及已做过的排查。不要附上完整 App Secret。
七、客户常见问题
能把所有客户的完整聊天记录同步到我们的 CRM 吗？
不能通过本开放平台实现。当前开放的是规定范围内的客户、风险、超时等业务数据，不包含聊天原文、完整上下文和原始消息附件。
可以拿风险数据给我们自己的 AI 做二次筛选吗？
可以围绕接口实际返回的风险等级、命中规则、审计状态及已有 AI 分析结果，在企业自己的系统中继续筛选、解读并发送通知。具体对接需以正式接口可用范围为准。
如果需求是“让自有 AI 重新阅读完整聊天，判断是否真的违规”，本开放平台提供的数据不能满足，因为它不返回聊天原文和完整上下文。外部系统的筛选结果也不会因此自动回写企小码，或自动关闭企小码原有通知。
开通 AI 分析结果权限，能主动调用企小码的 AI 分析一段内容吗？
不能。该权限用于读取已有分析结果，不提供通用模型或自定义 prompt 调用入口。
创建应用后，是不是所有数据权限都会开通？
不能这样理解。创建后需逐项检查「数据权限」，开启所需对象并保存。权限控制可访问的数据类别，实际返回内容仍以接口范围和已有数据为准。
可以获取接入前的全部历史数据吗？
不能仅凭创建应用就承诺获取全部历史。需要确认企小码实际保有的数据，以及对应接口允许的历史查询范围、时间跨度和分页限制。开放平台不会自动补回系统原本没有的数据。
能从外部系统直接修改风险审计或处理申诉吗？
不能通过当前介绍的 API 应用执行这些操作。API 应用用于外部系统读取已授权且系统实际保存的数据，审计和申诉处理仍需在对应业务页面完成。
重置密钥和停用应用，应该选哪个？
仍要继续接入、但需要更换凭证时，使用重置密钥，并同步更新外部系统。暂时不希望该应用继续调用时，使用停用应用。确认不再使用且不需要保留配置时，再删除应用。