# 美团棋牌一品多态 API｜无限聚核
> 棋牌包型包间、团购关联、库存、预订核销、退款代理与消息通知。
## AI 接入
[AI 接入提示词](https://doc.elys.cn/chess-sdk.md)
请读取 https://doc.elys.cn/chess-sdk.md，并按其中流程帮我接入无限聚核棋牌一品多态 API。
## 接入说明
开发版本：平台字段与实际权限需联调确认，服务发布后方可使用。
- 官方页面：https://doc.elys.cn/chess
- API Host：`https://newopen.elys.cn`
- Content-Type：`application/json`
- 成功判断：`检查 success 和 data.outcome；platformResponse 保留本次美团返回，受理成功不等于审核、退款完成。`
本文档由无限聚核公开 API 的结构化数据自动生成。接入时以当前字段、鉴权、成功判断和风险说明为准，不要猜测未列出的接口或参数。
## 美团合作授权
无限聚核已获得美团技术服务合作授权，为商户提供相关 API 产品服务。
美团合作授权书
## 开发者接入流程
### 接口与消息全流程
实线为 API 调用或业务处理；Webhook 节点标注应答方式。
```mermaid
sequenceDiagram
participant D as 开发者
participant P as 聚核代理 / MC
participant M as 美团
participant L as 门禁 / 店长
D->>P: API 规则 → 包型包间
P->>M: 原生接口转发
M-->>P: 5810162 包型结果
P-->>D: notification / ACK
D->>P: API 团购查询 → 关联包间 → 可订信息 → 库存 → 升级查询
M-->>P: 5810017 开始预订
P-->>D: decision / 保存并 ACK
D->>D: 分配包间 / 建单
D->>P: API bookresultcallback（extMap 字符串）
P->>M: 原样转发
M-->>P: 5810003 预订同步
P-->>D: notification / ACK
M-->>P: 5810027 设备启动
P-->>D: command / unifiedOrderId
D->>L: 执行真实开门
L-->>D: 设备结果
D-->>P: 同步 data={} 或 businessCode/businessMsg
P-->>M: 同步开门结果
D->>P: API isvconsume / 预占额度
P->>M: 核销（每次调用都转发）
M-->>P: 当次核销结果
P-->>D: outcome + platformResponse
M-->>P: 5810031 核销同步
P-->>D: notification / ACK，不新增收费
alt 用户退款状态查询
M-->>P: 5810023
P-->>D: query
D-->>P: 同步 orderId + consumeStatus
P-->>M: 同步查询应答
else 人工退款审核
M-->>P: 5810013
P-->>D: decision / 保存并 ACK
D->>L: 等待店长审核
L-->>D: 同意或拒绝
D->>P: API refundauditresult
P->>M: 原样转发
else 用户撤回退款
M-->>P: 5810005
P-->>D: notification / 撤销待审并 ACK
else 商家主动退款
D->>P: API merchantapply/refund 或 multirefund
P->>M: 申请退款
M-->>P: 5810165 审核意见
P-->>D: notification / ACK
D->>P: API query/order 核实退款结果
end
M-->>P: 5810001 取消预订
P-->>D: command / 处理取消并释放资源
D-->>P: 同步 data={orderId}
P-->>M: 同步取消应答
D->>P: API updatestock 更新占用
```
## 请求、响应与计费
### 一对一代理
全部为 POST /api/v2/yuding/chess/，对应 /ddzh/yuding/ 同后缀。鉴权通过且计费允许的每次调用都转发，平台决定重复调用是否生效；平台不承诺所有接口幂等。无需额外请求防重标识。
biz 原样传递，不要传签名、凭据或外部账号路由参数。长整数请使用无损 JSON 序列化；保持美团要求的字段类型，extMap 等 JSON 字符串不能变成对象。
success=true 与 outcome=succeeded 表示本次接口明确成功；rejected 为明确拒绝，not_submitted 为确定未提交，unknown 为结果未知。不能仅看 HTTP 200，也不能把异步受理当成审核/退款完成。unknown 先查单，不自动重试写请求。
### 计费边界
仅 isvconsume 计费；首次核销转发前预占 1 次，余额不足 QUOTA_EXHAUSTED 且不转发。共用现有计费订单、额度及流水，棋牌与体育馆相同账号/美团订单共用计费身份。
同周期重复请求不重复预占，仍返回当次平台结果。unknown 保留预占，后续重复拒绝不能误退此前成功或未知扣点。原预占已释放或费用已退回后再核销，按后继计费订单处理。
明确商家取消成功沿用原核销退点；审核同意、申请受理、5810165 和部分退款均不自动退点。开门和消息不计费；门已开但核销失败仍应如实返回设备成功。
### 官方文档与字段类型
业务流程以美团[棋牌一品多态对接方案](https://developer.meituan.com/docs/biz/biz_ddzh_20d841fe-d16e-4896-9629-1fed8f1ca200)为参考，各接口的“接口说明”页签链接到对应官方接口。Body 图形表单和下方示例已按官方业务参数列出嵌套字段。
官方 long 在字段表中标为 integer (int64)，string 订单号须保留引号。大于 JavaScript 安全整数的 long 值应由服务端无损序列化；不要把 long 一律改为字符串，也不要先转换为 JavaScript Number。
extMap 是包含 JSON 内容的字符串；properties 中的 attrValue 也必须是字符串，数组属性需先编码为 JSON 字符串。字段的条件必填要求见说明，具体业务校验由美团执行。
### 可订时段
推送团购可订信息时，进场模式（timeSelectType=2）下每一段在美团单独显示成一行“X–Y内开场”，并在团购关联的每个包间下各列一次。全天可订只推一段 00:00–00:00；有营业时间时写成一段，如跨天 10:00–02:00。
不要为了让顾客按小时或半小时选择而把开放时间切成多段：全天按半小时切成 48 段，同一团购就会在每个包间下重复出现 48 行。顾客下单时再选具体开场时间，使用时长由团购决定。
每个团购分别推送可订信息；推送成功后在美团 App 门店页核对展示。
### 库存与异常恢复
库存按未来 15 天完整占用推送；跨天按北京时间自然日拆分，开始向下、结束向上取整到半小时，并合并重叠。整天空闲也要发 0/0 清空条目，不能简单省略；所有会影响可订库存的本地渠道下单、支付、取消、结束、续时、维修及门店上下线都应重新推送。保洁是否占用由商家业务规则决定；若保洁可预约，不得把保洁时段作为不可订库存。
订单查询 platformResponse.data 中已确认 receipts[].receiptStatus：1 未使用、2 已使用、4 未核销退款、6 已核销退款。混合、空数组、缺失或未知状态都不能推断整单退款成功。amount 出现在原生结果中，但此查询的金额类型和单位尚未完整核实，不用于自动退款金额计算。预订消息 amount 则是元字符串。
无法核实的结果保持 unknown，保留占房或待处理任务并交人工核查；不能因查询失败或空数据释放资源、重试核销、回补额度。商户主动退款受理、审核意见和最终退款状态独立记录。
## 消息与应答
### 门店配置与签名
在管理端 /bot-notify 的棋牌 Tab 按门店配置一个 HTTPS URL；消息清单由基础配置决定，仅展示。新增 5810165 后，存量门店需显式保存以合入默认消息；发布时须确认连接允许列表也支持该消息。
外层 eventId,event,version,occurredAt,data；event=merchant.platform.message，version=1.0。data 包含 requestId、traceId、platform、businessId、msgType、mode、shopId、userId、payload 及按实际消息出现的 deadlineAt；payload 保留原文。
校验 X-Webhook-Account、X-Event-Id、X-Event-Timestamp，签名 X-Event-Signature=v1=。decision/notification 的 2xx 只表示收到。
query/command 同步返回 {"code":0,"message":"success","data":{...}}；data 不用 null。5810001 必须含 orderId；5810027 业务拒绝仍用外层 code=0，业务码放 data.businessCode（7/336/337/338/999）。
5810027 通常约 3 秒应答，按实际 deadlineAt；慢核销等工作由开发者可靠队列处理，不能阻塞开门应答。同单再次合法点击仍应执行开门。
接单、退款审核直接调棋牌 API，无需通过 MC /reply 重复提交。直接回调成功后平台尽力收敛 MC 技术待答复状态；状态同步失败不改变已取得的美团结果，也不重发业务。
### 10 类消息
| msgType | 模式 | 处理 / 应答 |
| --- | --- | --- |
| 5810162 | notification | 包型包间结果：ACK；更新逐项结果。 |
| 5810017 | decision | 保存并 ACK；分配包间后调用预订结果回调。 |
| 5810003 | notification | ACK；同步本地预订结果。 |
| 5810023 | query | 同步 data={orderId,consumeStatus}，1 未核销、2 已核销、3 未知。 |
| 5810013 | decision | 保存并 ACK；等店长审核后调用审核结果，不设本地短期限。 |
| 5810001 | command | 完成本地取消/释放资源，同步 data={orderId}，不能仅回空对象。 |
| 5810027 | command | 用 unifiedOrderId 执行真实开门；成功 data={}，业务拒绝 data={businessCode,businessMsg}。同单可多次合法开门。 |
| 5810031 | notification | ACK；同步核销状态，不新增收费。 |
| 5810005 | notification | ACK；撤销退款待审状态，保留已核销等事实。 |
| 5810165 | notification | ACK；auditResult=true/false 为审核意见，reason 为原因，不等于退款到账。 |
### 协议依据与兼容边界
以下 payload 字段依据 2026-11-06 棋牌联调说明，并与消息中心当前透传、签名及应答实现核对。示例均为虚构数据。平台消息不会被转换成聚核订单 DTO，未知字段须保留；商户实际能力仍需联调。
历史直连说明中的 Idempotency 请求头、外部 POI 作为 shopId、原生回包 data 字符串不适用于本代理：外层 shopId 是聚核内部门店 ID，API 不要求防重标识，Webhook 应答 data 使用对象。不得把其他业态的查询字段混入棋牌。
续时按新增的后续时段占库存，不能把原时段再次占用。回调已提供有效起止时间和候选包间时，按该时段校验、占用并推送最新库存；未确认的续时建单字段（例如主单关联字段名）原样保存，不能猜测关系。只有缺少必要时段或包间信息的部分转人工核实。已知的 subOrderIds 仅用于退款关联，不能据此推导续时建单协议。
### 回调地址验证
保存新 URL 前会收到 event=webhook.endpoint.verification，仍使用五字段外层、相同签名和账号头。验签通过后仅返回 {"challenge":"原样的 data.challenge"}。它没有业务 shopId、msgType 或订单，不进入业务处理。X-Event-Timestamp 是 Unix 秒，接收端检查时钟偏差（建议 300 秒）并核对 X-Event-Id 与 eventId、data.requestId。
X-Webhook-Account 对应配置账号邮箱；业务 data.userId、data.shopId 绑定聚核账号与内部门店，必须与本地绑定一起校验，不能仅按 payload 的 opBizCode 或房间 ID 路由。签名计算使用原始字节，不能重新序列化。重复投递以 eventId 防重复副作用；同一订单的新开门事件必须重新执行。
### 完整消息信封与同步回包
#### 已验签的预订消息（虚构示例）
```json
{
"eventId": "mc_example_001",
"event": "merchant.platform.message",
"version": "1.0",
"occurredAt": "2026-12-01T00:00:00Z",
"data": {
"requestId": "mc_example_001",
"traceId": "trace_example",
"platform": "meituan",
"businessId": "58",
"msgType": "5810017",
"mode": "decision",
"shopId": 100001,
"userId": 100002,
"payload": {
"orderId": "1234567890123456789",
"appProductId": "[100101,100102]",
"begintime": "2026-12-01 10:00",
"endtime": "2026-12-01 14:00",
"duration": "240",
"products": "[{\"quantity\":1,\"product_id\":100201,\"product_name\":\"无套餐\"}]",
"amount": "39.90",
"quantity": "1",
"bizType": "1"
}
}
}
```
#### 核销状态查询应答
```json
{
"code": 0,
"message": "success",
"data": {
"orderId": "1234567890123456789",
"consumeStatus": 2
}
}
```
#### 取消完成应答
```json
{
"code": 0,
"message": "success",
"data": {
"orderId": "1234567890123456789"
}
}
```
#### 设备问题应答
```json
{
"code": 0,
"message": "success",
"data": {
"businessCode": 338,
"businessMsg": "设备未确认执行，请联系商家"
}
}
```
### 5810017 payload 字段
orderId 是字符串；appProductId 是候选包间 ID 数组的 JSON 字符串，内部整数无损解析。begintime/endtime 全小写，北京时间 yyyy-MM-dd HH:mm；duration 为分钟字符串，amount 为元字符串。products 是 JSON 数组字符串，product_id 为团购 ID；mobile/userName 为可选用户资料，不可将脱敏手机号当作登录身份。先持久保存，再分配本店候选空闲包间、占房并回调；冲突拒单 code=40006，extMap 首次接单就带齐。
### 5810017 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789",
"appProductId": "[100101,100102]",
"begintime": "2026-12-01 10:00",
"endtime": "2026-12-01 14:00",
"duration": "240",
"products": "[{\"quantity\":1,\"product_id\":100201,\"product_name\":\"无套餐\"}]",
"amount": "39.90",
"quantity": "1",
"bizType": "1"
}
```
### 5810003 payload 字段
beginTime/endTime 使用驼峰，bookStatus 字符串 2 成功、3 失败。仅同步预订事实，不能覆盖已取消终态或把预订成功当作已核销。
### 5810003 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789",
"beginTime": "2026-12-01 10:00",
"endTime": "2026-12-01 14:00",
"bookStatus": "2",
"amount": "39.90"
}
```
### 5810023 payload 字段
同步返回 orderId 与整数 consumeStatus：1 未核销、2 已核销、3 未知；退款待审不抹除既有核销事实。
### 5810023 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789"
}
```
### 5810013 payload 字段
orderId/reason/type 为字符串；subOrderIds 为存在续时时的订单号数组。isTieredRefund 可能出现，但当前资料未确认类型，不推断。持久保存待审并 ACK；人工审核通过 API 回调，不因等待时间长或已经核销自动拒绝。
### 5810013 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789",
"reason": "计划有变",
"type": "1",
"subOrderIds": [
"1234567890123456790"
]
}
```
### 5810001 payload 字段
orderId、cancelType、auditChannel、reason、type 保留原始字符串。完成本地取消、释放资源，记录平台取消事实并更新库存，不在开发者系统重复调用微信退款。重复取消返回相同订单号；未收到的旧订单也要留终态，防止乱序预订重建。
### 5810001 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789",
"cancelType": "2",
"auditChannel": "2",
"reason": "用户取消",
"type": "1"
}
```
### 5810005 payload 字段
撤销待审状态，保留已核销、已取消等独立事实；不能把已取消单恢复成可开门。
### 5810005 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789"
}
```
### 5810031 payload 字段
verifyStatus 字符串 2 表示已核销；verifyChannel 字符串 3 为三方核销；可能有 serialNumber 流水号，留存时按敏感信息管理，不进入普通日志。不再调用核销或扣费。
### 5810031 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789",
"verifyStatus": "2",
"verifyChannel": "3",
"type": "1"
}
```
### 5810027 payload 字段
unifiedOrderId 是预订单号，不是本地订单 ID。校验门店、订单、允许开门时段及房间占用；提前开门分钟数由商户策略决定，不能把联调门店 30 分钟当平台规定。成功 data={}；7 过早、336 房间占用、337 非营业时间、338 设备问题或超时、999 其他业务失败。MQTT 发布成功不能证明设备执行成功，应有设备执行回执；未知结果不得报告成功。开门成功后可靠排队核销，核销不阻塞约 3 秒应答。
### 5810027 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"unifiedOrderId": "1234567890123456789"
}
```
### 5810162 payload 字段
逐项记录 roomTypeCode 字符串、roomCodeList 整数数组、success 布尔和 errMsg；API 受理成功不代表逐项同步或平台审核成功。
### 5810162 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"roomSyncResultList": [
{
"roomTypeCode": "type-001",
"roomCodeList": [
100101,
100102
],
"success": true,
"errMsg": ""
}
]
}
```
### 5810165 payload 字段
auditResult 为布尔审核意见，reason 为原因。orderId 可能为字符串或原生 long，需无损解析保存，不经浮点数。该通知不是最终退款完成或退点凭据。
### 5810165 payload 示例
#### 美团 payload（外层信封同上）
```json
{
"orderId": "1234567890123456789",
"auditResult": true,
"reason": ""
}
```
## 棋牌代理接口
### 推送门店预订规则
- 方法：`POST`
- URL：`https://newopen.elys.cn/api/v2/yuding/chess/resource/shoprule/booking`
- 在线调试风险：会改变业务状态；调用前必须确认：确认已核实门店、参数及真实业务影响。
- 授权：Authorization: Bearer 。
- 说明：同步门店的接单、预约和退款规则；阶梯退款与提前退订分钟数需配套设置。
- 美团官方文档：https://developer.meituan.com/docs/api/ddzh-yuding-resource-shoprule-booking
#### JSON Body 参数
- `platform`（`string`，必填）：固定 meituan。；默认值：meituan
- `shopId`（`string`，必填）：无限聚核内部门店 ID，须属于当前账号。不是美团 POI。
- `biz`（`object`，必填）：美团业务参数；公共鉴权与签名由服务端处理。请保持下列字段的类型和条件必填约束。
- `acceptType`（`integer`，必填）：接单方式：1 自动接单，2 人工接单。；可选值：1（自动接单）、2（人工接单）
- `notifyPhone`（`string`，选填）：接收接单提醒的手机号。
- `acceptOrderPeriod`（`string`，选填）：可接单的时间范围，格式为 HH:mm,HH:mm；省略时不限制接单时段。
- `addOrderBefore`（`integer`，选填）：提前多少分钟可预订，允许 0～120。
- `refundBefore`（`integer`，必填）：允许直接退订的提前分钟数，可填 60、30 或 0；阶梯退款仅允许 60。；可选值：60（提前 60 分钟）、30（提前 30 分钟）、0（开始前）
- `refundType`（`string`，选填）：退款规则：fullRefund 为全额退款，tieredRefund 为阶梯退款；阶梯退款需同时设置 refundBefore=60。；可选值：fullRefund（全额退款）、tieredRefund（阶梯退款）
#### 请求示例
##### 结构示例，ID、图片和时间请替换为实际业务值
```json
{
"platform": "meituan",
"shopId": "100001",
"biz": {
"acceptType": 1,
"acceptOrderPeriod": "00:00,00:00",
"addOrderBefore": 30,
"refundBefore": 60,
"refundType": "fullRefund"
}
}
```
#### 响应示例
##### 转发成功（平台业务结果仅为示例）
```json
{"success": true, "code": 10000, "message": "", "traceId": "trace-example", "data": {"outcome": "succeeded", "platformResponse": {"code": "OP_SUCCESS", "data": {}}}}
```
### 推送包型包间
- 方法：`POST`
- URL：`https://newopen.elys.cn/api/v2/yuding/chess/resource/room/sync`
- 在线调试风险：会改变业务状态；调用前必须确认：确认已核实门店、参数及真实业务影响。
- 授权：Authorization: Bearer 。
- 说明：异步同步包型及包间；创建省略 roomTypeId，更新提供该 ID。真实逐项结果通过 5810162 消息返回。
- 美团官方文档：https://developer.meituan.com/docs/api/ddzh-yuding-resource-room-sync
#### JSON Body 参数
- `platform`（`string`，必填）：固定 meituan。；默认值：meituan
- `shopId`（`string`，必填）：无限聚核内部门店 ID，须属于当前账号。不是美团 POI。
- `biz`（`object`，必填）：美团业务参数；公共鉴权与签名由服务端处理。请保持下列字段的类型和条件必填约束。
- `roomInfoList`（`array