已经有一个微信小程序,想让顾客在里面核销团购券 —— 这是团购核销里最常见的需求形态。技术上的第一件事不是写接口,而是把调用边界划清楚。

一、三层链路,各自负责什么

层职责不该做的事
小程序端选门店、输券码、展示确认页与结果页不持有密钥、不直接调用平台接口
你的服务端权限校验、门店映射、调核销接口、发权益不把平台原始错误直接抛给用户
核销服务方对接平台、处理授权与协议差异不管你的业务权益逻辑

这条链路的好处是:小程序只依赖你自己的域名,以后换服务方、加平台,小程序都不用重新审核发布。

二、小程序侧必须先配好的两件事

1. request 合法域名

小程序只能请求已在后台配置过的 HTTPS 域名。接入核销前,把你服务端的域名加进「开发管理 → 开发设置 → 服务器域名 → request 合法域名」。

  • 必须是 HTTPS,且证书链完整 —— 缺中间证书时微信侧校验会失败,本地浏览器却正常
  • 域名不能带端口、不能是 IP
  • 每月修改次数有限制,正式环境请提前配置好
  • 开发阶段可临时勾选「不校验合法域名」,但这个开关只在开发工具里有效,真机调试和体验版都不生效

2. 券码输入的交互约束

团购券码通常是纯数字串(常见 12 位或 14 位,少数带前缀字母)。小程序端要做的是:

  • 用数字键盘,减少输错概率
  • 输入框去除所有空格与全角字符,统一转半角
  • 不要自作聪明截断长度 —— 不同平台、不同券类型长度不一致
  • 扫码得到的码与手输的码可能形态不同,都原样提交,让服务端判断

三、核销的时序:先准备,再核销

这是最容易写错的地方。正确顺序是四步,中间那步不能省:

  1. 验券准备(预核销):把券码提交上去,校验券是否存在、是否可用、属于哪个门店、对应什么套餐
  2. 在确认页展示套餐信息,让顾客确认 —— 这一步是给顾客看的,不是给系统看的
  3. 执行核销:顾客确认后再调用,券状态才真正改变
  4. 返回结果并发放权益:预约、开门、上电、出餐,按业务来

预核销通常不计费,正式核销成功才计费。所以多做一次准备既安全又不增加成本。

四、门店授权是前置条件,不是可选项

核销前,每个门店都要完成平台侧授权 —— 商家用美团账号确认「允许这个系统替我核销」。授权拿到的是一个门店级的凭据,不是账号级的。

  • 授权是按门店做的,10 家店就是 10 次授权
  • 授权码要存在服务端,按门店ID索引,不要和用户会话混在一起
  • 授权可能过期或被商家主动解除,调用前要能识别「授权失效」并引导重新授权
  • 新开门店必须先授权,否则该店所有核销都会失败

授权环节的具体做法见「团购核销门店授权怎么做」,那篇专门讲授权失败的排查。

五、五个高频踩坑

现象原因处理
开发者工具正常,真机白屏/转圈request 域名未配置,或证书链不完整补齐合法域名,用 SSL 检测工具查中间证书
券查得到,核销报门店不匹配门店ID 填错,或该门店未授权核对门店ID 并确认授权状态
偶发超时,重试后提示券已核销网络重试导致重复提交,接口无幂等按幂等键重试,或先查询核销状态再决定
顾客看到套餐和店里不一致跳过了验券准备,直接核销恢复「准备 → 确认 → 核销」四步
换台手机就核不了门店ID 或授权码按数值/会话存储,发生精度丢失或丢失门店ID 存字符串,授权码存服务端持久层

六、用聚合接口时的差异

云飞API 这一层已经完成了平台对接与授权协议处理,小程序接入的工作量集中在三件事上:

  • 门店映射:把你的门店ID 与平台门店标识对应起来,一次配置长期使用
  • 多平台同码:同一个门店下的美团、点评、抖音、快手券走同一套调用,用平台参数区分
  • 错误语义化:返回的业务错误已归类(券不可用 / 门店未配置 / 授权失效),可直接映射成小程序里的提示文案

账号侧只需要一对服务端密钥,不存在「小程序包里放密钥」的问题。

常见问题

小程序里能直接请求美团接口吗?

技术上要过域名白名单,而美团接口域名不在你能配置的范围内;即使能配,密钥也会暴露在客户端。正确做法是走自己的服务端。

一个门店要授权几次?

每个门店、每个平台各一次。一家店同时上美团和抖音,就是两次授权。

顾客输错券码会不会有惩罚?

验券准备阶段失败不改变券状态、通常也不计费。但短时间内大量失败请求可能触发平台侧风控,建议在小程序端加基础防抖与次数提示。