API接口对接，是让两个系统按约定传递数据并处理返回结果。项目推进时，最容易耗费时间的往往不是发出请求，而是双方对同一个字段、同一种“成功”有不同理解：接口返回正常，页面却没有更新；测试环境运行顺利，上线后却出现重复记录。

文档写着“成功”，页面却没有结果

接口联调开始前，双方一般会交换地址、认证方式和字段说明。但文档中的“必填”“可为空”如果没有对应到具体业务状态，开发人员很可能各自作出合理却不同的解释。

例如，假设一个业务系统通过第三方接口提交订单。联调时，请求得到成功响应，业务系统随即把订单标记为“已完成”；随后查询第三方系统，却暂时找不到对应记录。排查方向不能停在“HTTP状态码是200”。这个状态码只表明请求获得了正常的网络响应；返回体中的业务代码，以及第三方是否还要异步处理，才关系到订单当前处于什么状态。

对接双方此时要核对接口约定：返回的成功究竟指“已接收请求”，还是“业务处理完成”？如果只是已接收，业务系统就不能直接展示最终结果。可以保留“处理中”状态，并按双方约定的方式获取后续结果；若有回调，还要确认回调未到达时如何查询。

在这个假设情境中，订单状态的改动能够继续推进，但第三方处理完成的时间仍未明确。联调记录里应留下请求标识和返回内容，双方下次沟通时针对同一笔请求核对，不必反复用截图猜测各自看到的是哪一步。

请求超时后，重复提交该怎么处理

接口对接进入实际运行后，超时比明确报错更难判断。调用方没有收到响应，并不能据此认定对方没有处理请求。如果直接重试创建类接口，就可能生成两条订单或重复触发一次操作。

这类请求要提前约定幂等处理：同一业务动作使用稳定的业务标识，对方收到重复请求时，返回已有处理结果或明确告知当前状态，而不是重新执行。调用方也要记录每次请求的标识、发送时间和响应，避免把新的业务操作误当作超时重试。对于尚未确认结果的请求，先查询处理状态，再决定后续动作。

并非所有接口都采用同一种重试方式。查询接口通常允许再次请求；创建、扣减、提交等会改变数据的操作，则要看服务方是否支持幂等标识，以及重复提交会产生什么后果。文档没有写清时，应把该问题带到联调中验证，不要等上线后用真实业务数据试错。

上线前还有哪些约定没有写清

功能跑通后，检查范围可以收拢到两处：一是错误响应能否让调用方采取明确动作，二是测试环境与生产环境的配置差异。认证失败、参数不合法和服务端暂时不可用，不宜都被包装成同一句“调用失败”。日志中保留必要的请求标识与错误信息，敏感凭证则不写入日志。

生产环境的地址、密钥和回调配置，也要在切换前逐项核对。联调结束时，双方把“接收成功”与“处理完成”的判定写进接口约定，再用同一个业务标识测试一次超时后的重复请求。若对方尚未提供状态查询或幂等能力，就先确认业务系统如何保留待处理记录，避免把未知结果显示成已完成。