# 场馆SaaS怎么接美团运动场馆预订直连, 必接消息与退款审核, 无限聚核

> 核销服务由无限聚核提供，美团、抖音团购核销一站式接入。

**预订直连是什么：** 商户系统把场馆时段库存接到美团后，用户在美团店页「预订」里直接选日期／场地／时段下单支付，不必另找团购券核销才能订场。团购仍可同页并存；订场走预订直连消息与答复，不走验券核销。

**商户接上后，用户怎么看到：** 店页出现「预订」能力与日期／起价；点进选场次后是场地×时段网格，已订灰显、可订显示价格，再提交订单支付。下图为京体运动中心望京南湖羽毛球馆在美团 C 端的真实界面（截图日期约 2026-11-01）。

![美团商家页「预订」Tab：场馆预订（羽毛球）、日期与起价；同页下方团购区仍在，说明预订与团购可并存](assets/c-end-shop-booking-tab.png)

*美团店页「预订」Tab（京体运动中心望京南湖羽毛球馆）：场馆预订（羽毛球）展示日期与起价；同页下方仍有团购区。*

![选择场次弹层：日期条、1～4号场×时段网格；已订灰显、可订显示价格；底部提交订单](assets/c-end-select-slots.png)

*选场次弹层：按日期展开 1～4 号场与各时段；已订灰显、可订显示价格，选好后点「提交订单」。*

**开发者要接的不是概念，是这三类 Webhook 模式：**

| mode | 回调里做什么 | 要不要另调答复 API |
|---|---|---|
| `query`／`command` | **同一次 HTTP 响应**返回业务 JSON（成功 `code=0`） | 否；禁止先 204 再补答 |
| `decision` | 先可靠保存，回 **HTTP 204**（只表示收到） | **是**：再调答复预订结果／答复退款审核 |
| `notification` | 可靠保存，回 HTTP 2xx（建议 204） | 否 |

无限聚核在中间做鉴权、门店归属、验签转发与答复投递；接单／拒单／库存数字／同意退款仍由场馆系统决定。查阅日期 2026-11-03，字段与枚举以当期公开体育馆 API 为准。

![示意图：左栏 C 端订场六步；中栏开始预订、预订结果回调、库存查询；右栏规则退与非规则退超时默认拒](assets/hero.jpg)

*总览示意（2026-11-03）。下文四张时序图与公开体育馆文档站流程一致：商品发布、5810033 库存、5810017 接单、5810013 退款审核。*

## 一、先分清：预订直连要接哪些消息

团购验券、商品上下架、订场接单是三套能力。本文内核是**预订直连 Webhook + 答复 API**。商品直连只作为接订场前的前置（没有可订商品／规则，C 端无场可卖）；团购核销另文。

| msgType | 名称 | mode | 回调 HTTP | 另调答复？ |
|---|---|---|---|---|
| 5810033 | 多商品库存批量查询 | query | 200 + `code`／`data` 库存数组 | 否 |
| 5810001 | 取消预订 | command | 200 + 业务结果 | 否（同步出结果） |
| 5810023 | 核销状态查询 | query | 200 + 核销状态 | 否 |
| 5810017 | 开始预订 | decision | 保存后 **204** | **是**：答复预订结果 |
| 5810013 | 取消预订审核 | decision | 保存后 **204** | **是**：答复退款审核 |
| 5910003 | 商品流程状态变更 | notification | 204 | 否 |
| 5910049 | 商品上下架状态变更 | notification | 204 | 否 |
| 5810003 | 预订结果同步 | notification | 204 | 否 |
| 5810005 | 用户撤销退款通知 | notification | 204 | 否 |
| 5810031 | 预订核销同步 | notification | 204 | 否 |

只会收到已开通并订阅的事件。同步 `query`／`command` 有连接超时预算（公开说明约 3 秒总预算，以消息里 `data.deadlineAt` 为准）；这是技术超时，不是订单业务期限。`decision` 不提供本地 `deadlineAt`，也不要把最终接单／同意退款写在回调响应体里冒充答复。

**同步响应体协议（必须遵守）：** 最外层只允许 `code`、`message`、`data`；`code` 为整数，成功为 `0`。不要塞 `success`、`msg`、`traceId` 等字段，不要套统一 Result，不要对 query／command 回空 204。HTTP 200 只表示网络层有响应，字段不合规仍会被拒绝。

## 二、商品发布：创建／提交成功 ≠ 可订

订场前通常要先有商品与预订规则。流程是：创建商品 → 提交商品 → 等平台流程／上下架通知。接口成功只表示请求被受理，**不等于审核通过或已上架可售**。

![时序图：开发者→无限聚核→美团创建／提交商品；接口成功不等于审核通过；美团经 5910003 商品流程通知与 5910049 上下架通知签名 Webhook 到开发者](assets/flow-product-publish.png)

*文档站「商品发布与状态通知」流程：5910003／5910049 为 notification，保存后 HTTP 204 即可；上架状态以通知与查询为准，不要用创建接口回包当可售。*

## 三、5810033 库存：同一次回调答完

`5810033` 是 **query**。美团查库存 → 无限聚核打签名 Webhook → 你查本地日期／时段库存 → **在当前 HTTP 响应**返回 `code=0` 与 `data` 数组 → 网关转成美团原生同步响应。

不能：先 204／空 body，再另开接口补库存；不能套异步 `/reply`。连接超时或协议不合规时，C 端常见后果是**时段显示无库存或不可订**。

![时序图：美团 5810033→无限聚核签名 Webhook（query）→开发者查库存→HTTP 200 code=0 data 数组→转换为美团原生同步响应；查询结果必须在当前 HTTP 回调中返回](assets/flow-stock-query.png)

*文档站「库存查询：在同一次回调内应答」。同步 query 以 `data.deadlineAt` 为技术截止；超时不要伪造库存。*

落地要点：

1. 按消息里的商品／日期／时段查可售量，与本地锁场一致；  
2. 严格 `code`／`message`／`data` 三字段；  
3. 商家页打开时的库存可被平台侧缓存，**提交订单还会再查**——两边都要答得对、答得快；  
4. 「场馆实时库存」类主动查询 API 用于校准，不能代替 5810033 回调。

## 四、5810017 开始预订：204 确认 ≠ 接单

`5810017` 是 **decision**。正确两步：

1. 验签 → 持久化 → **HTTP 204**（只确认收到）；  
2. 本地判断能否接单后，另调 **答复预订结果**（请求带 `platform`、`shopId`、`requestId`，`biz.orderId` 取自消息 payload）。

`requestId`／`shopId`／`orderId` 必须来自该条已验签消息，禁止串单。

美团业务枚举（由平台判定）：接单 `biz.bookStatus=2` 且 `biz.code=200`；拒单 `biz.bookStatus=3` 且 `biz.code` 为 `40001`～`40007`。可选 `appOrderId` 作你侧单号。

payload 关键字段常见：`orderId`、`appProductId`、`begintime`、`endtime`、`quantity`（原生小写 `begintime`／`endtime`，与部分通知里的 `beginTime`／`endTime` 不同，不要自行改名）。

![时序图：美团 5810017→无限聚核确认平台接收→签名 Webhook（decision）→开发者 HTTP 2xx→处理接单或拒单→答复预订结果→reply_recorded→提交美团；保存答复与提交美团是两个阶段](assets/flow-booking-accept.png)

*文档站「预订接单：接收确认与业务答复分开」。不要把接单／拒单只写在回调 HTTP 正文里。*

## 五、5810013 退款审核 ≠ 5810001 取消预订

两条容易混：

| 消息 | mode | 你怎么答 |
|---|---|---|
| **5810001** 取消预订 | command | **同一次** HTTP 200 返回实际处理结果 |
| **5810013** 取消预订审核 | decision | 先 204，再另调 **答复退款审核** |

非规则退走 5810013：payload 常见 `orderId`，可能含 `reason`、`type`、`isTieredRefund` 等。答复里 `biz.auditResult=2` 通过、`3` 未通过（枚举交美团判定）。`requestId`／`shopId`／`biz.orderId` 必须来自对应审核消息。

规则退按已同步的预订规则自动处理；非规则退要你审。审核超时未答复时，平台侧**默认拒绝退款**。提交审核答复成功 ≠ 用户已到账。

![时序图：美团 5810013→无限聚核确认→签名 Webhook（decision）→开发者 HTTP 2xx→作出审核决定→答复退款审核→reply_recorded→提交美团；提交审核答复不等于退款到账](assets/flow-refund-audit.png)

*文档站「退款审核：另调审核答复接口」。退前按必接要求处理核销状态查询（5810023）；已核销单不要按未履约退。*

## 六、reply_recorded、completed、unknown

业务答复接口成功时，常见 `data.status=reply_recorded`：只表示消息中心**已保存本次答复**，并会为该次答复建提交任务。

接着用 **查询消息处理状态**（按同一 `requestId`）看最近一次 submission：

| 状态 | 含义 | 你该做什么 |
|---|---|---|
| `reply_recorded` | 答复已落消息中心 | 可查 submission；不要当成用户已预订成功 |
| `completed` | **最近一次**答复已成功提交美团 | 仍不等于历史每次都完成，也不等于订单终态 |
| `unknown` | 最近一次调用结果未知 | **不要自动换幂等键重试**；先核实平台结果再决定 |

写接口（创建商品、答复类等）出现 `data.outcome=unknown` 时，服务端**不会**自动重试；重复提交可能造成重复业务操作。接单／退审同样：204 或 `reply_recorded` 都不是 C 端「预订成功／退款成功」的充分条件，以查单与平台订单为准。

直连写接口（创建／更新／提交商品、同步规则、商家取消、到店核销等）公开说明不按 `Idempotency-Key` 复用结果；`decision` 答复靠正确的 `requestId` 关联消息，而不是靠你方随意换键硬刷。

## 七、联调最小闭环

| 步骤 | 通过标准 |
|---|---|
| 订阅 | 5810033／5810017／5810013 等必接已开；验签通过 |
| 商品 | 创建→提交→能收到 5910003／5910049；可售以通知／查询为准 |
| 库存 | 5810033 同回调 `code=0`+数组；故意超时能复现无库存 |
| 接单 | 5810017 → 204 → 答复 bookStatus 2／3 → 查到 completed |
| 退审 | 5810013 → 204 → 答复 auditResult 2／3；与 5810001 分路 |
| 未知态 | 模拟 unknown后不换键重放；有查单路径 |
| 身份 | `shopId`／授权按门店隔离，禁止串店 |

场馆 SaaS／收银只需把上述状态机嵌进本场地订单：库存与锁场、接单队列、审核超时告警。团购准备／核销／撤销仍走团购接口族，不要抄进预订 Webhook。

## 常见问题

### 5810033 能不能先回 204，再异步把库存推上去？

不能。5810033 是同步 query，库存必须出现在**当次**回调的 HTTP 200 业务 JSON 里。先 204 再补答会被当成失败；超时后 C 端常表现为无库存。

### 5810017 回调里直接返回 bookStatus 算接单成功吗？

不算。decision 回调只需持久化后 HTTP 204；接单／拒单必须另调答复预订结果。只写在回调正文里的业务 JSON 不能代替答复接口。

### reply_recorded 是不是表示预订已经成功？

不是。它只表示答复已写入消息中心。要用查询消息处理状态看最近一次是否 `completed`（已提交美团），再结合订单查询看用户侧是否已预订成功。

### 5810013 和 5810001 有什么区别？

5810001 取消预订是 command，同步在当次响应返回处理结果。5810013 取消预订审核是 decision，先 204，再调答复退款审核。非规则退走后者；不要混用两条链路。

### outcome 或提交状态为 unknown 时要不要自动重试？

不要自动换键重试。unknown 表示结果未知，不等于失败，服务端不会替你重放。先查平台／消息状态，确认未生效再按规范补答，避免重复接单或重复审核提交。

### 商品创建接口 success 了为什么 C 端还是订不了？

创建／提交成功不等于审核通过或上架。要等 5910003／5910049（或查询商品）确认可售，并且 5810033 能返回有效库存、5810017 能完成接单答复。

文中消息号、mode、应答字段与时序摘自无限聚核公开体育馆 API 说明（与文档站流程图一致），美团侧 bookStatus／auditResult 等业务枚举以平台判定为准，查阅日期 2026-11-03。