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

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

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

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

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

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

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

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

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

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

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

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

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

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

落地要点：

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 不同，不要自行改名）。

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

两条容易混：

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

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

六、reply_recorded、completed、unknown

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

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

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

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

七、联调最小闭环

场馆 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。