常见问题FAQ

团购核销接口常见问题

资质、费用、接口对接与平台差异,按接入时真正会卡住的顺序整理。 共 34 个问题,答案都尽量给到能直接判断的程度。

接入路径与资质

自己申请还是接第三方接口,两条路的门槛差在哪

云飞 API 支持哪些平台的团购券码核销?

目前已支持美团、大众点评、抖音、快手四大主流本地生活平台的团购券码核销接口,通过统一 API 网关实现一站式对接,无需分别接入各平台。

团购券码核销 API 的接入流程是怎样的?

接入流程分为三步:① 提交企业资料申请应用开户 → ② 获取 API 密钥和接口文档 → ③ 根据文档完成对接调试。接入接口调试阶段不收取任何费用,最快 1 天即可完成对接。

自己申请美团团购核销接口,需要准备什么?

自行对接需要先成为美团侧的服务商或品牌商,核心门槛有三项:保证金(服务零售业务开通时账户余额需达标,公开资料常见口径为 10 万元)、Web 应用防火墙证明、以及二级等保证明或网络安全保险二选一。此外还要按业务线(到店餐饮 / 到店综合)分别开通,并完成每个门店的商家授权。技术对接本身不是最难的部分,卡人的通常是有资金占压与资质周期的那几项。

个人或个体工商户能申请团购核销接口吗?

团购核销业务面向企业主体,个人不具备直接申请条件。平台服务商入驻页确实有「个人开发者」入口,但那是面向其他能力的实名开通,不等于个人能接团购核销 —— 这是这一环最常见的误判。个体工商户是独立市场主体,但部分材料按企业口径设定,能否满足需按平台当前规则逐项确认。如果只是想尽快让门店能核券,走已接入的第三方接口是更短的路。

已经接了美团,抖音还要单独申请吗?

自己对接时要。抖音是另一套独立的资质与接口体系,需要单独入驻、单独申请能力、单独完成门店授权,一方通过不自动带入另一方。如果走聚合接口,两个平台在同一套调用下以平台参数区分,不需要写第二套核销代码,但门店侧仍需分别完成两个平台的授权。

大众点评的券要单独接一套接口吗?

不需要。点评用户购买的团购券走美团同一套团购接口,不是第三个独立平台,区分来源靠接口返回的渠道字段。所以「美团 + 点评」在技术上是一套对接,不是两套。

费用与计费

钱到底花在哪,哪些是可以避免的

接入核销 API 需要多少费用?

接入接口不收费。正式商用后按核销券码成功计费,充值档位越高单价越低,量大从优。具体请联系商务团队获取详细报价。

为什么接入你们可以免掉 10 万元保证金?

保证金本质是平台对开发者履约能力的风险对冲。我们已与平台方完成技术服务对接,由我们统一承担接口调用侧的合规与结算责任,这笔保证金不再需要由每个开发者单独缴纳。你无需冻结资金,开户后即可获取测试额度并开始对接。

接入调试阶段收费吗?

不收费。开户后即可拿到测试额度并开始联调,跑通预核销、核销、撤销全链路之后再决定是否充值。这样做的原因很实际:核销这种写操作,不实际跑一遍根本不知道自己的重试与幂等设计对不对,先付费再调试对双方都不合理。

按什么计费?预核销算不算一次?

按核销成功次数计费,充值额度不过期,用完再充即可。预核销(验券准备)通常不计费 —— 它只是校验券是否可用,不改变券状态。这个差别对开发很重要:可以放心地做「先准备、让顾客确认、再核销」的两阶段流程,不会因为多查一次而增加成本。

单价是怎么算的?

按充值档位分档递减,低至 0.05 元/券。档位越高单价越低,具体档位表请联系商务获取。需要说明的是:折算方式是「到账金额 ÷ 单价」得到可核销次数,实际以成功核销次数为准,未核销的额度不会消耗。

撤销核销的那一笔还会计费吗?

按核销成功计费的模式下,撤销后通常不计入成功核销。但不同服务方的具体规则可能有差异,接入前应当确认清楚。这一点对账时很关键 —— 如果撤销未同步扣减,核销笔数会多于平台账单,差异会一直挂在那里。

比起自建,接第三方接口长期看会更贵吗?

取决于核销量与团队成本。自建的成本不是单价,而是保证金占压 + 等保测评 + 双平台开发人力 + 长期运维。当核销量很大、且平台接口变动频繁时,自建的单位成本才可能更低。多数团队的实际路径是:先用第三方接口把业务跑起来,量级上来后再评估自建是否划算。

技术对接

真正写代码时会卡住的地方

核销接口的响应速度和稳定性如何?

云飞 API 核销接口提供99.9% 可用性 SLA 保证,平均响应时间在 200ms 以内,支持高并发请求,已稳定服务全国超过 20000 家商户。

接入需要我们改造现有系统吗?

不需要。接口为标准 RESTful 协议,在你的服务端发起 HTTP 请求即可,现有业务系统与数据库结构无需改动。核销成功后由你的系统继续衔接会员权益、预约、开门或设备启动等环节。

接入你们的接口,我们还需要自己做二级等保吗?

不需要。平台侧的技术对接与安全合规责任由我们作为接口服务方承担;你的系统只是调用方,不直接与平台侧接口对接,因此不必为这类业务单独做等级保护测评。这对中小软件团队意味着省下一笔测评成本与数周整改周期。如果你的客户或招标方要求提供合规材料,我们可配合出具接口服务说明与安全责任划分说明。

我们团队只有两三个人,能接得动吗?

可以。接口为标准 HTTP 协议,只提供验券、核销、撤销等必要能力,半天即可完成首次跑通。同时提供 AI 辅助接入:把接口文档交给 AI 编程工具,可直接生成带签名与重试逻辑的调用代码,最快 5 分钟拿到第一个成功响应。调试阶段不收费,跑通后再决定是否充值。

验券准备(预核销)和执行核销有什么区别?为什么要调两次?

验券准备只做校验:券是否存在、是否可用、属于哪个门店、对应什么套餐,不改变券状态。执行核销才真正扣券。调两次不是为了多一步,而是为了让顾客在确认页看到「我要用哪张券、换什么套餐」之后再扣券 —— 跳过准备直接核销,一旦套餐不对就只能走撤销,而撤销有平台侧时限,超时退不回来。

接口超时了要重试吗?

不能直接重试。超时不等于失败 —— 请求可能已经在平台侧生效了,只是响应没回来,盲目重试会造成同一张券核两次。正确顺序是:先查询券状态,已核销就按成功处理并补记本地流水;确未核销才重试,且必须带同一个幂等键。查询本身也超时的情况,应进入「待确认」队列由定时任务再查,不要凭猜测下结论。

门店 ID 填对了,为什么还报门店不匹配?

多半是填了「看起来像门店 ID」的另一个值。美团体系里至少有四种:美团门店 ID(纯数字)、点评门店 ID(纯数字但更短)、北极星体系的 32 位十六进制串、以及品牌/连锁 ID。后两种最常见被误填。另外还有一个隐性原因:门店没做过授权也会表现成「门店不匹配」,所以核对 ID 之前先确认授权状态。

核销成功了但后台查不到记录,是怎么回事?

先分清是「真的没成功」还是「响应丢了」。判断依据是平台侧的实际扣券记录,不是你的本地日志。如果平台有记录而本地没有,属于响应丢失,补记流水即可,不要重复核销;两边都没有,才是请求真的没生效。有一类情况要特别警惕:只判断了 HTTP 200 而没看业务码,结果一整天记的都是假成功,直到对账才暴露。

券码是几位?有固定长度吗?

常见 12 位或 14 位(含 77 前缀),但不同平台、不同券类型的长度并不统一,所以不要按固定长度截断或校验。线上常见错误是前端按 12 位限制输入框,结果 14 位的券根本输不进去。正确做法是原样提交,让服务端判断;输入侧只做去空格、统一半角这类清理。

一个订单买了好几份,要核几次?

核销的最小单位是「券」,不是「订单」。顾客买 3 份套餐,就是一个订单对应 3 张券,需要按券处理。最容易踩的坑是只核了一次却出了 3 份餐,或者反过来核了 3 次只出一份。建议在验券准备阶段就把「本券含 N 份」展示出来,并且把出餐动作放在全部券核销成功之后,不要在循环里每核一张就出餐。

平台与迁移

多平台差异,以及老系统的去处

美团和抖音的核销接口能共用一套代码吗?

业务逻辑可以,适配层必须分开。两者在六处不同:业务线切分方式、授权粒度、券类型丰富度、成功判断字段、撤销时限与可撤销范围、错误码体系。其中「成功判断」和「错误语义」这两处最危险 —— 判断错了不会报错,只会在对账时发现数据是错的。可行结构是三层:业务层不变,适配层每个平台一份,调用层处理签名与重试。

餐饮门店能用自助门店的接口吗?

不能。美团把到店业务分成「到店餐饮」与「到店综合(服务零售)」两条线,接口、授权、门店体系全部独立,接口名前缀都不同。餐厅照搬洗车店的接口路径,第一步就通不过。判断依据是门店的主营类目,不是门店名字 —— 混合业态(既卖餐又提供其他服务)按主营类目归属,接入前应向平台确认。

北极星开放平台还能用吗?

不要依赖它。北极星的技术及运营服务已由美团技术服务合作中心承接,原文档中心与控制台逐步下线。官方两处说明的措辞并不完全一致(一处写「逐步进行下线处理」,一处写「已于 2025 年 6 月 25 日正式下线」),但对开发者来说做法是同一个:新的对接都在技术服务合作中心完成。老系统若出现「原控制台进不去、新门店绑不上」这类症状,优先怀疑这一层,而不是签名或券码。

从北极星迁移过来,门店 ID 要重新录吗?

要转换,不能直接沿用。北极星存的 openShopUuid 是混淆后的点评门店 ID,新平台要的 opPoiId 是混淆后的美团门店 ID,两者一一对应但值不同,必须调官方的转换接口换一次。这个坑特别难查,因为转换前后都是一串混淆字符,肉眼分辨不出来,而报错只会说「门店不匹配」,很容易误以为自己填对了。

老系统的门店授权能直接沿用吗?

不能指望直接沿用。授权方式本身已经从 session 换成了标准 OAuth 2.0 的令牌,且按业务分别授权、令牌不能跨业务使用。换过开发者或系统的门店,必须由商家本人在美团页面重新确认授权 —— 这一步你替代不了。另外提醒一个隐蔽的坑:再次授权时权限范围要传全量,只传新增项会把原有权限覆盖掉,而且不会立刻报错。

行业与场景

不同业态接入时真正该关心的事

支持哪些行业的团购券核销?

覆盖餐饮美食、酒店住宿、旅游景点、休闲娱乐(KTV / 密室逃脱 / 剧本杀等)、运动健身、生活服务(美容美发 / 洗浴足浴 / 宠物服务等)六大行业,超过 30 种细分业态。

顾客能在我们自己的小程序里自己核销吗?

可以,但这和店员核销是两套模型。店员核销只需要门店授权;顾客自助核销多一层用户授权 —— 顾客先授权,系统才能查到他名下有哪些券。没有这一层,连「这个顾客有什么券」都查不到,因为券信息属于用户隐私,不在门店维度公开。好处是体验顺:顾客不用手输一长串券码,点一下就能看到本店可用的券,还能一次核销多张。

自助门店(洗车 / 台球 / 健身房)核销后要做什么?

核销只是触发,真正的动作在你自己系统里:洗车是工位自动上电并开始计时,台球是开台计时,健身房是开门禁。这三类场景的共同点是无人值守,所以关键不在核销本身,而在「核销成功后动作必须可靠执行」—— 核销成功但设备没启动,比核销失败更麻烦,因为钱已经扣了。建议把「核销」与「设备动作」做成两个可独立重试的步骤,中间失败要有补偿。

场馆类(游泳 / 滑冰 / 射箭)和普通门店有什么不同?

差别在库存形态:场馆卖的不是「一次进门」,而是某个时段的某个位置,库存是时段 × 位置的矩阵。这决定了两种落位模型:核销即落位(简单,但高峰会超卖)和先预约后核销(可控,但核销前必须校验预约)。多数场馆最终会走到后者,因为团购流量集中在周末与晚间。如果一开始按「核销即落位」做,后面补预约会推翻整条核销链路。

连锁品牌几十家门店,授权要一家家做吗?

授权粒度是门店级的,通常需要逐店完成,一家店 × 一个平台算一份授权。批量授权能力取决于平台是否提供,接入前应按自己的门店结构确认。运营上更实际的做法是:把授权状态做成可查看的列表,标注已授权 / 待授权 / 即将到期,并支持一键生成授权二维码直接发给门店负责人 —— 否则「哪家店没授权」只能等核销失败才发现。

给门店做系统的 SaaS,能一套代码服务多个商户吗?

可以,前提是商户维度贯穿授权、门店映射、计费三处。漏掉任何一处都会串数据 —— 最典型的是 A 商户的核销请求用到了 B 商户的授权,表现是券核到了别的店。门店映射表的唯一索引建议建在「商户 + 平台 + 本地门店」上,平台门店标识允许为空(该店没上这个平台),但核销前必须校验非空并给出明确提示。

还有没答到的问题?

说清楚门店类型与现有系统,我们能直接判断走哪条业务线、需要多久。 调试阶段免费,跑通后再决定是否充值。