写券码校验的时候,很容易假设「团购券码就是 12 位数字」。多数情况确实如此,但有例外,而这个例外会让你的正则把合法券判成非法。

一、两种格式,取决于商家配置

格式长度出现条件
普通券码12 位数字默认情况
bin 码券码14 位,77 前缀商家在美团侧配置了 bin 码(扩展字段)

官方说明是:如果扩展字段有 bin 码,则返回 binCode(77)前缀加 14 位券码;没有则返回普通券码。这个 77 前缀由美团运营在美团侧按商家维度配置。

二、为什么不能自己判断平台

有人想通过券码长度或前缀反推这是美团券还是别的平台券。这条思路走不通 —— 官方明确说没有可用于判断平台的券码规则。

正确做法:平台由你的业务侧决定(用户从哪个入口来、扫的是哪个平台的码),而不是从券码字符串猜。

三、扫码内容不是券码本身

顾客出示的二维码扫出来往往是一段 URL,券码藏在参数里。常见处理顺序:

  1. 先去掉首尾空格与不可见字符(手输场景尤其容易带空格)
  2. 如果是 URL,按已知参数名提取券码
  3. 提取不到则认为不是有效券码,提示重试,不要硬猜

把整段 URL 直接当券码传给接口,会得到「券码无效」—— 这是扫码核销最常见的失败原因之一。

四、一个容易踩的规则:撤销后券码会变

这个规则很多人不知道:某张券撤销之后,平台会换成一张新券码。

影响有两个:

  • 用旧券码再去查,会查不到 —— 不是数据丢了,是码换了
  • 目前没有「用旧券码反查新券码」的能力,官方也说明暂无建设计划

所以撤销之后如果要跟进,靠的是购券订单号,不是券码。这也是为什么核销记录里必须存订单号,而不仅是券码。

五、查不到券时的排查顺序

  1. 券是否已核销过(已核销的券不能用验券准备再查一遍期望它可核)
  2. 券是否过期、已退款、或适用条件不满足(这三类是「券码失效」的常见原因)
  3. 若是 77 前缀券,试着去掉前缀查询
  4. 改用购券订单号查询
  5. 门店是否授权正确、映射是否对上

按这个顺序走,绝大多数「券码无效」能在两分钟内定位是数据问题还是配置问题。

六、用聚合接口时要注意什么

云飞API 对券码做统一处理,但两个原则仍然成立:

  • 不要在前端做长度硬校验,把原始内容传给接口,由接口返回明确结果
  • 抖音可以传完整短链,美团不行 —— 这类差异由接口层处理,你按平台传对应内容即可

如果你的系统要在核销前展示套餐信息给店员确认,那一步就是验券准备,别跳过。详见我们另一篇讲两阶段区别的文章。