团购核销幂等怎么做，重试漏单和 requestId 别踩坑, 无限聚核

联调最怕两种结局：超时后换参数再打一枪，平台其实已经核掉，本地却没有首次成功明细；或者看到「已核销」就当成功，又给顾客发了一份权益。幂等不是多传一个字段就完事，而是「首次成功怎么存、未知结果怎么重试、已核销提示怎么核对」三件事一起做对。

一句话回答： 团购核销幂等要分三层落地。自接美团验券时，用 requestId 标识同一笔业务请求：第一次拿到完整成功响应必须整份落库；超时或结果未知时，只用同一个 requestId 和同一组券码／门店／数量重试，不要换参、不要重跑准备。自接抖音时，验券准备与验券一一对应，失败后应重新 certificate.prepare，禁止拿旧的 verify_token 再试。本地业务再按「平台 + 门店 + 券码／券ID」做去重键。聚合侧命中已成功订单时常见 code=10500、errorCode=ALREADY_CONSUMED：这是核对信号，不是成功响应，不能据此补发权益或编造撤销凭证。以下整理自美团／抖音开放平台公开接口说明与无限聚核公开 FAQ／API 口径，查阅日期 2026-10-25，以官方后台与当期文档为准。

• 美团：requestId 管同一笔写请求。 成功明细只认第一次完整响应；未知结果同键重试；
• 抖音：失败就重新准备。 旧 verify_token 不符合「一次准备配一次验券」；
• 本地：platform + shop + coupon 去重。 接口层防「核成多笔」≠ 业务层自动补明细；
• 10500／已核销：停重试、去核对。 保存原单号，不要当成功入账。

一、先分清：接口幂等 ≠ 业务幂等

很多人把「幂等」理解成「随便重试都安全」。更准确的拆法是：

聚合核销公开 FAQ 写明：调用方无需自传 idempotencyKey（旧客户端传入也会被忽略）。业务系统仍要按券与自身订单去重，并保存首次完整成功记录——不能指望「再打一次就能把明细补回来」。

二、美团：requestId 怎么用才不漏单

自接美团（含大众点评来源券）服务零售验券时，公开文档要求传用于标识幂等性的请求 ID requestId，并带上券码、验券数量等。聚合层对外时，会把平台侧的幂等语义收进「原请求重试」规则；无论自接还是聚合，业务侧都要遵守同一条纪律：

1. 发核销请求前写入本地 pending（或等价状态），记下将要用的 requestId（或聚合侧完整原请求五元组：门店、平台、券码、数量、凭证）；
2. 第一次 success=true（或平台约定的成功码）：把完整响应、逐张明细、撤销所需凭证原样落库，再发权益。权益发放与核销写成功要拆开：本地权益失败走补处理，不要再核一次已经成功的券；
3. 超时、连接中断、结果未知：页面显示「结果待确认」，只用同一个 requestId／同一组原参数有间隔、有上限地重试。不要换 requestId「再开一笔」，也不要为了重试重新跑验券准备或让顾客重输码；
4. 明确拒绝：停止自动重试，展示原因；修配置后再人工发起。

requestId 的价值是：平台把「同一笔业务写请求」认成一笔。你一旦在未知结果时换了新的 requestId，就等于另开一笔写请求——若第一次其实已成功，第二次可能撞上已核销，本地却两头都没有干净的首次成功报文。

三、抖音：失败后重新 prepare，别抱着旧 token

抖音生活服务是 certificate.prepare → certificate.verify：准备返回 verify_token 与加密券码，验券确认才真正核销。公开文档要求准备与验券次数一一对应；验券成功后当前二维码失效。

和美团「同键重试」不同的关键点：

• 核销失败（明确失败）后，应重新走准备，拿新的 verify_token／加密券码，再进入下一次验券；
• 不要复用旧的 verify_token 瞎重试——不符合「一次准备配一次验券」；
• 通过聚合接口时：超时／结果未知的自动重试，仍按公开 FAQ 的白名单用完全相同的原核销请求重试，且不要重新预核销；这与「自接抖音明确失败后重新 prepare」是不同分支，按当期文档分支落地，不要混成「任何失败都重预核销」或「任何失败都抱旧 token」；
• 抖音次卡结果未知时不要自动重试，先查平台券状态或进入对账待核对（预核销返回里可判断是否次卡）。

把美团的「同 requestId」抄到抖音的 verify_token 上，是漏单与错单的常见来源。

四、本地去重键：platform + shop + coupon

接口层防的是「同请求核成多笔」；业务层还要防「同券发两份权益」「同券两条成功订单」。建议每张券一条核销记录，唯一键取：

• 平台（如美团／抖音枚举）；
• 门店（聚核门店 shopId 或你们映射后的业务门店，不要混用商户 ID）；
• 券键（美团存券码；抖音优先存券 ID／certificate_id，按字符串存大整数）。

请求发出前写 pending；成功改 succeeded 并挂上权益 ID；未知改 unknown 进入核对队列。一次核销多张券时，按响应逐项入库，不要「整请求一条糊过去」。对账任务（见「团购核销对账」专文）用同一唯一键比对平台记录与本地记录，只出差异单，不自动补发、不自动撤销。

五、10500／ALREADY_CONSUMED：核对，不是成功

聚合核销命中已成功订单时，公开口径常见为：顶层 success=false、code=10500、errorCode=ALREADY_CONSUMED，并带回原核销单号（如 wxdgOrderNo），但不再返回首次成功明细和撤销凭证。

正确动作：

1. 立刻停止该次自动核销重试；
2. 保存完整响应、原请求与原单号；
3. 用原单号与平台「已验券／券状态」核对：是否本店本单、本地是否已有首次成功记录；
4. 本地没有首次成功时：标记待核对；确认前不要仅凭 10500 补发权益，也不要编造 consumeCredential——没有首次成功响应就没有合法撤销凭证。

10500 最常见的故事是：第一次其实已经成功，客户端只看到超时／失败，店员又点了一次。提示语是在说「别再核了，去对原单」，不是「再试一次就能拿到成功报文」。

六、落地清单：发版前勾这五项

更细的失败码白名单、可重试集合，见错误码专文；每日三份数据怎么对，见对账专文。本文只钉「幂等与重试」这一截，避免把整份对账流程或完整 Java 示例再贴一遍。

常见问题

团购核销幂等只要传 idempotencyKey 就够了吗？

不够。聚合核销公开文档说明调用方无需传 idempotencyKey，旧客户端传入也会被忽略。业务系统仍须按券码（或券 ID）与自身业务订单去重，并保存首次完整成功记录；不能依赖重复请求补回成功明细。自接美团时另按平台规则使用 requestId 标识同一笔验券写请求。

超时或结果未知时，能不能换一个新的 requestId 再试？

不能。超时、结果未知时应用与首次相同的 requestId（或聚合侧完全相同的原请求参数）有间隔、有上限地重试。换新的 requestId 等于另开一笔写请求，容易在「其实已成功」时撞上已核销，本地却缺少第一份完整成功报文。也不要为了重试重新预核销或让顾客重输码。

抖音核销失败后，可以拿旧的 verify_token 继续重试吗？

不可以。抖音生活服务要求验券准备与验券一一对应；明确失败后应重新 certificate.prepare，使用新的 verify_token 与加密券码再验券。复用旧 token 不符合公开规则。聚合路径下「结果未知」的自动重试仍按当期 FAQ 白名单用原核销请求重试，且次卡结果未知禁止自动重试。

本地去重键应该怎么设计？

建议每张券一条记录，唯一键为平台 + 门店 + 券键：美团用券码，抖音用券 ID（大整数按字符串存），门店用聚核 shopId 或已映射的业务门店 ID，不要与商户 ID 混用。请求前写 pending，成功后再发权益；对账与差异处理沿用同一唯一键。

返回 10500 或 ALREADY_CONSUMED，可以直接给顾客补发权益吗？

不可以。该结果表示命中已成功订单：应停止自动重试，保存原单号与完整响应，再与平台券状态、本地首次成功记录核对。不要把已核销提示当作成功响应，不要仅凭提示补发权益，也不要编造撤销凭证；没有首次成功响应就没有合法撤销凭证。

接口幂等是否等于不用做每日对账？

不等于。接口幂等降低「同请求核成多笔」的概率，对账负责发现「平台已核本地没有」「本地成功平台没有」「已撤销权益还在」等差异。核销当下把唯一键与首次成功明细存全，次日对账才有可比数据；对账任务只出差异单，不自动补发、不自动撤销。