跳到正文
观点文章/文章详情

对接第三方接口前,双方应该确认哪些资料?

核心结论

对接前把六件事写成双方确认的交接表:业务字段与主键由谁生成、重复请求如何识别;鉴权用哪个账号、凭证如何轮换;哪些错误可以重试、哪些不能;频率与超时上限;测试环境和数据;版本变更如何通知。接口文档只描述调用方式,不替代这些业务约定。

两套业务系统之间的接口请求卡,标注业务主键、鉴权凭证、错误分支和双方交接表

先看一个假设的例子:项目启动会上,对方发来一份 30 页的接口文档:有哪些地址、每个请求带什么字段、返回什么 JSON。双方都以为可以开工了。三周后联调,订单系统重发了一次超时的创建请求,对方系统多生成了一张订单。再往后,测试环境里能通过的签名,换成正式凭证就失败。

接口文档描述的是怎么调用,不描述双方对业务的共同约定。文档发过来之后,还有六件事需要确认。

接口文档通常缺什么

常见接口文档会写地址、请求方法、字段名、示例报文和返回码列表。它通常不写:业务主键由谁生成、重复请求算不算同一件事、凭证归谁管理、哪些错误可以自动重试、调用频率上限是多少、测试环境是否与正式环境一致、版本变更提前多久通知。

这些内容不属于“技术细节”,它们决定业务会不会重复记账、丢单或卡在无人处理的失败里。对接前要把它们写进一份双方确认的交接表,而不是等联调时在群里逐条问。

业务字段和主键:谁生成,重复请求算什么

先定每个对象的业务主键。订单号、客户编号、物料编码,由哪一方生成,格式是什么,是否允许修改,冲突时以哪边为准。主键不能只在各自的数据库里唯一,它必须在双方之间能对应上。

再定重复请求的识别方式。常见的做法是请求方带一个幂等键,接收方在第一次成功后记住这个键,后续相同键的请求返回第一次的结果,而不是再建一条记录。幂等键由哪一方生成、保存多久、重复时返回什么,都要写明。

金额要写清币种和最小单位,避免一方用元、一方用分。时间要写清时区和格式,跨系统的时间比较很容易差八小时。状态字段不要直接互传内部枚举值,先做一张状态映射表:对方系统的“已确认”对应本系统的哪个状态,对应不上的进入哪个待处理状态。

鉴权与权限:用谁的账号,凭证怎么换

接口通常用独立的系统账号,而不是某个员工的个人账号。员工调岗或离职,不应让接口突然失效;反过来,共享一个管理员账号,也无法知道是哪套系统在调用。

要确认:凭证类型是什么,由谁签发,保存在哪里,多久轮换一次,泄露后如何作废;调用方在对方系统里拥有哪些权限,是否只限必要的读写;是否有 IP 白名单或其他来源限制;每次调用是否留下可追溯的日志。

不要把正式凭证写进前端代码、聊天记录或仓库的示例配置。凭证轮换要有重叠期,先发新凭证、确认调用切换成功,再停用旧凭证,避免轮换当天接口全断。

错误与重试:哪些请求可以重发

失败后的重试判断
  1. 网络或临时故障
  2. 受控重试并核对幂等
  3. 权限、校验或冲突
  4. 修正原因或人工核对

新建类请求在自动重试前需确认幂等机制和服务端处理结果。

失败不都等于可以重试。按 RFC 9110 第 9.2.2 节,GET、HEAD、OPTIONS、TRACE、PUT、DELETE 是幂等方法,重复发送相同请求的预期效果与发送一次相同;POST 不是。用 POST 创建订单时,没有幂等键就自动重试,可能创建两张订单。

因此重试规则至少分三类:

  1. 可安全重试:网络超时、连接中断、对方返回 503。可以退避后重试,但要设次数上限和总时长。对方返回 503 并带 Retry-After 时,按它给出的等待时间再试,不立刻重发。见 RFC 9110 第 15.6.4 节。
  2. 不能自动重试,需要先对账:POST 新建类请求超时,但无法确认对方是否已经处理。先用查询接口按业务主键查一次,确认没有写入再重发。
  3. 重试没有意义:字段校验失败、权限不足、凭证过期、业务规则拒绝。把错误原文或双方约定的错误码交给人和日志,不要反复重发。

对方返回 409 时,按 RFC 9110 第 15.5.10 节,表示请求与目标资源当前状态冲突,响应应包含足以让人识别冲突的信息。这通常意味着需要人看一眼,而不是自动重试。

错误码表要双方共同维护:每个码对应什么原因、由谁处理、是否可重试、用户看到什么文案。只给对方一段英文堆栈,运营无法处理。

调用频率、超时与批量

频率上限要写成具体数字,并说明是每秒、每分钟还是每天,按账号还是按接口。超过上限时对方返回什么,调用方如何排队或降级,要提前约定。

批量接口要写清单次最多多少条、部分成功时返回什么、失败的行怎么重试。不要假设“批量提交要么全成功要么全失败”,很多接口是逐条处理的。

超时时间也要双方一致。调用方设 10 秒超时,对方实际 30 秒才处理完,调用方会认为失败并重试,造成重复。异步任务更要把“已受理”和“已完成”分开:先拿任务编号,再轮询或等回调。

测试环境、版本与上线切换

测试环境要能覆盖正式环境的主要行为,包括鉴权、错误码和限流。测试凭证与正式凭证分开,测试数据不要使用真实客户资料。双方要约定联调窗口、谁能在测试环境造数据、出现问题时找谁。

接口变更要提前通知:新增字段通常兼容,删除字段、改字段含义、改错误码、改鉴权方式则可能让调用方直接失败。版本号怎么带、旧版本保留多久、切换时双方如何验证,都写进交接表。

上线切换要有回退方案。先小流量或单账号试运行,确认对账一致,再扩大范围。切换当天保留双方的值班人和回退开关。

接口交接表

项目

需要确认的内容

由谁提供

验收方式

业务主键

生成方、格式、是否可改、冲突规则

双方业务负责人

用一张测试订单双向核对

幂等

幂等键、保存时长、重复请求返回

接收方

同一请求发送两次,只产生一条记录

字段映射

状态、金额单位、时区、枚举

双方

字段对照表逐项签字

鉴权

账号、凭证轮换、权限范围、日志

双方技术负责人

用测试凭证与正式凭证各调用一次

错误

错误码、可重试性、处理人、文案

接收方

制造一次校验失败与一次 503

频率与超时

上限、批量大小、部分成功、超时值

双方

压测或模拟限流

测试环境

地址、数据、联调窗口、联系人

双方

一条完整任务在测试环境走通

版本变更

通知方式、提前期、旧版保留

双方

变更记录可查

这张表不需要很厚,但每一行都要有具体答案和负责人。空着的行,就是联调时会卡住的地方。

先挑一个最小的接口,例如查询一条订单状态,把上面八行填完再开始写代码。查询接口跑通后,再处理创建和修改。业务系统开发中怎样把接口范围写进项目,可参考业务系统开发;现有表格和主数据怎样整理,可参考业务系统准备清单。

AI 接入 ERP 或 OA 的分级与权限边界,见AI 怎么接入 ERP 和 OA。那篇讨论的是 AI 动作级别,不替代本文的接口交接表。

资料来源

聊聊你的项目

网站 / 业务系统 / AI 应用

企业微信咨询