美团的团购核销是两步:先「验券准备」,再「验券」。这两个名字很像,导致大量开发者以为是一个操作的不同叫法 —— 这是这个环节最高频的错误来源。

一、本质区别:一个只读,一个写

验券准备验券(核销)
作用检查券是否可用,取回套餐信息与待确认凭证正式核销,改变券状态
性质只读确认写操作
能否发权益不能可以,但必须确认返回成功
是否计费通常不计费计费
能否跳过不能不能

二、跳步会具体出什么问题

跳过验券准备直接调验券,最常见的三种表现:

  1. 查不到券:用券码去查券信息,返回空或券不存在。因为未验证的券不在可查范围。
  2. 取不到套餐信息:拿不到套餐名、售价、可核销数量,前端无法展示给店员确认。
  3. 拿不到待确认凭证:验券接口通常需要回传准备阶段返回的那段凭证,缺了就会失败。

还有一种更隐蔽的错误:准备成功了,但页面直接提示「已核销」。这在业务上非常危险 —— 券实际上还没核,顾客被告知核销成功,事后必然投诉。准备成功的正确文案是「待确认」。

三、准备阶段返回的凭证必须原样保存

验券准备返回的凭证(不同接口里可能叫 ticketInfo、verify_token 之类)是一段不透明字符串。正确处理方式是整段原样落库,核销时原样回传。

不要做的事:

  • 不要解析它再重组 —— 格式随时可能变,解析等于给自己埋雷
  • 不要只存其中几个字段 —— 少了任何一个都可能校验失败
  • 不要用准备阶段的参数重新构造一份 —— 必须用服务端返回的原始值

配套要求是:核销时传的门店、平台、券码、数量这一组参数,必须与准备阶段完全一致。任何一项变了,凭证就对不上。

四、超时和结果未知怎么处理

核销请求超时是最容易把状态搞乱的地方。正确处理原则:

情况该怎么做不该做什么
明确成功保存完整响应,再发放权益不要重复调用
明确拒绝(券不可用等)停止重试,把原因展示给店员不要自动换门店或换券码重试
超时 / 结果未知用幂等键做有限次原样重试不要重新跑一遍验券准备
提示已核销拿原订单号核对,走人工确认不要当成核销成功去补发权益

五、联调时按这个清单自检

  • 业态路径没混用(餐厅走餐饮那套,非餐饮走服务零售那套)
  • 准备成功的界面文案是「待确认」,不是「已核销」
  • 待确认凭证整段落库,核销时原样回传
  • 核销用的门店 / 平台 / 券码 / 数量与准备阶段完全一致
  • 成功字段与撤销凭证都落库了
  • 结果未知时不引导顾客重新输码

六、用聚合接口时这两步还在吗

在。聚合接口只是把各平台的字段差异抹平,两阶段的语义不变。云飞API 的调用方式是「预核销 → 核销 → 撤销」,对应关系是:

  • 预核销 = 验券准备,只读、不计费
  • 核销 = 验券,写操作、按成功次数计费
  • 撤销 = 撤销验券,需回传核销时返回的凭证

换句话说,理解了这两步的区别,换成任何平台或任何聚合服务都不会再踩同一个坑。这也是我们把这篇文章放在开发实战最前面的原因。