美团验券接口怎么接，验券准备到执行核销别跳步, 无限聚核
核销服务由无限聚核提供，美团、抖音团购核销一站式接入。
目录（7 节）
搜「美团验券接口」，前排经常是官方「券码验证」文档片段，或 CSDN 上直接打 msconsume／「验券」一步写完的半截教程。开发真正卡的是：准备和执行哪一步真正改券状态？服务零售和到店餐饮是不是同一套路径？跳过准备会发生什么？超时后能不能换参数再打？
一句话回答： 美团团购验券是两段式——先验券准备（输码验券校验／预核销），再执行验券（核销）。准备只读：查可用券、拿回展示信息与不透明凭证，不改变券状态、不发权益；真正扣券在执行步。自研走美团开放平台对应准备／验券接口族；接第三方则用统一「预核销 → 核销」，platform=1 表示美团。到店餐饮文档里的 msprepare／msconsume 是另一路由，不要和服务零售路径混抄。依据美团技术服务合作中心公开说明与无限聚核公开 API／FAQ 整理，查阅日期 2026-10-21，字段与路径以当期官方文档与公开 API 为准。
- 准备 ≠ 核销。 准备成功只能进确认页，不能发权益；
- 执行才改状态。 必须带上准备返回的不透明凭证（如
ticketInfo）整段原文回传； - 餐饮与服务零售分开。
msprepare／msconsume属于到店餐饮，勿当服务零售通用名； - 成功只认明确成功字段。 自研看平台当期成功判定；聚合侧认顶层
success=true； - 失败先分三类。 可原样重试、明确拒绝停手、已核销转核对——不要重新准备、不要让顾客重输码。
一、先认准：你要接的是哪一套「验券」
| 名称／说法 | 属于谁 | 配对的下一步 | 作用 |
|---|---|---|---|
| 输码验券校验／验券准备（服务零售） | 美团服务零售团购 | 验券（执行） | 查可用券，换出核销用凭证 |
| 验券（执行） | 同上 | 需要时再撤销 | 真正核销 |
msprepare |
美团到店餐饮 | msconsume |
餐饮侧验券准备 |
msconsume |
美团到店餐饮 | （餐饮撤销另有路径） | 餐饮侧执行验券 |
| 聚合预核销 → 核销 | 第三方统一接口 | 撤销（传核销返回的凭证） | 用 platform 区分美团／抖音，两段语义对齐平台 |
判断方法：
- 券从哪买的、门店开在哪条业务线。 服务零售团购与到店餐饮接口族不同，餐厅侧常见路径名带
msprepare／msconsume，不要抄服务零售示例。 - 你是自研还是接聚合。 自研要管商家 token、按开放平台当期文档调准备／执行；聚合用具体门店
shopId+platform=1，凭证字段名以公开 API 为准（常见为不透明ticketInfo）。 - 别被「验券」一词带偏。 口语里「验一下券」可能指准备，也可能指执行；写代码时按接口文档的准备／执行拆开，不要做成一步 RPC。
抖音侧是 certificate.prepare → certificate.verify，与美团餐饮 msconsume 不是同一条链路——对照另文，本文只咬合「美团验券接口」。
二、两段式最小闭环：准备 → 确认 → 执行
固定成三条调用顺序（名称按口径，具体 path／字段以当期文档为准）：
-
验券准备（预核销／输码验券校验）
传入门店标识与券码（聚合侧另加platform=1）。成功后拿到：套餐／项目展示信息、可核张数（若有）、不透明凭证。
不改变券状态，不发预约／开台／出菜权益。 -
顾客确认
用准备返回的名称、售价、张数做确认页。店员或顾客点确认后，才进入执行。 -
执行验券（核销）
回传与准备同一组门店、平台、券码、数量，以及准备拿到的凭证整段原文。成功后再落本地订单与权益。
可选第四步：撤销。用执行成功时保存的撤销凭证（聚合侧常见为 consumeCredential 数组），在平台允许的时限内撤销；撤销与消费者付款退款是两件事。美团侧撤销窗口常见约 10 分钟，以平台当前说明为准。
聚合侧路径示意（Host 与完整 URL 以公开 API 文档为准，下文只写语义名）：
| 步骤 | 语义 | 要点 |
|---|---|---|
| 准备 | …/ddzh-tuangou-receipt-prepare |
shopId + platform=1 + code；存 ticketInfo |
| 执行 | …/ddzh-tuangou-receipt-consume |
原样回传 ticketInfo；认 success=true；存 wxdgOrderNo、data[]、consumeCredential[] |
| 撤销 | …/ddzh-tuangou-receipt-cancel |
传 consumeCredential（常见 1–10 项） |
shopId 必须是聚合侧具体门店 ID，不是商户 ID、不是你系统门店主键、不是美团经营宝门店码。
三、凭证怎么存：ticketInfo 当黑盒
准备成功后的凭证（聚合侧常叫 ticketInfo；自研侧字段名以开放平台当期文档为准）建议按下面规矩处理：
| 做法 | 要／不要 |
|---|---|
| 服务端整段字符串保存 | 要 |
| 核销时原样放进请求体 | 要 |
| 解析 JSON 后删字段再序列化 | 不要 |
| 用凭证去「猜」商品 ID／门店 ID | 不要 |
| 准备成功就当已核销写库发权益 | 不要 |
商品映射：美团券常用展示名与售卖价与本地已配置商品预匹配；核销成功后再以返回明细里的成交／项目标识为准。匹配不到唯一商品时先完善配置，不要拆凭证硬猜。
四、成功、失败与重试：别跳步补枪
成功
- 聚合：只认顶层布尔
success=true；不要只看 HTTP 200 或数字code。 - 自研：按开放平台当期成功判定（常见有业务
code／文案），以官方文档为准。 - 成功后保存首次完整响应、原请求、门店／平台／券码关联；按明细与撤销凭证下标一一对应落库，再发自己的权益。
失败分支（聚合口径摘要）
| 类别 | 信号举例 | 动作 |
|---|---|---|
| 可重试 | CONSUME_IN_PROGRESS、RESULT_UNKNOWN、SERVICE_UNAVAILABLE、PROVIDER_UNAVAILABLE，或超时无完整响应 |
保留原请求五元组，有间隔、有上限地原样重试 |
| 明确拒绝 | PLATFORM_REJECTED 等 |
停自动重试，展示返回原因 |
| 已核销提示 | ALREADY_CONSUMED（常见外层 code=10500） |
停重试；用返回的原单号核对；不要当成功、不要补发、不要编造撤销凭证 |
重试时不要：重新跑准备、换门店／券码／张数、让顾客重新输码。抖音次卡「结果未知」另有例外（不自动重试），美团路径仍以当期 FAQ 为准。
五、自研与聚合对照（只谈验券主链路）
| 维度 | 自研美团开放平台 | 第三方聚合 |
|---|---|---|
| 前置 | 服务商／自研品牌资质与商家授权 | 建门店、店主授权给服务商 |
| 准备 | 开放平台「输码验券校验／验券准备」族 | 统一预核销，platform=1 |
| 执行 | 对应「验券」写接口 | 统一核销，回传准备凭证 |
| 幂等 | 按平台文档传幂等键（若有） | 接口层防重复核成多笔；业务仍要按券码＋本地订单去重 |
| 餐饮 | 改走餐饮路由（msprepare／msconsume 等） |
建店时选对业态，勿混服务零售路径 |
两条路都不要「跳过准备直接核」。需要 Java 可运行示意时，另见官网「美团核销 Java」专文；本文专注接口语义与跳步风险，不铺长代码。
六、联调清单（上线前自检）
- 业态选对：服务零售 vs 到店餐饮，路径未混用；
- 准备成功后 UI 文案是「待确认」，不是「已核销」；
- 凭证整段落库，执行请求与准备五元组一致；
- 成功只认文档规定的成功字段，并保存撤销凭证；
- 超时／未知态有「结果待确认」态，禁止引导重输码；
- 已核销类错误走核对，不走补发；
- 撤销时限与退款流程分开处理。
常见问题
美团验券接口是一步还是两步？
两步。先验券准备（只读校验），再执行验券（真正核销）。跳过准备或把准备成功当成已核销，是联调最常见的产品与代码错误。
验券准备和预核销是一回事吗？
在团购核销开发语境里，常把「输码验券校验／验券准备」口语叫成预核销，指准备这一步。财务软件里的「预核销」是另一套账务概念，不要用财务词做技术主标题或状态机命名时硬套。
msprepare／msconsume 能当服务零售通用接口名吗？
不能。它们属于美团到店餐饮文档路径。服务零售团购请用当期服务零售准备／验券接口族；聚合侧用统一预核销／核销并传 platform=1。
ticketInfo 丢了或改过还能核销吗？
应按「必须整段原文回传」处理。丢失或重组后，常见结果是平台／聚合拒绝或结果不可预期；应重新走准备（仅当尚未执行成功、且业务规则允许时），已进入结果未知或已核销核对流程时不要随便重新准备。
执行超时了怎么办？
先保留原请求与已收到的部分响应，页面显示结果待确认。仅在错误码属于可重试白名单或完全无响应时，用完全相同的原请求有限重试；不要换参数、不要重新准备、不要让顾客重输码。仍不确定则查平台券状态或对账。
和抖音 prepare／verify 怎么区分？
抖音生活服务是 certificate.prepare → certificate.verify，凭证形态是 verify_token 与加密券码。美团服务零售与餐饮是另一套字段与成功判定。需要对照时看「抖音 prepare」专文，不要按名字把 msconsume 当成抖音验券确认。
