# 美团验券接口怎么接，验券准备到执行核销别跳步, 无限聚核

> 核销服务由无限聚核提供，美团、抖音团购核销一站式接入。

搜「美团验券接口」，前排经常是官方「券码验证」文档片段，或 CSDN 上直接打 `msconsume`／「验券」一步写完的半截教程。开发真正卡的是：准备和执行哪一步真正改券状态？服务零售和到店餐饮是不是同一套路径？跳过准备会发生什么？超时后能不能换参数再打？

**一句话回答：** 美团团购验券是两段式——先**验券准备**（输码验券校验／预核销），再**执行验券**（核销）。准备只读：查可用券、拿回展示信息与不透明凭证，**不改变券状态、不发权益**；真正扣券在执行步。自研走美团开放平台对应准备／验券接口族；接第三方则用统一「预核销 → 核销」，`platform=1` 表示美团。到店餐饮文档里的 `msprepare`／`msconsume` 是**另一路由**，不要和服务零售路径混抄。依据美团技术服务合作中心公开说明与无限聚核公开 API／FAQ 整理，查阅日期 2026-10-21，字段与路径以当期官方文档与公开 API 为准。

- **准备 ≠ 核销。** 准备成功只能进确认页，不能发权益；
- **执行才改状态。** 必须带上准备返回的不透明凭证（如 `ticketInfo`）整段原文回传；
- **餐饮与服务零售分开。** `msprepare`／`msconsume` 属于到店餐饮，勿当服务零售通用名；
- **成功只认明确成功字段。** 自研看平台当期成功判定；聚合侧认顶层 `success=true`；
- **失败先分三类。** 可原样重试、明确拒绝停手、已核销转核对——不要重新准备、不要让顾客重输码。

![左栏验券准备：传门店与券码、返回套餐展示与不透明凭证、不改券状态；中栏顾客确认：展示名称售价张数；右栏执行验券：原样回传凭证、写核销状态、保存撤销凭证与订单号](assets/hero.png)

*示意图：链路按公开文档与聚合 FAQ 口径整理（2026-10-21），非平台后台截图。*

## 一、先认准：你要接的是哪一套「验券」

| 名称／说法 | 属于谁 | 配对的下一步 | 作用 |
|---|---|---|---|
| 输码验券校验／验券准备（服务零售） | 美团服务零售团购 | 验券（执行） | 查可用券，换出核销用凭证 |
| 验券（执行） | 同上 | 需要时再撤销 | 真正核销 |
| `msprepare` | 美团到店餐饮 | `msconsume` | 餐饮侧验券准备 |
| `msconsume` | 美团到店餐饮 | （餐饮撤销另有路径） | 餐饮侧执行验券 |
| 聚合预核销 → 核销 | 第三方统一接口 | 撤销（传核销返回的凭证） | 用 `platform` 区分美团／抖音，两段语义对齐平台 |

判断方法：

1. **券从哪买的、门店开在哪条业务线。** 服务零售团购与到店餐饮接口族不同，餐厅侧常见路径名带 `msprepare`／`msconsume`，不要抄服务零售示例。
2. **你是自研还是接聚合。** 自研要管商家 token、按开放平台当期文档调准备／执行；聚合用具体门店 `shopId` + `platform=1`，凭证字段名以公开 API 为准（常见为不透明 `ticketInfo`）。
3. **别被「验券」一词带偏。** 口语里「验一下券」可能指准备，也可能指执行；写代码时按接口文档的准备／执行拆开，不要做成一步 RPC。

抖音侧是 `certificate.prepare` → `certificate.verify`，与美团餐饮 `msconsume` 不是同一条链路——对照另文，本文只咬合「美团验券接口」。

## 二、两段式最小闭环：准备 → 确认 → 执行

固定成三条调用顺序（名称按口径，具体 path／字段以当期文档为准）：

1. **验券准备（预核销／输码验券校验）**  
   传入门店标识与券码（聚合侧另加 `platform=1`）。成功后拿到：套餐／项目展示信息、可核张数（若有）、**不透明凭证**。  
   **不改变券状态，不发预约／开台／出菜权益。**

2. **顾客确认**  
   用准备返回的名称、售价、张数做确认页。店员或顾客点确认后，才进入执行。

3. **执行验券（核销）**  
   回传与准备**同一组**门店、平台、券码、数量，以及准备拿到的凭证**整段原文**。成功后再落本地订单与权益。

可选第四步：**撤销**。用执行成功时保存的撤销凭证（聚合侧常见为 `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」专文；本文专注接口语义与跳步风险，不铺长代码。

## 六、联调清单（上线前自检）

1. 业态选对：服务零售 vs 到店餐饮，路径未混用；
2. 准备成功后 UI 文案是「待确认」，不是「已核销」；
3. 凭证整段落库，执行请求与准备五元组一致；
4. 成功只认文档规定的成功字段，并保存撤销凭证；
5. 超时／未知态有「结果待确认」态，禁止引导重输码；
6. 已核销类错误走核对，不走补发；
7. 撤销时限与退款流程分开处理。

## 常见问题

### 美团验券接口是一步还是两步？

两步。先验券准备（只读校验），再执行验券（真正核销）。跳过准备或把准备成功当成已核销，是联调最常见的产品与代码错误。

### 验券准备和预核销是一回事吗？

在团购核销开发语境里，常把「输码验券校验／验券准备」口语叫成预核销，指准备这一步。财务软件里的「预核销」是另一套账务概念，不要用财务词做技术主标题或状态机命名时硬套。

### msprepare／msconsume 能当服务零售通用接口名吗？

不能。它们属于美团到店餐饮文档路径。服务零售团购请用当期服务零售准备／验券接口族；聚合侧用统一预核销／核销并传 `platform=1`。

### ticketInfo 丢了或改过还能核销吗？

应按「必须整段原文回传」处理。丢失或重组后，常见结果是平台／聚合拒绝或结果不可预期；应重新走准备（仅当**尚未**执行成功、且业务规则允许时），已进入结果未知或已核销核对流程时不要随便重新准备。

### 执行超时了怎么办？

先保留原请求与已收到的部分响应，页面显示结果待确认。仅在错误码属于可重试白名单或完全无响应时，用**完全相同**的原请求有限重试；不要换参数、不要重新准备、不要让顾客重输码。仍不确定则查平台券状态或对账。

### 和抖音 prepare／verify 怎么区分？

抖音生活服务是 `certificate.prepare` → `certificate.verify`，凭证形态是 `verify_token` 与加密券码。美团服务零售与餐饮是另一套字段与成功判定。需要对照时看「抖音 prepare」专文，不要按名字把 `msconsume` 当成抖音验券确认。