写券码校验的时候,很容易假设「团购券码就是 12 位数字」。多数情况确实如此,但有例外,而这个例外会让你的正则把合法券判成非法。
一、两种格式,取决于商家配置
| 格式 | 长度 | 出现条件 |
|---|---|---|
| 普通券码 | 12 位数字 | 默认情况 |
| bin 码券码 | 14 位,77 前缀 | 商家在美团侧配置了 bin 码(扩展字段) |
官方说明是:如果扩展字段有 bin 码,则返回 binCode(77)前缀加 14 位券码;没有则返回普通券码。这个 77 前缀由美团运营在美团侧按商家维度配置。
二、为什么不能自己判断平台
有人想通过券码长度或前缀反推这是美团券还是别的平台券。这条思路走不通 —— 官方明确说没有可用于判断平台的券码规则。
正确做法:平台由你的业务侧决定(用户从哪个入口来、扫的是哪个平台的码),而不是从券码字符串猜。
三、扫码内容不是券码本身
顾客出示的二维码扫出来往往是一段 URL,券码藏在参数里。常见处理顺序:
- 先去掉首尾空格与不可见字符(手输场景尤其容易带空格)
- 如果是 URL,按已知参数名提取券码
- 提取不到则认为不是有效券码,提示重试,不要硬猜
把整段 URL 直接当券码传给接口,会得到「券码无效」—— 这是扫码核销最常见的失败原因之一。
四、一个容易踩的规则:撤销后券码会变
这个规则很多人不知道:某张券撤销之后,平台会换成一张新券码。
影响有两个:
- 用旧券码再去查,会查不到 —— 不是数据丢了,是码换了
- 目前没有「用旧券码反查新券码」的能力,官方也说明暂无建设计划
所以撤销之后如果要跟进,靠的是购券订单号,不是券码。这也是为什么核销记录里必须存订单号,而不仅是券码。
五、查不到券时的排查顺序
- 券是否已核销过(已核销的券不能用验券准备再查一遍期望它可核)
- 券是否过期、已退款、或适用条件不满足(这三类是「券码失效」的常见原因)
- 若是 77 前缀券,试着去掉前缀查询
- 改用购券订单号查询
- 门店是否授权正确、映射是否对上
按这个顺序走,绝大多数「券码无效」能在两分钟内定位是数据问题还是配置问题。
六、用聚合接口时要注意什么
云飞API 对券码做统一处理,但两个原则仍然成立:
- 不要在前端做长度硬校验,把原始内容传给接口,由接口返回明确结果
- 抖音可以传完整短链,美团不行 —— 这类差异由接口层处理,你按平台传对应内容即可
如果你的系统要在核销前展示套餐信息给店员确认,那一步就是验券准备,别跳过。详见我们另一篇讲两阶段区别的文章。