ERP 同步中途失败,最难的是安全重试
幂等键、事务性发件箱和三方对账,让客户的账目在期末结账时分毫不差。
要点速览
- 重复分录通常来自超时后的重发,所以幂等键必须来自业务 ID,而不是随机数。
- 交易和发件箱事件写在同一个数据库事务里;429 这类瞬时错误先重试,持续失败才执行补偿。
- 对账必须区分在途资金(时间差)和真正缺失或出错的资金。
期末结账第三天,客户的总会计师发来一张截图:ERP 里同一笔打款有两条一模一样的分录,前一天的打款却不见踪影。代码没有崩溃过,日志里写的是“timeout, retrying”,接着是“success”。
为大客户做会计集成的前线部署工程师(FDE)对这种情况并不陌生。对财务团队来说,重复分录不是小 bug:只要有一个数字对不上,他们就不会在账目上签字。
一周时间足以做出一个漂亮的同步演示,但要让客户信任你的系统,它必须在成千上万次网络抖动中始终正确。
决定 ERP 集成质量的有三个问题:交易会不会丢?会不会记两次?中途失败时,账目处于什么状态?再加上客户真正关心的第四个:怎么证明两边一致?
交易在到达 ERP 之前丢失
第一类故障出在自己的服务内部。服务先把交易存进数据库,然后才发出“需要同步”的事件。如果进程恰好在这两步之间退出,记录已经存在,却没人通知同步 worker。Microsoft 把这称为双写问题。
解决办法是事务性发件箱(Transactional Outbox):把交易和事件写入 outbox 表,并放在同一个数据库事务里。Microsoft 的架构文档指出,当业务对象及其事件在同一事务中保存时,系统可以保证不丢数据。
worker 只需读取 outbox,把条目推送到 ERP。无论进程在何时退出,都不会留下缺口。
为什么一次重试会多出一条分录?
回到那张截图。设想这样的过程:worker 发送一条分录,ERP 已经入账,但响应在返回途中丢了。worker 看到超时,于是再发一次。ERP 并不知道这是同一个请求,又记了一条。
Stripe 用幂等键解决这个问题。客户端在创建或更新请求上附带一个键,发生连接错误时可以放心重发,不用担心生成第二个对象或把同一次更新执行两遍。
在 API v1 中,服务端会保存某个键的第一次响应,之后的每次重试都原样返回这个响应,即使第一次响应是 500 错误。
Stripe 的文档还补充了两个细节:键由客户端生成,至少保留 24 小时后删除;用同一个键搭配不同参数的请求会被拒绝,以便发现误用。
这两个细节引出两条规则。第一,键必须从稳定的业务 ID 派生(例如 erp-journal:po_123),绝不能每次发送都用 uuid4() 生成,因为随机键会让重试看起来像一个新请求。
第二,键会过期,而且并非所有 ERP 都提供这种机制,所以不能把去重完全交给 ERP。你必须自己维护一张从键到 ERP 记录 ID 的映射表,更重要的是,要在首次发送之前写入这一行,而不是等响应回来之后。
一个写对了的打款同步 worker
假设每天夜里要把打款推送到 NetSuite。根据 Oracle 的文档,超过并发上限时,NetSuite REST Web Services 会返回 HTTP 429,错误码为 CONCURRENCY_LIMIT_EXCEEDED,消息为“Concurrent request limit exceeded. Request blocked.”
Oracle 建议重新发送请求,重试逻辑由你的代码实现。下面的代码使用一个假设的 erp 封装,其中有一个按外部 ID 查询分录的函数:
def sync_payout(payout_id):
key = f"erp-journal:{payout_id}" # 来自业务 ID,而不是随机生成
row = mapping.get(key)
if row and row.erp_id:
return row.erp_id # 已确认入账:不再重发
if row is None:
mapping.save_pending(key) # 在首次发送之前写入“待处理”
for attempt in range(6):
found = erp.find_by_external_id(key) # 之前的某次发送可能已经入账
if found:
mapping.confirm(key, found.id)
outbox.mark_done(payout_id)
return found.id
try:
resp = erp.post_journal(build_payload(payout_id),
external_id=key, idempotency_key=key)
except Timeout: # 不确定 ERP 是否已经入账
sleep(min(2 ** attempt, 60) + random())
continue # 下一轮循环会在发送前再查一次
if resp.status == 429: # CONCURRENCY_LIMIT_EXCEEDED:瞬时错误
sleep(min(2 ** attempt, 60) + random())
continue
resp.raise_for_status()
mapping.confirm(key, resp.id) # 先确认映射,再清理 outbox
outbox.mark_done(payout_id)
return resp.id
alert_oncall(payout_id, key) # 重试次数用完:交给人工处理
用这段代码重演那天夜里的情况。发送之前,worker 已经为这个键写了一条“待处理”记录。第一次发送超时,但 ERP 实际上已经入账。worker 捕获 Timeout 异常,等待退避时间,进入下一轮循环。
下一轮循环的第一件事不是重发,而是问 ERP:带这个外部 ID 的分录是否已经存在?答案是存在,于是 worker 只确认映射,然后结束。如果 ERP 支持幂等性,同一个键还能再加一层保护,但这个设计并不依赖它。
进程直接退出、三天后才重启时,“待处理”记录同样重要:worker 看到一条未确认的记录,就一定会先查 ERP 再发送。唯一的前提是把键存进分录上一个可搜索的外部 ID 字段,这个字段应在第一周就和客户商定。
第二步失败了,第一步怎么办?
一笔真实的打款通常要跨几个系统走好几步:创建收入记录、过账分录、标记为已付。没有哪个 ACID 事务能同时覆盖你的平台和 ERP。Saga 模式用一串本地事务来代替:某一步失败时,由一系列补偿事务撤销前面各步的操作。
Saga 中有一个概念叫 pivot 事务,即不可回退点。pivot 之后的步骤必须可重试且幂等,这样即使遇到瞬时错误,saga 也总能到达最终状态。在 ERP 过账流程中,已入账的分录通常就是 pivot。
具体到每个客户,原因最好当作待验证的假设:问问总会计师,分录出错时是直接修改,还是必须做一笔冲销分录。如果它确实是不可回退点,过了这一步就只能向前走。
Microsoft 给出了很实用的优先顺序:先重试瞬时错误;只有某一步反复失败或无法恢复时,才停止并触发补偿;有些失败需要告警,让人来介入。补偿步骤本身也可能失败,所以必须写成可以重跑的幂等命令。
在会计领域,最重要的要求是可审计。Microsoft 要求原始操作和补偿操作能够关联起来,并且可以端到端审计。给原始分录、补偿分录和日志附上同一个关联 ID,审计人员只需一次搜索就能追溯整条链路。
对账是证据,不是额外工作
同步正确还不够,客户需要看到证据。Stripe 的银行对账模型是个很好的模板:每笔打款通过共享的参考键与对应的银行入账匹配,然后标记为 Reconciled(已对账)或 Unreconciled(未对账)。把这个模型扩展成三方:平台、ERP 和银行流水,共用一个键。
最大的陷阱是把时间差当成真正的错误。Stripe 的示例提到,银行通常不在周日入账打款,所以示例中 2 月 4 日(周日)的金额单元格是空的。
如果报告把这类行都标成错误,财务团队就会淹没在误报里,不再信任这份报告。
| 类别 | 信号 | 处理 |
|---|---|---|
| 已匹配 | 三方都有,金额一致 | 无需处理 |
| 时间差 | 平台和 ERP 中都有,银行尚未入账 | 等待,结算周期后再核对 |
| 真正的不一致 | 超过截止时间仍有一方缺失,或金额不同 | 建工单,按关联 ID 追查 |
从零搭建,按什么顺序?
到了新客户那里,第一件事是和总会计师坐下来,问清楚哪一步是不可回退点、出错时如何更正。答案会告诉你 pivot 在哪里,补偿步骤应该是什么样子。
接着在数据库里建好 outbox,基于业务 ID 为每一步定义键,选定 ERP 中存放键的外部 ID 字段,再写一个对瞬时错误带重试和退避的 worker。
之后才轮到补偿和告警。对账应从第一周就开始跑,而不是等到期末:上面这份三类报告,是赶在客户之前发现设计缺陷的最快办法。
让财务团队失去信任的错误
最常见的错误是每次发送都生成随机键,幂等性因此形同虚设。紧随其后的是只在响应成功后才写映射,于是恰恰在超时那一刻,映射表是空的。再就是把每个 429 或超时都当成失败,立即执行补偿,而本该先重试。
还有两个。补偿步骤不幂等,重跑一次就补偿两遍。另一个出在沟通上:把每笔尚未到账的金额都报成“不一致”。一份满是误报的报告,客户会记得比十个平稳同步的夜晚更久。
简历上怎么写这项技能
简历上一行“NetSuite 集成”几乎什么也说明不了。要写清楚你如何设计幂等同步、处理部分失败、搭建三方对账,以及在多少次期末结账中客户无需手工修改任何一行。
面试时,“ERP 已经入账但响应丢了”这个场景是一个简短的故事,能说明你会在故障发生之前就考虑它。
下次有人说“重试一下就行”,不妨问他:用哪个键重试?再次发送之前,问过 ERP 了吗?
这篇文章对你有帮助吗?
感谢你的反馈!
6 个信源
- Idempotent requests | Stripe API Reference
- Error Handling in REST Web Services (Oracle NetSuite Help)
- Saga Design Pattern - Azure Architecture Center | Microsoft Learn · 2025-02-25
- Compensating Transaction Pattern - Azure Architecture Center | Microsoft Learn · 2026-04-16
- Implement the Transactional Outbox Pattern by Using Azure Cosmos DB - Azure Architecture Center | Microsoft Learn · 2026-02-23
- Bank reconciliation | Stripe Documentation