接入团购核销时,券能查到、但核销时报「门店不匹配」或「门店ID有误」,绝大多数情况不是接口问题,而是门店ID填错了。

这个环节之所以容易出错,是因为「门店ID」在美团体系里有好几种不同的值,长得像但不通用。

一、先分清有几种「门店ID」

叫法形态用在哪
美团门店ID(poi_id)一串纯数字核销时指定门店,团购业务的通行标识
大众点评门店ID纯数字,通常比美团门店ID短点评侧核销与门店匹配
北极星门店ID32 位十六进制串(如 54b1ec409d7be542024312e5159855ac)老北极星体系,已下线,不能用于团购核销
品牌ID / 连锁ID纯数字,代表整个品牌或连锁管理用,不能代替单店门店ID

二、在哪里查

两条路,推荐按顺序试:

  1. 从美团商家后台的门店管理里看门店信息,门店详情页通常会展示门店编号类信息
  2. 若已拿到接口权限,直接调用门店查询类接口按门店名称检索,取返回的门店标识 —— 这条路最可靠,因为返回的就是接口认的值

大众点评门店ID 同理:在点评商家后台的门店信息里查,或者用接口按名称检索。

三、五种典型填错

填错方式表现怎么改
填成品牌ID / 连锁ID核销报门店不匹配,或核到了别的门店换成该门店自己的门店ID
填成美团商家账号 / 登录手机号格式校验就过不了换成门店ID,不是账号
填了中文门店名直接报错「门店ID有误」必须是纯数字
填了北极星 32 位串格式校验失败,或提示门店不存在换成美团门店ID(纯数字)
粘贴时带了空格或全角字符看着是数字但校验不通过去掉首尾空白,统一半角

这五类里,第四类最隐蔽 —— 值看起来是「一串字符」,非技术人员很难判断它是哪一种。如果拿到的值长度是 32 位、含字母,基本可以确定是北极星ID。

四、为什么门店ID必须存成字符串

这是很多人事后才踩的坑。门店ID 看起来是纯数字,很自然会定义成整型,但:

  • 平台的返回类型不保证一致 —— 同一字段可能时而返回数字、时而返回字符串
  • 按固定类型解析时,类型一变就解析失败,直接表现为「这家门店无法核销」
  • 前端展示还可能涉及精度问题(长数字在某些序列化下会被截断)

五、一个门店对应多个平台时怎么配

同一家实体店在美团、点评、抖音、快手各有一个门店标识,落地时建议:

  • 建一张门店映射表:本地门店ID ←→ 各平台门店标识
  • 主键用本地门店ID,各平台标识作为不同字段,不要混在一个字段里
  • 平台标识允许为空(这家店只上了美团没上抖音),但核销前必须校验非空并给出明确提示
  • 映射表要能由运营自己维护,不要写死在代码里

映射缺失时的正确处理是「在核销之前拦下来」,而不是核销之后失败。券核掉了才发现门店没配,就得走撤销流程,顾客会等很久。

六、排查顺序

  1. 确认门店ID 是纯数字、无空格、无全角字符
  2. 确认不是 32 位含字母的北极星ID
  3. 确认不是品牌/连锁ID
  4. 确认该门店在当前平台侧已完成授权(授权缺失也会表现成门店不匹配)
  5. 用接口按名称反查一次,对比返回值与自己填的是否一致

按这个顺序走,门店ID 类问题基本能在几分钟内定位。

七、用聚合接口时的差异

云飞API 把多平台的门店配置统一到一张映射上,你只需按平台填对应门店标识。两点说明:

  • 门店标识一律按字符串提交,接口层不做数值转换
  • 某个平台的门店标识留空时,调用该平台的核销会明确返回「门店未配置」,不会静默失败

这类配置错误集中在接入前几天,把校验做在前面、提示写清楚,能省下大量联调往返。