已经有一个微信小程序,想让顾客在里面核销团购券 —— 这是团购核销里最常见的需求形态。技术上的第一件事不是写接口,而是把调用边界划清楚。
一、三层链路,各自负责什么
| 层 | 职责 | 不该做的事 |
|---|---|---|
| 小程序端 | 选门店、输券码、展示确认页与结果页 | 不持有密钥、不直接调用平台接口 |
| 你的服务端 | 权限校验、门店映射、调核销接口、发权益 | 不把平台原始错误直接抛给用户 |
| 核销服务方 | 对接平台、处理授权与协议差异 | 不管你的业务权益逻辑 |
这条链路的好处是:小程序只依赖你自己的域名,以后换服务方、加平台,小程序都不用重新审核发布。
二、小程序侧必须先配好的两件事
1. request 合法域名
小程序只能请求已在后台配置过的 HTTPS 域名。接入核销前,把你服务端的域名加进「开发管理 → 开发设置 → 服务器域名 → request 合法域名」。
- 必须是 HTTPS,且证书链完整 —— 缺中间证书时微信侧校验会失败,本地浏览器却正常
- 域名不能带端口、不能是 IP
- 每月修改次数有限制,正式环境请提前配置好
- 开发阶段可临时勾选「不校验合法域名」,但这个开关只在开发工具里有效,真机调试和体验版都不生效
2. 券码输入的交互约束
团购券码通常是纯数字串(常见 12 位或 14 位,少数带前缀字母)。小程序端要做的是:
- 用数字键盘,减少输错概率
- 输入框去除所有空格与全角字符,统一转半角
- 不要自作聪明截断长度 —— 不同平台、不同券类型长度不一致
- 扫码得到的码与手输的码可能形态不同,都原样提交,让服务端判断
三、核销的时序:先准备,再核销
这是最容易写错的地方。正确顺序是四步,中间那步不能省:
- 验券准备(预核销):把券码提交上去,校验券是否存在、是否可用、属于哪个门店、对应什么套餐
- 在确认页展示套餐信息,让顾客确认 —— 这一步是给顾客看的,不是给系统看的
- 执行核销:顾客确认后再调用,券状态才真正改变
- 返回结果并发放权益:预约、开门、上电、出餐,按业务来
预核销通常不计费,正式核销成功才计费。所以多做一次准备既安全又不增加成本。
四、门店授权是前置条件,不是可选项
核销前,每个门店都要完成平台侧授权 —— 商家用美团账号确认「允许这个系统替我核销」。授权拿到的是一个门店级的凭据,不是账号级的。
- 授权是按门店做的,10 家店就是 10 次授权
- 授权码要存在服务端,按门店ID索引,不要和用户会话混在一起
- 授权可能过期或被商家主动解除,调用前要能识别「授权失效」并引导重新授权
- 新开门店必须先授权,否则该店所有核销都会失败
授权环节的具体做法见「团购核销门店授权怎么做」,那篇专门讲授权失败的排查。
五、五个高频踩坑
| 现象 | 原因 | 处理 |
|---|---|---|
| 开发者工具正常,真机白屏/转圈 | request 域名未配置,或证书链不完整 | 补齐合法域名,用 SSL 检测工具查中间证书 |
| 券查得到,核销报门店不匹配 | 门店ID 填错,或该门店未授权 | 核对门店ID 并确认授权状态 |
| 偶发超时,重试后提示券已核销 | 网络重试导致重复提交,接口无幂等 | 按幂等键重试,或先查询核销状态再决定 |
| 顾客看到套餐和店里不一致 | 跳过了验券准备,直接核销 | 恢复「准备 → 确认 → 核销」四步 |
| 换台手机就核不了 | 门店ID 或授权码按数值/会话存储,发生精度丢失或丢失 | 门店ID 存字符串,授权码存服务端持久层 |
六、用聚合接口时的差异
云飞API 这一层已经完成了平台对接与授权协议处理,小程序接入的工作量集中在三件事上:
- 门店映射:把你的门店ID 与平台门店标识对应起来,一次配置长期使用
- 多平台同码:同一个门店下的美团、点评、抖音、快手券走同一套调用,用平台参数区分
- 错误语义化:返回的业务错误已归类(券不可用 / 门店未配置 / 授权失效),可直接映射成小程序里的提示文案
账号侧只需要一对服务端密钥,不存在「小程序包里放密钥」的问题。
常见问题
小程序里能直接请求美团接口吗?
技术上要过域名白名单,而美团接口域名不在你能配置的范围内;即使能配,密钥也会暴露在客户端。正确做法是走自己的服务端。
一个门店要授权几次?
每个门店、每个平台各一次。一家店同时上美团和抖音,就是两次授权。
顾客输错券码会不会有惩罚?
验券准备阶段失败不改变券状态、通常也不计费。但短时间内大量失败请求可能触发平台侧风控,建议在小程序端加基础防抖与次数提示。