1. 接入前准备【必看】
云飞API(来客核销)
  • API接口
    • 📱 商务合作
    • 💁 技术支持
    • 🤖AI快速接入
    • 接入前准备【必看】
      • 🤖 AI 辅助开发指南
      • OpenAPI接口调用约定
      • 申请应用开户【必看】
      • 生成accessToken
      • 💰 查询应用余额
        POST
      • 生成accessToken
        POST
    • 团购核销
      • 接入前必看
      • 🚩常见问题汇总【必看】
      • 🚩常见响应码表【开发必看】
      • 📖更新日志
      • 门店
        • 已关联门店查询
        • 设置回调通知地址
        • 🚩关联美团门店
          • 0.快速接入美团门店指引【必看】
          • 1.应用绑定美团门店
          • 1.1.设置门店授权成功回调通知地址【可选】
          • 2.生成美团门店授权码【必看】
          • 2.1.美团门店授权成功回调【可选】
          • 美团门店解除授权
          • 美团门店同步结果回调通知
          • 美团服务零售客户授权结果回调通知
          • 查询已授权美团服务零售客户
        • 🚩关联抖音门店
          • 0.快速接入抖音门店指引【必看】
          • 1.抖音门店授权步骤【必看】
          • 2.应用绑定抖音门店
        • 🚩关联快手门店
          • 1.快手门店授权步骤【必看】
          • 应用绑定快手门店
      • 商品
        • 获取门店团购信息
      • 团购核销API
        • 查券和验券
        • 撤销验券
        • 批量撤销验券
        • 手机号查询可用团购券
        • 团购退款预校验
        • 团购退款申请
        • 团购退款信息查询
        • 团购退款审核
      • 订单服务API
        • 订单券码分摊金额查询
        • 查询团购订单结算扩展明细
  1. 接入前准备【必看】

🤖 AI 辅助开发指南

云飞API(来客核销 OpenAPI)· AI 接入助手提示词#

以下内容请完整复制,粘贴到你的 AI 工具(Cursor / ChatGPT / Claude / Copilot / 通义 等)中,
然后直接用自然语言说你的需求即可。

📌 怎么用#

1.
从下方 --- 分隔线开始,全选复制(包括分隔线以下所有内容)
2.
粘贴到 AI 对话框中,发一条消息
3.
然后直接提需求,例如:
"用 Python + requests 写一段核销对接代码"
"用 Java 封装一个 TokenProvider,带 Redis 缓存"
"我调核销接口返回 code=400,msg=券码无效,帮我排查"
"用 Node.js 写一个查券 → 核销的完整流程"
4.
AI 会严格按照云飞API契约生成代码,不会瞎编字段或接口

⚠️ 注意事项#

首次粘贴后,建议先让 AI 复述一遍核心约束(比如"必须缓存 accessToken"),确认它理解了
如果 AI 生成的代码不符合你的框架习惯,补充一句"我用的是 xxx 框架,请调整"
报错排查时,把 code、msg、tid、请求路径、platform、opPoiId 一起贴给 AI

云飞API(来客核销 OpenAPI)接入规范#

以下是云飞API的接口契约,你在帮我写对接代码时必须严格遵守,不要凭空发明接口、字段或行为。

基础信息#

Base URL:http://wspacebot.yunfeiwork.com
协议:HTTP + JSON
Content-Type:application/json;charset=UTF-8
示例:
拿 accessToken:POST {base}/wspace-openapi/oauth/token
查券/核销:POST {base}/wspace-openapi/partner/tuangou/receipt/consume?access_token=xxx
关联门店:POST {base}/wspace-openapi/partner/app/bind/shop?access_token=xxx

鉴权方式#

access_token 必须作为 URL 查询参数 传递,不能放在 Header 或 Body 里。
✅ 正确:
POST /wspace-openapi/partner/tuangou/receipt/consume?access_token=xxx
❌ 错误:
Authorization: Bearer xxx
Body 里传 access_token

获取 Token#

POST /wspace-openapi/oauth/token
Body: {"appId": "...", "appSecret": "..."}
返回:data.accessToken(有效期 data.expiresIn 秒)
⚠️ 必须缓存 accessToken,禁止每次请求都重新获取。建议提前 60~300 秒刷新。多实例环境需保证 accessToken 共享与刷新互斥。

公共响应结构(所有接口统一)#

{
    "code": 200,
    "msg": "验证成功",
    "data": {},
    "tid": "202412112134332BEA1F1E7DB8F93AE378"
}
判断成功只看 code == 200,不要只看 HTTP 状态码。
data 可能为空对象/空数组/null,解析前先判空。
tid 是云飞侧日志 ID,报错时务必保留,用于排查问题。

核销接口#

POST /wspace-openapi/partner/tuangou/receipt/consume?access_token=xxx
Body 参数:
字段类型必填说明
receiptCodestring是用户券码
opPoiIdstring是门店ID
platformstring否meituan / douyin,不传默认 meituan
typeint是1=查券(不扣费),2=核销(扣费)
verifyCountinttype=2时必填核销数量,默认取查券返回总数

⚠️ 核心约束#

1.
type=1 只查不核销、不扣费
2.
type=2 成功才计费
3.
幂等由调用方控制(建议:券码 + 业务单号 + 状态机)

门店绑定(抖音来客)#

POST /wspace-openapi/partner/app/bind/shop?access_token=xxx
关键字段:opPoiId、dyShopId、dyAccountId、platform=douyin、businessType(DDZH/DDCY)

代码生成要求#

1.
用我指定的语言/框架写,确保可运行
2.
accessToken 必须缓存,带过期刷新逻辑
3.
超时设置:连接 3s,读取 5s
4.
重试:仅网络异常/429/5xx 做指数退避;业务错误(code≠200)不自动重试
5.
日志必须记录 tid、platform、opPoiId
6.
appSecret 和 access_token 全文禁止打印到日志
7.
appSecret 只能从配置中心/环境变量读取,不能硬编码、不能进前端
8.
响应解析先判断 code == 200,再读 data

排障#

报错时我需要看到:code、msg、tid、请求路径、platform、opPoiId。
文档里没写的字段或接口,明确告诉我"文档未定义",不要编造。

安全红线#

核销是资金动作,必须做幂等(唯一索引/分布式锁)
不能在客户端/前端直接调核销接口
不要假设有退款/冲正接口,除非文档明确给出
修改于 2026-11-03 03:14:25
上一页
🤖AI快速接入
下一页
OpenAPI接口调用约定
Built with