# 无限聚核开放平台 · 到店餐饮 API 文档

> 22 个开放接口，包含美团与抖音餐饮聚合授权、无限聚核平台的商户、门店、额度、充值能力，以及美团到店餐饮验券和查询能力。

## AI 接入

[AI 接入提示词](https://doc.elys.cn/sdk.md)

请读取 https://doc.elys.cn/sdk.md，并按其中流程帮我接入无限聚核 API。

- 官方页面：https://doc.elys.cn/dining
- API Host：`https://newopen.elys.cn`
- Content-Type：`application/json`
- 成功判断：`code=OP_SUCCESS`

本文档由无限聚核公开 API 的结构化数据自动生成。接入时以当前字段、鉴权、成功判断和风险说明为准，不要猜测未列出的接口或参数。

## 快速接入

配置 Bearer key 后，按平台接口或餐饮原生接口各自的参数表调用。

1. **配置调用身份**：统一发送 `Authorization: Bearer <key>` 和 `Content-Type: application/json`。X-Store-Id 仅用于餐饮验券与查询接口；平台组的建店、额度、充值接口与餐饮授权接口应按各自参数表填写。
2. **完成餐饮门店授权**：调用 `/api/hexiao/v2/dining/storemap/authorize-url`，传系统餐饮子门店 `shopId` 和必填 `platform`（1 美团、2 抖音），由商户打开返回链接完成对应平台授权。原美团餐饮授权接口继续保留。
3. **执行新版预验券**：调用 `/tuangou/ng/coupon/msprepare` 查询券和商品信息，不使用旧版 `/tuangou/coupon/prepare`。
4. **确认后执行新版核销**：只调用 `/tuangou/ng/coupon/msconsume`；该接口会执行真实验券，并按收费配置创建或复用核销订单。相同请求命中已成功订单时返回 10500 已核销提示，不再返回原成功数据。

## 美团合作授权

无限聚核已获得美团技术服务合作授权，为商户提供相关 API 产品服务。

![宁德无限递归网络科技有限公司美团合作授权书](https://cdn.umember.cn/assets/mt_auth.jpg)

美团合作授权书

## 餐饮接口详情

以下 12 个美团到店餐饮业务接口使用 X-Store-Id，平台未知字段可通过原始 JSON 继续透传。

### 已验券码查询

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/queryById`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：根据餐饮团购券码查询已验证团购券详情。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-queryById

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id），不是美团 POI ID

#### JSON Body 参数

- `couponCode`（`string`，必填）：美团券券码

### 验券准备（新）

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/ng/coupon/msprepare`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：调用美团新版餐饮预验券接口，聚合券和商品信息；该接口免费且不创建收费订单。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-ng-coupon-msprepare

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `code`（`string`，选填）：券码
- `version`（`int`，选填）：版本控制：0 不兼容买单核销，1 兼容买单核销；默认值：1；可选值：0（普通券模式）、1（兼容买单核销）

#### 补充说明

- **不要调用旧版 prepare**：旧版 `/tuangou/coupon/prepare` 永久返回 HTTP 403。

### 执行验券（新）

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/ng/coupon/msconsume`
- 在线调试风险：会改变业务状态；调用前必须确认：本次请求会改变业务状态并可能扣减核销额度：确认门店、券码、数量和渠道无误，未传 Idempotency-Key 或 idempotent，并同意立即执行新版餐饮验券。
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：执行真实美团餐饮验券。该接口是餐饮类目中唯一接入无限聚核收费订单体系的接口；首次成功返回美团原生结果，重复请求命中已成功订单时返回 10500 已核销提示。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-ng-coupon-msconsume

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `code`（`string`，必填）：要验证的美团券密码或二维码
- `num`（`int`，必填）：验证数量，允许 1–100；默认值：1
- `extendChannel`（`int`，选填）：扩展核销渠道，默认传 1004；默认值：1004

#### 响应示例

##### 首次核销成功（美团原生结构）

```json
{
  "code": "OP_SUCCESS",
  "msg": "成功",
  "traceId": "dining-consume-first",
  "data": {
    "couponCodes": ["<已脱敏券码>"]
  }
}
```

##### 重复请求命中已成功订单

```json
{
  "success": false,
  "code": 10500,
  "message": "优惠券已于:2026-08-13 20:45:54核销;门店:化大",
  "traceId": "dining-consume-replay",
  "data": null
}
```

#### 补充说明

- **调用方不能提供幂等身份**：不得传 `Idempotency-Key`，JSON 中也不得包含任何大小写变体的 `idempotent`；服务端使用收费订单号生成并管理平台幂等身份。
- **结果未知时使用原请求重试**：不要更换券码、数量、渠道或正文；完全相同的业务请求会复用原收费订单，不重复预占额度。
- **成功回放返回已核销提示**：相同请求命中已成功订单时返回 success=false、code=10500、data=null，message 包含首次成功时间和当前门店名；服务端不会再次调用美团或重复扣费。

### 撤销验券

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/cancel`
- 在线调试风险：会改变业务状态；调用前必须确认：本次请求会改变美团券状态：确认门店、ERP 操作人和券码无误。部分撤销只更新核销明细，整笔订单全部撤销后才返还一次原核销额度。
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：向美团提交餐饮撤销验券。该接口不创建新的收费订单，每次请求都会直接提交美团；仅平台明确成功后更新本地撤销状态，整笔订单全部撤销时返还一次原额度。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-cancel

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `eId`（`string`，必填）：商家登录 ERP 账号 ID，长度不超过 32
- `eName`（`string`，必填）：商家登录 ERP 账号名称，长度不超过 32
- `type`（`int`，必填）：固定传 1，表示撤销验券；默认值：1；可选值：1（撤销验券）
- `couponCode`（`string`，必填）：需要撤销的美团券码

#### 补充说明

- **全部撤销后返还一次额度**：每次请求都会直接提交美团。平台明确撤销成功后才更新原核销明细；同一订单包含多张券时，部分撤销保持原计费，全部成功明细均撤销后才按原扣费来源返还一次额度。平台失败、超时或结果未知时不修改本地订单。

### 门店验券历史

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/queryListByDate`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：查询绑定门店某天在美团技术合作中心的验券历史，limit 建议不超过 200。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-queryListByDate

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `date`（`string`，必填）：查询日期，格式如 2026-08-13
- `offset`（`int`，必填）：查询起始位置，从 0 开始；默认值：0
- `limit`（`int`，必填）：查询条数，建议不超过 200；默认值：10

### 门店本地验券历史

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/queryLocalListByDate`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：查询绑定门店某天经由美团技术合作中心的本地验券历史。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-queryLocalListByDate

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `date`（`string`，必填）：查询日期，格式如 2026-08-13
- `offset`（`int`，必填）：查询起始位置，从 0 开始，最大 999；默认值：0
- `limit`（`int`，必填）：查询条数，最大 999；默认值：10

### 门店套餐映射

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/querySetMealList`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：按套餐状态和商品来源查询线下门店在美团的团购套餐详情。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-querySetMealList

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `dealStatus`（`int`，选填）：套餐状态：-1 全部、0 结束、1 售卖中、2 隐藏、4 未开始、5 不可购买
- `source`（`array`，选填）：商品来源数组：1 商家手动创建，2 秒提上翻团购商品

### 查询团购券交易快照

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/ng/coupon/getCouponPriceInfo`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：按券码查询美团团购券交易价格快照。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-ng-coupon-getCouponPriceInfo

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `code`（`string`，必填）：美团券码

### 查询门店点评

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/review/reviewList`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：查询美团平台指定门店的点评内容。当前美团目录未返回静态字段定义，请按官方文档通过原始 JSON 提交。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/review-reviewList

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

### 查询团购订单结算明细

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/queryTradeDetail`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：按券码查询团购订单结算明细。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-queryTradeDetail

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `couponCode`（`string`，必填）：不超过 12 位的美团券码

### 查询团购订单结算扩展明细

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/ng/coupon/externalProfitDetailRequire`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：按券码和项目 ID 查询团购订单结算扩展明细。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-ng-coupon-externalProfitDetailRequire

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `couponCode`（`string`，必填）：美团券码
- `dealId`（`long`，必填）：美团项目 ID

### 查询团购项目限制条件

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/tuangou/coupon/queryDealAttr`
- 在线调试风险：只读请求
- 授权：统一传 `Authorization: Bearer <key>` 与 `X-Store-Id: <store.id>`。
- 说明：批量查询团购项目的预约、不可用日期、使用时段、叠加张数和限用规则。
- 美团餐饮官方文档：https://developer.meituan.com/docs/api/tuangou-coupon-queryDealAttr

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入
- `X-Store-Id`（`number | string`，必填）：无限聚核系统门店 ID（store.id）

#### JSON Body 参数

- `dealIds`（`string`，必填）：项目 ID 列表，最多 50 个，使用英文逗号分隔

## 无限聚核平台接口

餐饮商户使用聚合授权入口获取美团或抖音链接，并共用无限聚核平台的商户、门店、额度和充值接口；原美团授权入口继续保留。

### 获取餐饮聚合授权链接

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/dining/storemap/authorize-url`
- 在线调试风险：只读请求
- 授权：请求头需携带 `Authorization: Bearer <key>`。
- 说明：为当前账号所属的餐饮子门店生成美团或抖音的完整授权 URL。platform 必填：1 美团、2 抖音；有效业务类目由服务端读取主商户确定。成功 HTTP 201，data 为链接字符串。

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入

#### JSON Body 参数

- `shopId`（`number | string`，必填）：系统餐饮子门店 ID，必须属于当前账号，其有效主商户类别必须为 dining。
- `platform`（`number`，必填）：授权平台：1 美团，2 抖音；必须显式传入，无默认平台。

#### 请求示例

##### 美团餐饮授权

```json
{
  "shopId": 100001,
  "platform": 1
}
```

##### 抖音餐饮授权

```json
{
  "shopId": 100001,
  "platform": 2
}
```

#### 响应字段

- `success`（`boolean`，必填）：是否成功生成授权链接。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明。
- `traceId`（`string | null`，选填）：本次请求链路 ID。
- `data`（`string | null`，必填）：成功时为对应平台的完整授权 URL 字符串；请原样打开，不修改签名参数。

#### 响应示例

##### 成功生成抖音餐饮授权链接（HTTP 201）

```json
{
  "success": true,
  "code": 10000,
  "message": "",
  "traceId": "dining-aggregate-auth",
  "data": "https://auth.dylk.com/auth-isv/?charset=UTF-8&client_key=APP_CLIENT_KEY&extra=OPAQUE&out_shop_id=100001&permission_keys=1%2C16%2C175%2C177%2C180&solution_key=21&timestamp=UNIX_SECONDS&sign=SERVER_SIGNATURE"
}
```

#### 补充说明

- **生成链接不等于授权完成**：商户需打开返回链接完成授权，以平台回调后的授权状态为准。示例地址中的占位值不可直接使用；抖音链接有效期为24小时。
- 这是新增聚合入口，原 `/api/hexiao/v2/meituan/dining/storemap/authorize-url`、`/api/hexiao/v2/meituan/storemap/authorize-url` 和 `/api/hexiao/v2/get/auth/url` 保留原有契约。
- 客户端只传 shopId 与 platform，不传 client_secret、solution_key、permission_keys 或业务类目。餐饮权限配置由服务端管理。
- 本接口免费，不创建核销订单、不扣减额度。授权成功不会自动切换既有核销路由；下方美团餐饮业务接口仍只适用于美团。

### 获取美团餐饮授权链接

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/meituan/dining/storemap/authorize-url`
- 在线调试风险：只读请求
- 授权：请求头需携带 `Authorization: Bearer <key>`。
- 说明：为当前账号所属的系统门店生成美团到店餐饮门店映射授权 URL。商户打开返回链接后，在美团页面完成餐饮门店绑定。

#### Headers

- `Authorization`（`string`，必填）：Bearer <key>，由本文档保存的授权自动注入

#### JSON Body 参数

- `shopId`（`number | string`，必填）：无限聚核系统门店 ID（store.id），门店必须属于当前账号

#### 请求示例

##### 请求示例

```json
{
  "shopId": 123
}
```

#### 响应字段

- `success`（`boolean`，必填）：是否成功生成授权链接。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明。
- `traceId`（`string | null`，选填）：本次请求链路 ID。
- `data`（`string | null`，必填）：美团餐饮门店映射授权 URL；生成失败时为 null。

#### 响应示例

##### 成功生成授权链接

```json
{
  "success": true,
  "code": 10000,
  "message": "",
  "traceId": "dining-storemap-auth",
  "data": "https://open-erp.meituan.com/storemap?sign=example"
}
```

#### 补充说明

- **生成链接不等于授权完成**：调用成功后仍需由商户打开返回链接并完成美团门店绑定；只有美团回调处理成功后，餐饮业务接口才可使用对应门店凭据。
- 该接口免费，不创建核销订单、不扣减核销额度，也不受餐饮核销写开关影响。

### 商户列表

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/merchant/list`
- 在线调试风险：只读请求
- 授权：请求头需携带 Authorization: Bearer <token>。结果只包含当前认证账号拥有的数据。
- 说明：分页查询当前认证账号拥有且未删除的商户。可按商户内部名称、商户 ID 和业务类型筛选；所有筛选条件同时生效。

#### Headers

- `Authorization`（`string`，必填）：Bearer <token>

#### JSON Body 参数

- `name`（`string`，选填）：商户内部名称的字面量子串；服务端先去除首尾空白，空字符串表示不按名称筛选。不会匹配门店名称；显式 null 无效并返回 HTTP 400。
- `masterShopId`（`positive safe integer | decimal integer string`，选填）：商户 ID。支持正安全整数或十进制整数字符串；空白值按未传处理。
- `businessCategory`（`string`，选填）：业务类型。服务端去除首尾空白并转为小写；空字符串表示不筛选，显式 null 无效并返回 HTTP 400。；可选值：service_retail（服务零售）、dining（到店餐饮）
- `page`（`positive safe integer | decimal integer string`，选填）：页码，必须为正安全整数；省略或 null 时使用默认值，空字符串无效。；默认值：1
- `pageSize`（`positive safe integer | decimal integer string`，选填）：每页数量，必须为 1 至 20 的安全整数；省略或 null 时使用默认值，空字符串无效。；默认值：10

#### 请求示例

##### 按名称与业务类型查询

```json
{
  "name": "华东",
  "businessCategory": "service_retail",
  "page": 1,
  "pageSize": 10
}
```

##### 查询当前账号全部商户

```json
{}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明；成功时为 success。
- `traceId`（`string`，必填）：本次请求的链路 ID。
- `data.list`（`array`，必填）：当前页商户列表；没有结果时为 []，不会返回 null。
- `data.list[].shopId`（`number`，必填）：商户的系统 ID。
- `data.list[].masterShopId`（`number`，必填）：商户 ID，与同一对象的 shopId 相等。
- `data.list[].name`（`string`，必填）：商户内部名称；缺失时为 ""。
- `data.list[].businessCategory`（`string`，必填）：规范化后的业务类型。历史空值或无效值按 service_retail 返回。
- `data.list[].childTotal`（`number`，必填）：该商户下当前账号拥有且未删除的门店总数。
- `data.list[].childHasMore`（`boolean`，必填）：childTotal 是否大于 20。
- `data.list[].children`（`array`，必填）：该商户下按固定顺序返回的门店预览，最多 20 条；没有门店时为 []。
- `data.list[].children[].shopId`（`number`，必填）：门店的系统 ID。
- `data.list[].children[].masterShopId`（`number`，必填）：所属商户 ID。
- `data.list[].children[].name`（`string`，必填）：门店内部名称；缺失时为 ""。
- `data.list[].children[].businessCategory`（`string`，必填）：继承所属商户并规范化后的业务类型。
- `data.list[].children[].douyinAuthorized`（`boolean`，必填）：已保存的抖音授权状态；到店餐饮以对应有效餐饮授权记录为准，服务零售沿用当前有效授权路由。
- `data.list[].children[].meituanAuthorized`（`boolean`，必填）：与当前业务类型匹配的已保存美团授权状态。
- `data.list[].children[].meituanName`（`string`，必填）：最新有效美团外部账号名称；缺失时为 ""，授权为 true 时也可能为空。
- `data.list[].children[].douyinName`（`string`，必填）：对应业务类目的最新有效抖音外部账号名称；没有已保存名称时为 ""。
- `data.page`（`number`，必填）：当前页码。
- `data.pageSize`（`number`，必填）：本次请求采用的每页数量。
- `data.total`（`number`，必填）：符合筛选条件的商户总数；超出末页时仍保留该总数。

#### 响应示例

##### 响应示例

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "traceId": "merchant-list-10001",
  "data": {
    "list": [
      {
        "shopId": 1000,
        "masterShopId": 1000,
        "name": "示例商户",
        "businessCategory": "service_retail",
        "childTotal": 21,
        "childHasMore": true,
        "children": [
          {
            "shopId": 1001,
            "masterShopId": 1000,
            "name": "示例门店",
            "businessCategory": "service_retail",
            "douyinAuthorized": true,
            "meituanAuthorized": true,
            "meituanName": "美团示例门店",
            "douyinName": "抖音示例门店"
          }
        ]
      }
    ],
    "page": 1,
    "pageSize": 10,
    "total": 1
  }
}
```

#### 补充说明

- **固定顺序与门店预览**：商户与 children 均按 updated_at DESC, id DESC 排序。每个商户最多预览 20 个当前账号拥有且未删除的门店；预览与同一数据时点、不带 name 和 shopId 筛选的门店列表第 1 页 pageSize=20 一致。空商户也会返回。
- **分页是实时视图**：分页不是导出快照；两次请求之间如有记录更新，记录可能因 updated_at 变化而移动，连续翻页可能出现重复或遗漏。页码和偏移量超出安全整数范围时返回 HTTP 400。
- **严格请求字段**：请求体必须是 JSON 对象，空请求体按 {} 处理。name 或 businessCategory 显式 null、其他字段类型或取值无效、分页范围无效时均返回 HTTP 400；不支持的字段也返回 HTTP 400，包括 sortBy、sortOrder、adminUserId 和 shopId。
- **授权状态含义**：授权字段反映系统已保存的有效授权记录，不是实时可调用性检查。美团按商户业务类型匹配有效授权：service_retail 使用业务码 58，dining 使用业务码 1；service_retail 的抖音状态来自有效门店 Provider 绑定，dining 的抖音状态固定为 false。平台名称取最新有效且非空的授权账号显示名，不保证等同于平台单店名称；授权为 true 时名称仍可能为空。接口不会调用外部平台，也不会返回平台 ID、凭据、Provider 信息、余额或 shopKey。

### 门店列表

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/store/list`
- 在线调试风险：只读请求
- 授权：请求头需携带 Authorization: Bearer <token>。结果只包含当前认证账号拥有的数据。
- 说明：分页查询当前认证账号指定商户下拥有且未删除的门店。masterShopId 必填，可按门店内部名称和门店 ID 筛选；所有筛选条件同时生效。

#### Headers

- `Authorization`（`string`，必填）：Bearer <token>

#### JSON Body 参数

- `masterShopId`（`positive safe integer | decimal integer string`，必填）：商户 ID。支持正安全整数或十进制整数字符串；空白值按未传处理，因此仍会触发必填校验。
- `name`（`string`，选填）：门店内部名称的字面量子串；服务端先去除首尾空白，空字符串表示不按名称筛选，显式 null 无效并返回 HTTP 400。
- `shopId`（`positive safe integer | decimal integer string`，选填）：门店 ID。支持正安全整数或十进制整数字符串；空白值按未传处理。
- `page`（`positive safe integer | decimal integer string`，选填）：页码，必须为正安全整数；省略或 null 时使用默认值，空字符串无效。；默认值：1
- `pageSize`（`positive safe integer | decimal integer string`，选填）：每页数量，必须为 1 至 100 的安全整数；省略或 null 时使用默认值，空字符串无效。；默认值：20

#### 请求示例

##### 查询商户下的门店

```json
{
  "masterShopId": 1000,
  "name": "人民路",
  "page": 1,
  "pageSize": 20
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明；成功时为 success。
- `traceId`（`string`，必填）：本次请求的链路 ID。
- `data.list`（`array`，必填）：当前页门店列表；没有结果时为 []，不会返回 null。
- `data.list[].shopId`（`number`，必填）：门店的系统 ID。
- `data.list[].masterShopId`（`number`，必填）：所属商户 ID。
- `data.list[].name`（`string`，必填）：门店内部名称；缺失时为 ""。
- `data.list[].businessCategory`（`string`，必填）：继承所属商户并规范化后的业务类型。历史空值或无效值按 service_retail 返回。
- `data.list[].douyinAuthorized`（`boolean`，必填）：已保存的抖音授权状态；到店餐饮以对应有效餐饮授权记录为准，服务零售沿用当前有效授权路由。
- `data.list[].meituanAuthorized`（`boolean`，必填）：与当前业务类型匹配的已保存美团授权状态。
- `data.list[].meituanName`（`string`，必填）：最新有效美团外部账号名称；缺失时为 ""，授权为 true 时也可能为空。
- `data.list[].douyinName`（`string`，必填）：对应业务类目的最新有效抖音外部账号名称；没有已保存名称时为 ""。
- `data.page`（`number`，必填）：当前页码。
- `data.pageSize`（`number`，必填）：本次请求采用的每页数量。
- `data.total`（`number`，必填）：符合筛选条件的门店总数；超出末页时仍保留该总数。

#### 响应示例

##### 响应示例

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "traceId": "store-list-10001",
  "data": {
    "list": [
      {
        "shopId": 1001,
        "masterShopId": 1000,
        "name": "示例门店",
        "businessCategory": "service_retail",
        "douyinAuthorized": true,
        "meituanAuthorized": true,
        "meituanName": "美团示例门店",
        "douyinName": "抖音示例门店"
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}
```

##### 指定门店不属于所选商户

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "traceId": "store-list-empty-10001",
  "data": {
    "list": [],
    "page": 1,
    "pageSize": 20,
    "total": 0
  }
}
```

#### 补充说明

- **商户校验**：masterShopId 必须是当前认证账号拥有、未删除且实际为商户的 ID。不可访问、已删除或不是商户时统一返回 HTTP 404 和相同安全提示，不泄露数据是否存在。
- **筛选与固定顺序**：name 只匹配门店内部名称。shopId 不属于所选商户或当前账号时成功返回空列表。结果固定按 updated_at DESC, id DESC 排序；商户列表中的 children 预览使用同一顺序。
- **分页是实时视图**：分页不是导出快照；两次请求之间如有记录更新，记录可能因 updated_at 变化而移动，连续翻页可能出现重复或遗漏。页码和偏移量超出安全整数范围时返回 HTTP 400。
- **严格请求字段**：请求体必须是 JSON 对象，空请求体会因缺少 masterShopId 返回 HTTP 400。name 显式 null、其他字段类型或取值无效、分页范围无效时均返回 HTTP 400；不支持的字段也返回 HTTP 400，包括 businessCategory、sortBy、sortOrder 和 adminUserId。
- **授权状态含义**：授权字段反映系统已保存的有效授权记录，不是实时可调用性检查。美团按商户业务类型匹配有效授权：service_retail 使用业务码 58，dining 使用业务码 1；service_retail 的抖音状态来自有效门店 Provider 绑定，dining 的抖音状态固定为 false。平台名称取最新有效且非空的授权账号显示名，不保证等同于平台单店名称；授权为 true 时名称仍可能为空。接口不会调用外部平台，也不会返回平台 ID、凭据、Provider 信息、余额或 shopKey。

### 创建门店

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/store/create`
- 在线调试风险：会改变业务状态；调用前必须确认：本次请求会改变业务状态：确认名称、商户与门店关系和业务类型无误，并同意创建真实商户或门店。
- 授权：请求头需携带 Authorization: Bearer <token>。
- 说明：不传 masterShopId 时只创建一个商户并返回该商户 ID，不隐式创建首个门店；创建门店时只允许传当前认证账号所属商户 ID。归属始终来自 Authorization 对应的认证身份。

#### Headers

- `Authorization`（`string`，必填）：Bearer <token>

#### JSON Body 参数

- `shopName`（`string`，必填）：商户或门店名称
- `masterShopId`（`number | string`，选填）：创建门店时使用的商户 ID，必须属于当前认证账号。创建商户时不要填写。
- `businessCategory`（`string`，选填）：业务类型，仅创建商户时生效；service_retail 表示服务零售，dining 表示到店餐饮。省略、null 或空白时默认为 service_retail。创建门店时继承所属商户的业务类型，不允许覆盖，门店请求中的该字段会被忽略。；默认值：service_retail；可选值：service_retail（服务零售）、dining（到店餐饮）

#### 请求示例

##### 请求示例（商户）

```json
{
  "shopName": "示例商户",
  "businessCategory": "service_retail"
}
```

##### 请求示例（门店）

```json
{
  "shopName": "示例门店",
  "masterShopId": 123
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明。
- `data.shopId`（`number`，必填）：本次创建并返回的门店 ID。
- `data.name`（`string`，必填）：门店名称。
- `data.shopKey`（`string`，必填）：门店标识。
- `data.providerShopId`（`null`，必填）：Provider 门店 ID；创建商户或门店时均为 null。

#### 响应示例

##### 响应示例

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "data": {
    "shopId": 10001,
    "name": "示例商户",
    "shopKey": "ABCDEF",
    "providerShopId": null
  }
}
```

#### 补充说明

- 不传 masterShopId 时只创建一个商户；传入商户 ID 时创建门店。门店只可归属于当前认证账号所属商户，业务类型始终继承商户。

### 编辑商户或门店

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/store/update`
- 在线调试风险：会改变业务状态；调用前必须确认：本次请求会改变业务状态：确认 shopId 和新名称无误，并同意修改真实商户或门店名称。
- 授权：请求头需携带 Authorization: Bearer <token>。归属和操作权限只根据当前认证身份判断。
- 说明：只修改商户或门店内部名称；目标必须由当前认证账号拥有且未删除，不修改业务类型、商户归属、平台名称或授权状态。

#### Headers

- `Authorization`（`string`，必填）：Bearer <token>

#### JSON Body 参数

- `shopId`（`positive safe integer | decimal integer string`，必填）：当前认证账号内商户或门店的系统 ID，支持正安全整数或十进制整数字符串。
- `shopName`（`string`，必填）：新的内部名称。服务端去除首尾空白后必须为 1 至 20 个 Unicode 字符；null、非字符串、空名称或超长名称均返回 HTTP 400。

#### 请求示例

##### 修改商户或门店名称

```json
{
  "shopId": 10001,
  "shopName": "新名称"
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：修改结果说明；成功时为 修改成功。
- `traceId`（`string`，必填）：本次请求的链路 ID。
- `data.shopId`（`number`，必填）：已修改名称的商户或门店系统 ID。
- `data.name`（`string`，必填）：去除首尾空白后实际保存的新名称。

#### 响应示例

##### 修改成功（HTTP 200）

```json
{
  "success": true,
  "code": 10000,
  "message": "修改成功",
  "traceId": "store-update-10001",
  "data": {
    "shopId": 10001,
    "name": "新名称"
  }
}
```

#### 补充说明

- **名称更新规则**：同名更新成功。门店名称会检查同一商户下其他未删除门店，排除自身后存在同名门店时返回 HTTP 400；商户名称不做全局重复检查，与 Admin 管理逻辑一致。更新会写入 name 和 updated_at，因此下一次列表查询中的排序位置可能变化。
- **严格请求字段**：请求体只接受 shopId 和 shopName，二者均必填。无效 JSON、空名称、shopName 显式 null、非字符串或超过 20 个 Unicode 字符，以及 businessCategory、masterShopId、platform、adminUserId 等未知字段均返回 HTTP 400。
- **账号隔离与副作用**：shopId 不属于当前认证账号、记录已软删除或不存在时统一返回 HTTP 404。接口只修改内部名称，不调用 Provider，不修改或刷新 Redis 路由，不扣费，也不创建 operation。

### 删除商户或门店

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/store/delete`
- 在线调试风险：会改变业务状态；调用前必须确认：本次请求会改变业务状态，软删除真实商户或门店并停用平台路由：确认 shopId 无误、商户下已无未删除门店，并同意执行删除。
- 授权：请求头需携带 Authorization: Bearer <token>。归属和操作权限只根据当前认证身份判断。
- 说明：软删除当前认证账号拥有的商户或门店。删除商户前必须先删除其全部未删除门店，接口不会级联删除。

#### Headers

- `Authorization`（`string`，必填）：Bearer <token>

#### JSON Body 参数

- `shopId`（`positive safe integer | decimal integer string`，必填）：当前认证账号内商户或门店的系统 ID，支持正安全整数或十进制整数字符串。

#### 请求示例

##### 删除商户或门店

```json
{
  "shopId": 10001
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：删除结果说明。
- `traceId`（`string`，必填）：本次请求的链路 ID。
- `data.shopId`（`number`，必填）：已软删除的商户或门店系统 ID。

#### 响应示例

##### 删除成功（HTTP 201）

```json
{
  "success": true,
  "code": 10000,
  "message": "删除成功",
  "traceId": "store-delete-10001",
  "data": {
    "shopId": 10001
  }
}
```

##### 商户下仍有门店（HTTP 400）

```json
{
  "success": false,
  "code": 10001,
  "message": "主门店下存在子门店，请先删除子门店",
  "traceId": "store-delete-10001"
}
```

#### 补充说明

- **商户删除保护**：商户下存在任何未删除门店时返回 HTTP 400，必须先逐一删除门店，不能级联删除。已软删除门店不阻止商户删除。真正删除时会事务锁定商户并再次检查子门店，避免并发创建和删除交错。后端保留错误原文「主门店下存在子门店，请先删除子门店」。
- **请求兼容性**：请求体必须包含有效 shopId；无效 JSON 或无效 ID 返回 HTTP 400。为兼容既有调用，额外字段会被忽略；账号归属仍只取当前 Authorization，任何请求字段都不能指定其他账号。
- **账号隔离与删除副作用**：shopId 不属于当前认证账号、记录已软删除或不存在时统一返回 HTTP 404。删除成功沿用 HTTP 201，记录执行软删除，并停用该商户或门店的美团、抖音平台路由和清理缓存。预校验失败不会清理缓存。

### 查询剩余核销次数

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/quota/query`
- 在线调试风险：只读请求
- 授权：请求头需携带 Authorization: Bearer <token>。
- 说明：按邮箱查询账号级剩余核销次数；传入 shopId 时查询该账号下指定门店的专属剩余次数。

#### Headers

- `Authorization`（`string`，必填）：Bearer <token>

#### JSON Body 参数

- `email`（`string`，必填）：用户邮箱，用于查询账号
- `shopId`（`number | string`，选填）：门店 ID。传入时查询门店专属剩余次数，不传时查询账号级剩余次数

#### 请求示例

##### 账号级请求示例

```json
{
  "email": "test@example.com"
}
```

##### 门店级请求示例

```json
{
  "email": "test@example.com",
  "shopId": 8673891
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明。
- `data.source`（`"admin" | "store"`，必填）：额度来源；admin 为账号级，store 为门店级。
- `data.email`（`string`，必填）：被查询账号的邮箱。
- `data.shop_id`（`number | null`，必填）：系统门店 ID；账号级查询时为 null。当前响应字段使用 snake_case。
- `data.remaining_count`（`number`，必填）：剩余可核销次数。

#### 响应示例

##### 账号级响应示例

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "data": {
    "source": "admin",
    "email": "test@example.com",
    "shopId": null,
    "remaining_count": 88
  }
}
```

##### 门店级响应示例

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "data": {
    "source": "store",
    "email": "test@example.com",
    "shopId": 8673891,
    "remaining_count": 12
  }
}
```

##### 错误响应示例

```json
{
  "success": false,
  "code": 10001,
  "message": "email 必填"
}
```

#### 补充说明

- 常见错误信息：email 必填、账号不存在、shopId 格式错误、门店不存在。

### 查询可充值金额

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/recharge/plans`
- 在线调试风险：只读请求
- 授权：请求头需携带登录接口签发的 Authorization: Bearer <V2 JWT>。
- 说明：查询当前账号或所属商户可购买的充值档位。shopId 省略或传 0 时查询主账户档位；传大于 0 的系统门店 ID 时查询该商户档位。

#### Headers

- `Authorization`（`string`，必填）：Bearer <V2 JWT>，由 V2 登录接口签发

#### JSON Body 参数

- `shopId`（`number`，选填）：无限聚核系统商户 ID（store.id）；省略或传 0 表示当前管理员主账户，大于 0 时必须属于当前账号且未删除；默认值：0

#### 请求示例

##### 查询主账户充值档位

```json
{
  "shopId": 0
}
```

##### 查询门店充值档位

```json
{
  "shopId": 8673891
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明。
- `traceId`（`string`，必填）：本次请求链路 ID，排查问题时请一并提供。
- `data.shopId`（`number`，必填）：本次查询的充值目标；0 表示当前管理员主账户。
- `data.unitPriceFen`（`number`，必填）：当前档位组的单次核销价格，单位为分。
- `data.unitPrice`（`number`，必填）：当前档位组的单次核销价格，单位为元。
- `data.pricingMode`（`number`，必填）：当前档位组计价模式：1 为历史账号倍率，2 为固定单价。
- `data.plans`（`object[]`，必填）：可购买充值档位列表，仅返回金额不低于 100 元且配置有效的档位。
- `data.plans[].id`（`number`，必填）：充值档位 ID，创建订单时作为 rechargePlanId 原样传入。
- `data.plans[].rechargeAmountFen`（`number`，必填）：充值金额，单位为分。
- `data.plans[].rechargeAmount`（`number`，必填）：充值金额，单位为元。
- `data.plans[].unitPriceFen`（`number`，必填）：该档位单次核销价格，单位为分。
- `data.plans[].unitPrice`（`number`，必填）：该档位单次核销价格，单位为元。
- `data.plans[].pricingMode`（`number`，必填）：该档位计价模式：1 为历史账号倍率，2 为固定单价。
- `data.plans[].buyCount`（`number`，必填）：支付成功后增加的可核销次数。
- `data.plans[].sortOrder`（`number`，必填）：档位展示顺序，数值越小越靠前。

#### 响应示例

##### 查询成功

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "traceId": "recharge-plans-trace",
  "data": {
    "shopId": 8673891,
    "unitPriceFen": 15,
    "unitPrice": 0.15,
    "pricingMode": 2,
    "plans": [
      {
        "id": 42,
        "rechargeAmountFen": 30000,
        "rechargeAmount": 300,
        "unitPriceFen": 15,
        "unitPrice": 0.15,
        "pricingMode": 2,
        "buyCount": 2000,
        "sortOrder": 1
      }
    ]
  }
}
```

##### 门店无权限

```json
{
  "success": false,
  "code": 10001,
  "message": "门店不存在或无权限",
  "traceId": "recharge-plans-trace",
  "data": null
}
```

#### 补充说明

- **先查询再创建订单**：充值金额和次数以后端返回档位为准。调用方应保存用户选择的 data.plans[].id，并在创建订单时作为 rechargePlanId 传入。
- **常见错误**：HTTP 400 通常表示 shopId 类型或取值错误；HTTP 403 表示账号状态异常；HTTP 404 表示门店不存在或无权限；HTTP 500 表示充值数据暂时不可用。失败时 data 为 null。

### 创建充值订单

- 方法：`POST`
- URL：`https://newopen.elys.cn/api/hexiao/v2/recharge/order/create`
- 在线调试风险：会改变业务状态；调用前必须确认：本次请求会改变业务状态并创建一笔 30 分钟有效的真实待支付订单：确认 shopId 与 rechargePlanId 来自同一次档位查询，并同意创建订单。
- 授权：请求头需携带登录接口签发的 Authorization: Bearer <V2 JWT>。
- 说明：按查询接口返回的充值档位创建 30 分钟有效的待支付订单，并返回可渲染为二维码的 wxPayQrCodeUrl。本接口只创建订单，不直接调用微信支付。

#### Headers

- `Authorization`（`string`，必填）：Bearer <V2 JWT>，由 V2 登录接口签发

#### JSON Body 参数

- `shopId`（`number`，选填）：无限聚核系统商户 ID（store.id）；省略或传 0 表示当前管理员主账户，必须与查询充值档位时的目标一致；默认值：0
- `rechargePlanId`（`number`，必填）：充值档位 ID，必须取自同一 shopId 调用查询可充值金额接口返回的 data.plans[].id

#### 请求示例

##### 创建主账户充值订单

```json
{
  "shopId": 0,
  "rechargePlanId": 42
}
```

##### 创建门店充值订单

```json
{
  "shopId": 8673891,
  "rechargePlanId": 42
}
```

#### 响应字段

- `success`（`boolean`，必填）：业务是否成功；调用方应以该字段作为成功判断依据。
- `code`（`number`，必填）：统一业务码；成功时为 10000。
- `message`（`string`，必填）：业务结果说明。
- `traceId`（`string`，必填）：本次请求链路 ID，排查问题时请一并提供。
- `data.orderNo`（`string`，必填）：充值订单号。订单默认 30 分钟有效，支付和查询时应保持原值。
- `data.rechargeAmountFen`（`number`，必填）：订单充值金额，单位为分。
- `data.buyCount`（`number`，必填）：支付成功后增加的可核销次数。
- `data.wxPayQrCodeUrl`（`string`，必填）：现有小程序充值页 startapp 链接。调用方应把完整 URL 原样渲染成二维码，不能修改其中的 orderNo。

#### 响应示例

##### 订单创建成功

```json
{
  "success": true,
  "code": 10000,
  "message": "success",
  "traceId": "recharge-order-trace",
  "data": {
    "orderNo": "C17202608201530001235",
    "rechargeAmountFen": 30000,
    "buyCount": 2000,
    "wxPayQrCodeUrl": "https://hx.umember.cn/startapp?path=recharge&channel=scan&orderNo=C17202608201530001235"
  }
}
```

##### 充值档位不存在

```json
{
  "success": false,
  "code": 10001,
  "message": "充值档位不存在",
  "traceId": "recharge-order-trace",
  "data": null
}
```

#### 补充说明

- **完整支付与到账链路**：服务端创建待支付订单并返回 wxPayQrCodeUrl → 调用方把完整 URL 渲染为二维码 → 用户扫码进入现有微信小程序充值页并完成支付 → 现有支付回调处理订单并自动把 buyCount 对应次数充入目标主账户或门店。本接口不接入微信支付证书、私钥或支付回调。
- **二维码与订单有效期**：必须对 wxPayQrCodeUrl 完整字符串编码生成二维码，不要自行拼接或替换 orderNo。订单创建后 30 分钟内未支付会失效，失效后应重新查询档位并创建新订单。
- **常见错误**：HTTP 400 通常表示 shopId/rechargePlanId 类型或档位配置错误；HTTP 403 表示账号状态异常；HTTP 404 表示门店无权限或充值档位不存在；HTTP 500 表示订单创建或充值数据暂时不可用。失败时 data 为 null。

## 技术支持

扫码添加微信，获取餐饮接口接入帮助