系统兼容性

快速阅读

本文说明平台增强 OpenAPI、推送和 Webhook 时，哪些变化算向后兼容，接入方应按什么方式解析。

• 平台可能新增资源、字段、可选参数、事件类型；对象 ID 等不透明字符串的长度或格式也可能调整。
• 响应里多出来的字段、字段顺序变化、未识别的事件类型，按可扩展方式处理，不要把整单判失败。
• 本文是长期对接约定。某一次上线删字段、改语义或换入口，以当时的发布说明或项目联调方案为准。

阅读地图

• 哪些增强算向后兼容：读「二」。
• 什么情况下要单独评估改造：读「三」。
• 接入时怎么解析：读「四」。
• 签名、管理对象、话单推送、通话事件：读「五」列出的专题。

一、文档说明

企业把自有系统接到呼叫中心开放能力之后，OpenAPI、话单 / 推送和实时会话控制里的事件回调会持续增强。增强时优先走向后兼容：已经按约定接入的系统，通常不必为「多了一点信息」立刻改代码。

本文主要说明：

• 哪些变更属于向后兼容增强。
• 接入方解析响应和事件时应遵守的约定。
• 和鉴权认证、管理集成、数据与分析集成、Webhooks 等专题怎么分工。

适用：对接 OpenAPI 的技术负责人、接收 Webhook / 推送的系统负责人、实施联调人员。

签名算法、逐接口参数、完整事件类型和推送动作，见对应专题页。

二、向后兼容的增强

在不改变现有对接语义的前提下，平台可能做以下增强。接入方按可扩展方式解析。

补充说明：

• 新增字段：查询话单、座席、任务等接口时，响应里可能逐步多出字段；只取当前业务需要的字段即可。
• 可选参数：新参数用于新能力；旧调用不传，应继续按原约定工作。
• 不透明字符串：如对象 ID、requestId、通道相关标识等，长度和字符形态可能变化，不要用正则或定长截断去校验格式。
• 新事件类型：与 Webhooks：事件回调 一致——不认识的类型不要拖垮整批接收。

三、需要单独评估的变更

向后兼容指：已有调用在同样入参下，原有字段语义保持可用；平台可以多给信息、多给可选能力。

下列情况需要单独评估、联调和改造：

• 删除已有字段，或把可选请求参数改成必填。
• 改变已有字段的含义、枚举取值语义，或改变成功 / 失败判定口径。
• 改变鉴权方式、签名算法、权限模型等安全约定。
• 下线某条接口、某种推送动作，或要求切换到新入口才能完成原业务。

这类变更若发生，以正式发布说明、工单通知或项目联调方案为准。

四、接入方约定

按下面方式接入，可以吸收向后兼容增强：

1. 按字段名解析，不要按数组下标或 JSON 字段顺序写死。
2. 允许未知字段：反序列化时忽略未建模字段，或只映射白名单字段。
3. 事件按类型分发：认识的类型进业务逻辑；不认识的类型记日志后按成功应答，避免平台反复重推。
4. ID 当不透明字符串：入库、比对、回传都原样使用，不假设长度、前缀或纯数字。
5. 新可选参数按需启用：需要新能力再传；不要为了传全而填无业务含义的默认值。
6. 联调验收：除主流程外，抽一条「多字段响应」和一条「未知事件类型」用例，确认接收方不会因此失败。

五、和其他文档的分工

六、常见问题

多出来的响应字段要不要立刻改代码？
先确认业务是否要用新字段。用不到就忽略，解析器不要因未知字段失败。

Webhook 收到从未见过的事件类型怎么办？
按成功处理并落日志，便于以后补业务。不要返回失败导致整单重推。详见 Webhooks：事件回调。

对象 ID 长度变了，历史数据怎么办？
新旧 ID 都按字符串保存和比对。不要用定长字段截断，也不要按旧长度做校验。

可选参数不传，会不会走到新逻辑？
向后兼容的约定是：不传新可选参数时，行为与增强前一致。若某次发布改变了默认行为，按第三节单独说明。

这篇和接口变更日志是什么关系？
本文是长期有效的对接约定。某次具体上线删了什么、迁到哪，以当时的发布说明或项目通知为准。