接入团购核销时,券能查到、但核销时报「门店不匹配」或「门店ID有误」,绝大多数情况不是接口问题,而是门店ID填错了。
这个环节之所以容易出错,是因为「门店ID」在美团体系里有好几种不同的值,长得像但不通用。
一、先分清有几种「门店ID」
| 叫法 | 形态 | 用在哪 |
|---|---|---|
| 美团门店ID(poi_id) | 一串纯数字 | 核销时指定门店,团购业务的通行标识 |
| 大众点评门店ID | 纯数字,通常比美团门店ID短 | 点评侧核销与门店匹配 |
| 北极星门店ID | 32 位十六进制串(如 54b1ec409d7be542024312e5159855ac) | 老北极星体系,已下线,不能用于团购核销 |
| 品牌ID / 连锁ID | 纯数字,代表整个品牌或连锁 | 管理用,不能代替单店门店ID |
二、在哪里查
两条路,推荐按顺序试:
- 从美团商家后台的门店管理里看门店信息,门店详情页通常会展示门店编号类信息
- 若已拿到接口权限,直接调用门店查询类接口按门店名称检索,取返回的门店标识 —— 这条路最可靠,因为返回的就是接口认的值
大众点评门店ID 同理:在点评商家后台的门店信息里查,或者用接口按名称检索。
三、五种典型填错
| 填错方式 | 表现 | 怎么改 |
|---|---|---|
| 填成品牌ID / 连锁ID | 核销报门店不匹配,或核到了别的门店 | 换成该门店自己的门店ID |
| 填成美团商家账号 / 登录手机号 | 格式校验就过不了 | 换成门店ID,不是账号 |
| 填了中文门店名 | 直接报错「门店ID有误」 | 必须是纯数字 |
| 填了北极星 32 位串 | 格式校验失败,或提示门店不存在 | 换成美团门店ID(纯数字) |
| 粘贴时带了空格或全角字符 | 看着是数字但校验不通过 | 去掉首尾空白,统一半角 |
这五类里,第四类最隐蔽 —— 值看起来是「一串字符」,非技术人员很难判断它是哪一种。如果拿到的值长度是 32 位、含字母,基本可以确定是北极星ID。
四、为什么门店ID必须存成字符串
这是很多人事后才踩的坑。门店ID 看起来是纯数字,很自然会定义成整型,但:
- 平台的返回类型不保证一致 —— 同一字段可能时而返回数字、时而返回字符串
- 按固定类型解析时,类型一变就解析失败,直接表现为「这家门店无法核销」
- 前端展示还可能涉及精度问题(长数字在某些序列化下会被截断)
五、一个门店对应多个平台时怎么配
同一家实体店在美团、点评、抖音、快手各有一个门店标识,落地时建议:
- 建一张门店映射表:本地门店ID ←→ 各平台门店标识
- 主键用本地门店ID,各平台标识作为不同字段,不要混在一个字段里
- 平台标识允许为空(这家店只上了美团没上抖音),但核销前必须校验非空并给出明确提示
- 映射表要能由运营自己维护,不要写死在代码里
映射缺失时的正确处理是「在核销之前拦下来」,而不是核销之后失败。券核掉了才发现门店没配,就得走撤销流程,顾客会等很久。
六、排查顺序
- 确认门店ID 是纯数字、无空格、无全角字符
- 确认不是 32 位含字母的北极星ID
- 确认不是品牌/连锁ID
- 确认该门店在当前平台侧已完成授权(授权缺失也会表现成门店不匹配)
- 用接口按名称反查一次,对比返回值与自己填的是否一致
按这个顺序走,门店ID 类问题基本能在几分钟内定位。
七、用聚合接口时的差异
云飞API 把多平台的门店配置统一到一张映射上,你只需按平台填对应门店标识。两点说明:
- 门店标识一律按字符串提交,接口层不做数值转换
- 某个平台的门店标识留空时,调用该平台的核销会明确返回「门店未配置」,不会静默失败
这类配置错误集中在接入前几天,把校验做在前面、提示写清楚,能省下大量联调往返。