系统集成做到一半卡住，最常见的原因不是技术难，而是接口清单写得含糊。一句“两边对接一下”，到了联调阶段会变成几十个来回确认的消息。我们做集成项目时，接口清单是需求阶段就要定稿的东西。

接口地址与请求方式

完整的 URL、GET 还是 POST、测试环境和生产环境各一套。环境地址写混是联调初期最高频的低级错误。

鉴权方式

是 Token、AppKey 加签名，还是 Basic 认证；Token 多久过期、怎么刷新。这一项没写清楚，联调第一天就卡在 401。

字段含义与字段类型

不能只写字段名，要写清楚每个字段代表什么业务含义、是字符串还是数值、日期用什么格式、金额单位是元还是分。同名不同义的字段，是数据对不上的主要原因。

是否分页

列表接口一次返回多少条、有没有总数、翻页参数叫什么。不写清楚就会出现“只取到第一页”这种上线后才暴露的 bug。

错误码定义

成功返回什么、参数错误返回什么、对方系统不可用返回什么。要有明确的错误码，否则调用方只能靠猜，日志里也看不出所以然。

幂等与重试

同一个请求重复提交两次会怎样，失败了要不要重试、隔多久重试一次。涉及资金的接口必须写清楚，重复扣款的事故基本都出在这里。

数据时效与同步频率

是实时推送还是定时拉取，间隔多久，延迟能不能接受。业务方对“实时”的预期往往和工程实现的“准实时”不是一回事，这个要提前对齐。

这份清单看起来繁琐，但它是集成项目里唯一能避免返工的文档。我们把它作为联调的准入条件：清单没定稿，不开工。