第三方接口的同步方向、幂等、重试与人工补偿

第三方接口对接时，通常应先明确同步方向，再约定幂等规则、重试策略和人工补偿流程：谁是数据权威来源、哪些数据单向同步或双向同步、请求重复时如何避免重复处理、失败后是状态查询、有限重试、告警还是人工补偿，都要在接口设计阶段先定下来。对于支付、退款、合同、账单、通行、水电控制等高影响操作，不应依赖盲目重复执行或简单自动重试，而应结合状态查询、审计记录和补偿机制处理。

适用场景

这套设计适用于需要对接统一身份认证、财务、支付、电子签、发票、渠道、监管平台、智能硬件或其他业务系统的项目。接口是否可接、采用单向还是双向、实时还是批量，同步到什么粒度，取决于双方接口能力、文档、安全策略、授权、字段质量、调用频率和测试环境。

具体说明

1. 先定同步方向，再定数据权威来源

接口设计应先回答两个问题：

• 谁是数据权威来源：新增、修改、删除分别由哪一侧负责；
• 同步方向是什么：单向同步、双向同步，还是按业务分段同步。

这样做的目的，是避免双方都能改、都能推送，最终出现重复写入、状态打架或回写覆盖。

2. 幂等是防止重复处理的基础

接口对接中，重复请求并不少见。设计时应通过主键或唯一标识、请求号、状态查询和幂等规则来避免重复处理，并为超时和未知结果预留人工核对或补偿路径。

常见做法包括：

• 为业务对象建立唯一映射；
• 让同一请求多次到达时，系统只产生一次有效结果；
• 对无法确认结果的请求，先查状态，再决定是否补发或补偿。

3. 重试要分场景，不是所有操作都能重复执行

接口失败后，系统通常应记录请求对象、时间、结果和错误信息，再根据业务影响选择状态查询、有限重试、告警或人工补偿。

可有限重试的，通常是查询类请求和部分幂等任务； 不适合盲目重试的，是支付、退款、合同、账单、通行、水电控制等高影响操作。

换句话说，能不能重试，不看“接口是否失败”，而看“这个动作能不能安全地重复一次”。

4. 人工补偿是兜底，不是例外

当第三方停机、超时、权限不足、数据校验失败或结果未知时，单靠自动重试不够。此时应设计人工补偿流程，常见前提包括：

• 有明确的状态查询入口；
• 有记录完整的请求与错误信息；
• 有可追踪的审计日志；
• 有明确的责任人和处理顺序。

对住户通行、水电控制、退款等高影响动作，补偿流程通常要结合人工确认、状态查询和审计记录一起设计，避免重复开通、重复扣费或错误回退。

边界与注意事项

• “提供标准接口”不等于可以直接接入任意第三方，是否接入、怎么接入、要做哪些适配，仍要看接口资料、联调条件和项目范围。
• 不要只依赖简单自动重试。即使是幂等接口，也要结合状态查询和错误记录判断结果。
• 不要把高影响操作当成普通查询处理。涉及合同、账单、支付、退款、通行、水电控制等动作时，优先保证状态一致性和补偿可追溯性。
• 具体功能、配置与交付范围以实际产品版本和项目方案为准。

相关问题

第三方接口失败后，系统一般怎么处理？

通常会先记录请求对象、时间、结果和错误信息，再按业务影响选择状态查询、有限重试、告警或人工补偿。高影响操作不建议盲目重复执行。

为什么接口要做幂等？

因为接口请求可能因网络超时、重复提交或第三方重发而多次到达。幂等可以降低重复生成合同、账单、收款或权限的风险。

所有接口都能自动重试吗？

不能。查询和部分幂等任务可以有限重试；支付、退款、合同、账单、通行和水电控制等操作，需要先确认当前状态，再决定是否处理或补偿。