第三方对接扯皮的地方，很少在接口能不能连通，多半在文档没写清楚。六样东西齐了，联调通常两三轮就能收口；缺哪一样，就会在那一样上反复来回，一来回就是一周。下面按"缺了会出什么事"的顺序写，不按实现顺序。

一、鉴权方式要写清凭证怎么取、多久换一次、换的时候怎么办。包括凭证有效期、刷新时机、双方服务器时钟偏差的允许范围——偏差超过几十秒就会报错这种事必须写在正文里，不能等联调时才发现；多套环境的密钥不得共用。缺这一条的常见样子是：对方按固定凭证开发完了，上线后定期轮换把两边同时打断，第一周的订单全在重试。

二、下单与查询要有字段表和一组真实形状的示例。字段表逐项写名称、必填性、类型、取值范围、示例值和口径说明：数量算的是张数还是人数、日期带不带时分、外部单号是否全局唯一、重复提交怎么认定幂等。示例至少三组——成功、库存不足、参数错误。只给一组成功示例的文档，对方一定会把可选字段当必填传，上线第一天就报参数错。

三、库存与核销的推送时机，是最容易被一句话带过的一项。要写明库存是全量覆盖还是增量变更、由什么事件触发推送、推送失败之后怎么补偿；核销要写清是核验成功即时推还是按批次推，批次间隔多久，撤销核销怎么表达。这一项不明确，分销端就会出现卖得出去、核不掉的票，退款全部堆到窗口。

四、错误码表要分"能重试"和"不能重试"两栏。同一句"库存不足"，能重试和不能重试的处理完全不同。表里要给四列：错误码、含义、调用方应当做的动作、是否幂等可原样重发。只列码不写动作的表等于让对方自己猜，猜错的那一方在旺季会把自己的请求重试到把通道打停。

五、联调测试环境要能造数据，也要说清与生产的差异。除了环境入口、可用票种、可造的单号前缀，还要明确三件事：时段模板与生产是否一致、测试核销记录会不会回流到统计、数据什么时候清空。缺这一条的结果是对方按测试环境的行为上线，生产上的库存和核销节奏全乱，回头还说是接口变了。

六、限流与超时约定要写在同一页上，不能一个在附件里。每秒请求上限、单次查询最大返回条数、超时时间按秒给出、超时之后可否原样重发、拉取库存的建议节奏。这五项决定了对方的重试逻辑会不会把系统打停，也决定了旺季高峰查询是不是要降级。写"视情况而定"等于没写，联调时只会各按各的理解测。

六样之外还有一句：文档要有版本号和变更记录，接口变更需要提前几天通知也要写进去。改动不带版本号，两边各自按手上的旧文档联调，最后一轮全部作废。缺一项就补一项；缺三项以上时不要急着开工，先把文档补齐再谈联调，这一步省下来的时间最后会全部还回去。