美团的团购核销是两步:先「验券准备」,再「验券」。这两个名字很像,导致大量开发者以为是一个操作的不同叫法 —— 这是这个环节最高频的错误来源。
一、本质区别:一个只读,一个写
| 验券准备 | 验券(核销) | |
|---|---|---|
| 作用 | 检查券是否可用,取回套餐信息与待确认凭证 | 正式核销,改变券状态 |
| 性质 | 只读确认 | 写操作 |
| 能否发权益 | 不能 | 可以,但必须确认返回成功 |
| 是否计费 | 通常不计费 | 计费 |
| 能否跳过 | 不能 | 不能 |
二、跳步会具体出什么问题
跳过验券准备直接调验券,最常见的三种表现:
- 查不到券:用券码去查券信息,返回空或券不存在。因为未验证的券不在可查范围。
- 取不到套餐信息:拿不到套餐名、售价、可核销数量,前端无法展示给店员确认。
- 拿不到待确认凭证:验券接口通常需要回传准备阶段返回的那段凭证,缺了就会失败。
还有一种更隐蔽的错误:准备成功了,但页面直接提示「已核销」。这在业务上非常危险 —— 券实际上还没核,顾客被告知核销成功,事后必然投诉。准备成功的正确文案是「待确认」。
三、准备阶段返回的凭证必须原样保存
验券准备返回的凭证(不同接口里可能叫 ticketInfo、verify_token 之类)是一段不透明字符串。正确处理方式是整段原样落库,核销时原样回传。
不要做的事:
- 不要解析它再重组 —— 格式随时可能变,解析等于给自己埋雷
- 不要只存其中几个字段 —— 少了任何一个都可能校验失败
- 不要用准备阶段的参数重新构造一份 —— 必须用服务端返回的原始值
配套要求是:核销时传的门店、平台、券码、数量这一组参数,必须与准备阶段完全一致。任何一项变了,凭证就对不上。
四、超时和结果未知怎么处理
核销请求超时是最容易把状态搞乱的地方。正确处理原则:
| 情况 | 该怎么做 | 不该做什么 |
|---|---|---|
| 明确成功 | 保存完整响应,再发放权益 | 不要重复调用 |
| 明确拒绝(券不可用等) | 停止重试,把原因展示给店员 | 不要自动换门店或换券码重试 |
| 超时 / 结果未知 | 用幂等键做有限次原样重试 | 不要重新跑一遍验券准备 |
| 提示已核销 | 拿原订单号核对,走人工确认 | 不要当成核销成功去补发权益 |
五、联调时按这个清单自检
- 业态路径没混用(餐厅走餐饮那套,非餐饮走服务零售那套)
- 准备成功的界面文案是「待确认」,不是「已核销」
- 待确认凭证整段落库,核销时原样回传
- 核销用的门店 / 平台 / 券码 / 数量与准备阶段完全一致
- 成功字段与撤销凭证都落库了
- 结果未知时不引导顾客重新输码
六、用聚合接口时这两步还在吗
在。聚合接口只是把各平台的字段差异抹平,两阶段的语义不变。云飞API 的调用方式是「预核销 → 核销 → 撤销」,对应关系是:
- 预核销 = 验券准备,只读、不计费
- 核销 = 验券,写操作、按成功次数计费
- 撤销 = 撤销验券,需回传核销时返回的凭证
换句话说,理解了这两步的区别,换成任何平台或任何聚合服务都不会再踩同一个坑。这也是我们把这篇文章放在开发实战最前面的原因。