feiqiu-ETL/非球接口API.md at main

root/feiqiu-ETL

Template

Fork 0

Files

Neo a6ad343092 ODS 完成

2025-11-30 07:19:05 +08:00

32 KiB

Raw Permalink Blame History

1. 总体概览

1.1 服务地址与版本

Base URL（统一前缀）： https://pc.ficoo.vip/apiprod/admin/v1
所有接口路径均在该前缀下，例如：
- 助教流水：/AssistantPerformance/GetOrderAssistantDetails
- 门店商品档案1：/TenantGoods/GetGoodsInventoryList

统一完整 URL 形式：

https://pc.ficoo.vip/apiprod/admin/v1{path}

例如：

https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails

1.2 认证方式

认证方式：Bearer Token（JWT）
HTTP Header：
```
Authorization: Bearer {access_token}
```
Token 获取方式：由 Ficoo 系统颁发（脚本目前通过环境变量 FICOO_TOKEN 或命令行 --token 传入）。
注意：
- Token 为敏感信息，不要写死在代码仓库或文档中。通过CLI或.env配置。
- 示例中出现的实际 JWT 请在内部全部替换成占位符。

1.3 请求方式与编码

HTTP Method：目前脚本全部使用 POST。
请求体：Content-Type: application/json，JSON 编码，UTF-8。
响应体：JSON，UTF-8。

示例（来自现有 curl，经脱敏后）：

curl "https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/plain, */*" \
  --data-raw '{
    "siteId": 2790685415443269,
    "startTime": "2025-11-01 08:00:00",
    "endTime":   "2025-11-08 08:00:00",
    "IsConfirm": 2,
    "page": 1,
    "limit": 20
  }'

1.4 通用 Header 建议（必须）

所有接口均为内部管理后台接口，调用时必须携带以下核心请求头：

Header 名称示例值说明 Authorization Bearer <access_token> 鉴权，使用 Bearer Token Content-Type application/json 请求体为 JSON 编码 Accept application/json, text/plain, / 客户端期望接收 JSON 响应

注意：<access_token> 为系统颁发的 JWT，文档和示例中一律使用占位符，不要写实际 token。

1.4.2 浏览器兼容性请求头（建议统一保留）

为降低前置网关 / 安全策略的拦截风险，系统当前前端及采集脚本在调用接口时，统一携带一组“浏览器兼容性请求头”，用于模拟真实浏览器环境。这些头部对业务语义无强制要求，但推荐所有客户端统一保留：

Header 名称示例值（仅示意）说明 Origin https://pc.ficoo.vip 请求来源域名，前端浏览器自动携带 Referer https://pc.ficoo.vip/ 页面来源地址 User-Agent Mozilla/5.0 (Windows NT 10.0; Win64; x64)... Chrome/141.0.0.0 Safari/537.36 模拟 Chrome 浏览器 UA Accept-Language zh-CN,zh;q=0.9 语言偏好 sec-ch-ua "Google Chrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141" 浏览器 User-Agent Client Hints sec-ch-ua-platform "Windows" 同上，标识操作系统平台 sec-ch-ua-mobile ?0 同上，标识是否移动端 sec-fetch-site same-origin Fetch Metadata，标识请求来源站点关系 sec-fetch-mode cors Fetch Metadata，标识跨域模式 sec-fetch-dest empty Fetch Metadata，标识资源类型 priority u=1, i HTTP 优先级提示，用于底层网络调度 X-Requested-With XMLHttpRequest 传统 AJAX 头部，部分后端可能用来识别异步请求 DNT（可选） 1 Do Not Track，浏览器隐私偏好，业务逻辑不依赖

1.4.3 示例请求头（推荐组合）

下面是一个推荐的完整请求头示例，供客户端实现参考（已脱敏）：

POST /apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails HTTP/1.1 Host: pc.ficoo.vip Authorization: Bearer <access_token> Content-Type: application/json Accept: application/json, text/plain, / Origin: https://pc.ficoo.vip Referer: https://pc.ficoo.vip/ User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)... Chrome/141.0.0.0 Safari/537.36 Accept-Language: zh-CN,zh;q=0.9 sec-ch-ua: "Google Chrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141" sec-ch-ua-platform: "Windows" sec-ch-ua-mobile: ?0 sec-fetch-site: same-origin sec-fetch-mode: cors sec-fetch-dest: empty priority: u=1, i X-Requested-With: XMLHttpRequest DNT: 1

2. 通用协议约定

2.1 时间格式与时区

脚本中所有时间字段使用统一字符串格式：

"YYYY-MM-DD HH:MM:SS"
例如："2025-10-01 00:00:00"

常见时间字段：

startTime / endTime：一般为创建时间或业务发生时间段
rangeStartTime / rangeEndTime：多用于结账记录等“区间查询”
StartPayTime / EndPayTime：支付时间范围（支付流水）

时区未在响应中显式标识，默认可按北京时间（Asia/Shanghai）处理。

2.2 分页约定

通用分页参数：
- page：页码，从 1 开始
- limit：每页条数，例如 20 或 100

Python 脚本支持配置：

PAGE_START = 1
PAGE_END   = 2
PAGE_LIMIT = 100
``` :contentReference[oaicite:7]{index=7}

采集策略：遍历 page 从 PAGE_START 到 PAGE_END，每页将列表数据合并写入一个 JSON 文件。

特殊情况：

小票详情（/Order/GetOrderSettleTicketNew）本身是“单据级”明细接口，从业务上看不分页，通过 orderSettleId 或 orderSettleIdList 批量请求。脚本中单独针对该接口做了循环调用设计。

2.3 通用响应结构

从样本 JSON 看，多数接口返回结构类似：

{
  "code": 0,
  "data": {
    "...": "...",
    "total": 438,
    "<listField>": [ ... ]
  }
}

示例（会员档案，字段名略）：

{
  "code": 0,
  "data": {
    "total": 438,
    "tenantMemberInfos": [
      {
        "id": 2799...,
        "create_time": "2025-11-08 01:29:33",
        "member_card_grade_code": 1,
        "mobile": "138****1234",
        "nickname": "xxx",
        ...
      }
    ]
  }
}

注意：

列表字段名称并不统一：可能是 list / rows / records / items / dataList，也可能是业务专有名（例如 tenantMemberInfos）。脚本中专门写了一个通用提取函数 extract_list 来处理上述几种常见命名。
部分接口可能完全不分页，只返回单条对象或嵌套结构，需按实际响应处理。

3. 通用参数说明

脚本顶部有一个公共参数池 PARAMS，各个接口在构造请求时会从中按需取值。这些字段可以视为“通用过滤条件”和“业务枚举”。

3.1 门店与组织

siteId：门店 ID（int64）
- 单门店场景为一个长整型；
- 在门店商品档案 1/2 中，脚本会自动转成数组形式：[siteId]。
siteTableAreaIdList：台桌区域 ID 列表（array），用于结账记录筛选具体区域。

3.2 时间区间

startTime / endTime：通用时间范围
rangeStartTime / rangeEndTime：结账类接口使用
StartPayTime / EndPayTime：支付流水接口使用

全部为字符串格式 "YYYY-MM-DD HH:MM:SS"。

3.3 业务枚举类字段（常见）

以下均为整数枚举，具体含义需结合业务系统配置或你提供的 .md 报告来确定：

IsConfirm：助教业绩是否确认（示例值：2）
OnlinePayChannel：线上支付渠道（0 表示全部 / 默认）
paymentMethod：支付方式（现金 / 微信 / 支付宝 / …）
relateType：关联类型（支付记录）
isSaleManUser：是否按业务员维度汇总台费流水
isSalesBind：门店销售记录中，是否按销售绑定过滤
goodsSalesType：商品销售维度（按单品 / 分类 / 时间等）
costPriceType：成本价类型
ableDiscount：是否可打折（-1 代表全部）
tenantGoodsStatus：商品状态（启用 / 停用）
goodsSecondCategoryId：二级分类 ID 列表
goodsState：商品状态（在售 / 已停售）
enableStatus：启用状态
existsGoodsStock：是否仅查有库存商品
couponChannel：券来源渠道
couponUseStatus：券使用状态
settleType：结账类型 / 账单类型
stockType：库存变动类型（出库 / 入库 / 盘点等）

3.4 小票详情专用字段

orderSettleId：单张结账小票对应的结算 ID
orderSettleIdList：结算 ID 列表（脚本中大量示例 ID），支持批量拉取小票详情。

4. 批量采集脚本使用说明

4.2 Token 配置

支持两种方式（优先级从高到低）：

命令行参数：

python fetch_feiqiu_endpoints.py --token "Bearer x.y.z"
# 或仅传 bare token，脚本会自动补上 Bearer 前缀

也支持在同目录 .env 文件中设置 FICOO_TOKEN（依赖 python-dotenv）。

若两者都缺失，脚本会抛出异常并退出。

4.3 配置要调用的接口

脚本中通过 API_NAME 控制要调用的接口，可以是单个字符串或字符串列表：

# 示例：只跑门店商品档案 1 和 2
API_NAME = ["门店商品档案1", "门店商品档案2"]

可选值即 ENDPOINTS 字典中的所有键（见后文接口清单）。

4.4 分页与时间范围配置

在 PARAMS 和分页配置区集中调整：

PAGE_START = 1
PAGE_END   = 2
PAGE_LIMIT = 100

PARAMS = {
    "startTime": "2025-10-01 00:00:00",
    "endTime":   "2025-11-10 00:00:00",
    "rangeStartTime": "...",
    "rangeEndTime":   "...",
    "StartPayTime":   "...",
    "EndPayTime":     "...",
    "siteId": 2790685415443269,
    ...
}
``` :contentReference[oaicite:17]{index=17}  

### 4.5 输出位置与命名

- 输出目录：可配置
- 文件命名列表：
接口 Path 与建议 JSON 文件名对照表

| Request Path                                         | New JSON Filename                         | Brief Description                                    |
| ---------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
| `/MemberProfile/GetTenantMemberList`                 | `member_profiles.json`                    | 会员主档案数据，每条记录对应租户下的一位会员/账户，包括会员基本信息、等级、联系方式等。         |
| `/MemberProfile/GetMemberCardBalanceChange`          | `member_balance_changes.json`             | 会员账户余额变动流水，每条记录对应一次余额增减（充值、消费、调账等）。                  |
| `/MemberProfile/GetTenantMemberCardList`             | `member_stored_value_cards.json`          | 会员储值类卡片列表，每条记录是一张已开通的储值卡及其规则配置（卡种、折扣、适用范围等）。         |
| `/Site/GetRechargeSettleList`                        | `recharge_settlements.json`               | 会员充值结算流水，每条记录是一笔充值订单的结算信息（金额、支付方式、时间等）。              |
| `/AssistantPerformance/GetAbolitionAssistant`        | `assistant_cancellation_records.json`     | 助教废除/取消流水，每条记录表示某张台桌上一次助教被移除/废除的操作，含门店与台桌信息。         |
| `/AssistantPerformance/GetOrderAssistantDetails`     | `assistant_service_records.json`          | 助教服务流水明细，每条记录对应一次助教服务（单次上台/服务时段），可关联订单、结账、小票等。       |
| `/PersonnelManagement/SearchAssistantInfo`           | `assistant_accounts_master.json`          | 助教账号/人事档案维表，每条记录对应一名助教账号，包含人员基本信息、在职状态、计费与权限配置等。     |
| `/Table/GetSiteTables`                               | `site_tables_master.json`                 | 门店台桌维表，每条记录对应一张球台/包厢，包含台号、区域、状态、收费策略等基础配置。           |
| `/Site/GetTaiFeeAdjustList`                          | `table_fee_discount_records.json`         | 台费打折/调账流水，每条记录是一笔针对台费的手工折扣或金额调整，关联订单与台桌。             |
| `/Site/GetSiteTableOrderDetails`                     | `table_fee_transactions.json`             | 台费计费流水明细，每条记录对应一次台费收费明细，可按订单、台桌、时长等维度分析。             |
| `/TenantGoods/QueryTenantGoods`                      | `tenant_goods_master.json`                | 品牌维度的商品档案，每条记录是一个商品在租户层的主数据（名称、分类、定价等），供各门店复用。       |
| `/PackageCoupon/QueryPackageCouponList`              | `group_buy_packages.json`                 | 团购套餐定义列表，每条记录是一种团购券/套餐的规则配置（名称、面值、有效期、适用时段等）。        |
| `/Site/GetSiteTableUseDetails`                       | `group_buy_redemption_records.json`       | 团购套餐使用流水，每条记录对应一次团购券在门店被核销/使用的明细，含台桌与订单信息。           |
| `/Order/GetOrderSettleTicketNew`                     | `settlement_ticket_details.json`          | 结账小票打印详情，每条记录对应一张结算小票的完整快照，包括整单金额、会员、支付方式及台费/商品分项明细。 |
| `/Promotion/GetOfflineCouponConsumePageList`         | `platform_coupon_redemption_records.json` | 平台券（如美团等）验券流水，每条记录对应一次第三方团购券在门店的核销事件。                |
| `/GoodsStockManage/QueryGoodsOutboundReceipt`        | `goods_stock_movements.json`              | 商品库存变动流水，每条记录是某个门店商品的一次出入库/调整事件，可追溯至库存汇总与销售记录。       |
| `/TenantGoodsCategory/QueryPrimarySecondaryCategory` | `stock_goods_category_tree.json`          | 库存模块使用的商品分类树，每条记录是一个商品分类节点，形成一级/二级分类层级结构。            |
| `/TenantGoods/GetGoodsStockReport`                   | `goods_stock_summary.json`                | 门店商品库存汇总，每条记录对应一个门店商品在查询区间内的库存现状与汇总指标。               |
| `/PayLog/GetPayLogListPage`                          | `payment_transactions.json`               | 门店支付流水，每条记录是一笔支付交易（含支付方式、渠道、金额、关联订单等）。               |
| `/Site/GetAllOrderSettleList`                        | `settlement_records.json`                 | 门店结账记录，每条记录是一笔结算单的汇总信息，可与小票详情、支付记录等联查。               |
| `/Order/GetRefundPayLogList`                         | `refund_transactions.json`                | 退款支付流水，每条记录是一笔已发生的退款交易，包含退款金额、业务来源、支付通道等。            |
| `/TenantGoods/GetGoodsSalesList`                     | `store_goods_sales_records.json`          | 门店商品销售流水，每条记录对应一条商品销售明细，可关联支付记录、结账记录与库存变动。           |


* 日志目录：可配置，按接口名单独记录一份日志，包含每次调用的 curl 命令和原始请求/响应快照（Authorization 可选择打码）。

### 4.6 调用重试与限流策略

脚本中使用了 `requests.adapters.HTTPAdapter` + `urllib3.Retry`：

* 重试总次数：3
* 指定的可重试状态码：`429, 500, 502, 503, 504`
* 退避因子：0.5（指数退避）
* 每次请求后随机 `1–4` 秒延迟，减轻服务器压力。

---

## 5. 接口清单总览

以下均为 `POST` 接口，路径相对于 Base URL。

| 模块      | 接口名称    | Path                                                 | 是否分页（按脚本设计）       |
| ------- | ------- | ---------------------------------------------------- | ----------------- |
| 会员      | 会员档案    | `/MemberProfile/GetTenantMemberList`                 | 是（`page`,`limit`） |
| 会员      | 余额变更记录  | `/MemberProfile/GetMemberCardBalanceChange`          | 是                 |
| 会员      | 储值卡列表   | `/MemberProfile/GetTenantMemberCardList`             | 是                 |
| 会员 / 充值 | 充值记录    | `/Site/GetRechargeSettleList`                        | 是                 |
| 助教      | 助教废除    | `/AssistantPerformance/GetAbolitionAssistant`        | 是                 |
| 助教      | 助教流水    | `/AssistantPerformance/GetOrderAssistantDetails`     | 是                 |
| 助教      | 助教账号1   | `/PersonnelManagement/SearchAssistantInfo`           | 是                 |
| 助教      | 助教账号2   | `/PersonnelManagement/SearchAssistantInfo`           | 是                 |
| 台桌      | 台桌列表    | `/Table/GetSiteTables`                               | 是                 |
| 台费      | 台费打折    | `/Site/GetTaiFeeAdjustList`                          | 是                 |
| 台费      | 台费流水    | `/Site/GetSiteTableOrderDetails`                     | 是                 |
| 商品      | 商品档案    | `/TenantGoods/QueryTenantGoods`                      | 是                 |
| 团购      | 团购套餐    | `/PackageCoupon/QueryPackageCouponList`              | 是                 |
| 团购      | 团购套餐流水  | `/Site/GetSiteTableUseDetails`                       | 是                 |
| 订单      | 小票详情    | `/Order/GetOrderSettleTicketNew`                     | 否（单笔/批量按 ID）      |
| 营销 / 券  | 平台验券记录  | `/Promotion/GetOfflineCouponConsumePageList`         | 是                 |
| 库存      | 库存变化记录1 | `/GoodsStockManage/QueryGoodsOutboundReceipt`        | 是                 |
| 库存      | 库存变化记录2 | `/TenantGoodsCategory/QueryPrimarySecondaryCategory` | 是                 |
| 库存      | 库存汇总    | `/TenantGoods/GetGoodsStockReport`                   | 是                 |
| 支付      | 支付记录    | `/PayLog/GetPayLogListPage`                          | 是                 |
| 结账      | 结账记录    | `/Site/GetAllOrderSettleList`                        | 是                 |
| 订单      | 退款记录    | `/Order/GetRefundPayLogList`                         | 是                 |
| 商品 / 门店 | 门店商品档案1 | `/TenantGoods/GetGoodsInventoryList`                 | 是                 |
| 商品 / 销售 | 门店销售记录  | `/TenantGoods/GetGoodsSalesList`                     | 是                 |

---

## 6. 接口详情（参数级，按模块整理）

下面只写“请求参数层面”的反推说明；响应字段请结合etl_billiards/tests/source-data-doc目录下的 `.json` + `.md` 报告使用。

### 6.1 助教相关接口

#### 6.1.1 助教流水 – GetOrderAssistantDetails

* 中文名称：助教流水
* Path：`/AssistantPerformance/GetOrderAssistantDetails`
* Method：POST
* 是否分页：是

**请求参数：**

| 字段名         | 类型     | 必填 | 说明                            |
| ----------- | ------ | -- | ----------------------------- |
| `siteId`    | int64  | 是  | 门店 ID                         |
| `startTime` | string | 是  | 起始时间（含），`YYYY-MM-DD HH:MM:SS` |
| `endTime`   | string | 是  | 结束时间（含）                       |
| `IsConfirm` | int    | 否  | 业绩确认状态（枚举，具体含义待确认）            |
| `page`      | int    | 是  | 页码，从 1 开始                     |
| `limit`     | int    | 是  | 每页条数                          |


#### 6.1.2 助教废除 – GetAbolitionAssistant

* Path：`/AssistantPerformance/GetAbolitionAssistant`
* Method：POST
* 是否分页：是

**请求参数：**

| 字段名         | 类型     | 必填 | 说明    |
| ----------- | ------ | -- | ----- |
| `startTime` | string | 是  | 起始时间  |
| `endTime`   | string | 是  | 结束时间  |
| `siteId`    | int64  | 是  | 门店 ID |
| `page`      | int    | 是  | 页码    |
| `limit`     | int    | 是  | 每页条数  |

#### 6.1.3 助教账号1 / 2 – SearchAssistantInfo

* Path：`/PersonnelManagement/SearchAssistantInfo`
* 两个名称（助教账号1/2）仅是脚本中拆分；实际路径一致，可以视为不同筛选组合。

**请求参数：**

| 字段名               | 类型    | 必填 | 说明           |
| ----------------- | ----- | -- | ------------ |
| `siteId`          | int64 | 是  | 门店 ID        |
| `workStatusEnum`  | int   | 否  | 在职 / 离职状态    |
| `dingTalkSynced`  | int   | 否  | 是否同步钉钉       |
| `leaveId`         | int   | 否  | 请假状态/ID（待确认） |
| `criticismStatus` | int   | 否  | 处分/批评状态（待确认） |
| `signStatus`      | int   | 否  | 签到状态（待确认）    |
| `page`            | int   | 是  | 页码           |
| `limit`           | int   | 是  | 每页条数         |

### 6.2 台桌 / 台费接口

#### 6.2.1 台桌列表 – GetSiteTables

* Path：`/Table/GetSiteTables`
* Method：POST
* 是否分页：是

**请求参数：** 

| 字段名                | 类型  | 必填 | 说明           |
| ------------------ | --- | -- | ------------ |
| `showStatus`       | int | 否  | 展示状态（启用/停用等） |
| `virtualTableType` | int | 否  | 虚拟台桌类型       |
| `page`             | int | 是  | 页码           |
| `limit`            | int | 是  | 每页条数         |

#### 6.2.2 台费流水 – GetSiteTableOrderDetails

* Path：`/Site/GetSiteTableOrderDetails`
* Method：POST
* 是否分页：是

**请求参数：**

| 字段名             | 类型     | 必填 | 说明          |
| --------------- | ------ | -- | ----------- |
| `startTime`     | string | 是  | 起始时间        |
| `endTime`       | string | 是  | 结束时间        |
| `siteId`        | int64  | 是  | 门店 ID       |
| `isSaleManUser` | int    | 否  | 是否按销售人员维度过滤 |
| `page`          | int    | 是  | 页码          |
| `limit`         | int    | 是  | 每页条数        |

#### 6.2.3 台费打折 – GetTaiFeeAdjustList

* Path：`/Site/GetTaiFeeAdjustList`
* Method：POST

**请求参数：** 

| 字段名         | 类型     | 必填 | 说明    |
| ----------- | ------ | -- | ----- |
| `startTime` | string | 是  | 起始时间  |
| `endTime`   | string | 是  | 结束时间  |
| `siteId`    | int64  | 是  | 门店 ID |
| `page`      | int    | 是  | 页码    |
| `limit`     | int    | 是  | 每页条数  |

### 6.3 会员相关接口

#### 6.3.1 会员档案 – GetTenantMemberList

* Path：`/MemberProfile/GetTenantMemberList`
* Method：POST
* 是否分页：是

**请求参数：** 

| 字段名                   | 类型  | 必填 | 说明        |
| --------------------- | --- | -- | --------- |
| `isMemberInBlackList` | int | 否  | 是否黑名单     |
| `status_Revoked`      | int | 否  | 会员状态（注销等） |
| `page`                | int | 是  | 页码        |
| `limit`               | int | 是  | 每页条数      |

> 备注：样本 JSON 显示列表字段为 `tenantMemberInfos`，包含 `id`、`system_member_id`、`member_card_grade_code` 等字段，具体字段含义详见对应 `.md` 报告。

#### 6.3.2 余额变更记录 – GetMemberCardBalanceChange

* Path：`/MemberProfile/GetMemberCardBalanceChange`

**请求参数：**

| 字段名         | 类型     | 必填 | 说明     |
| ----------- | ------ | -- | ------ |
| `startTime` | string | 是  | 变更起始时间 |
| `endTime`   | string | 是  | 变更结束时间 |
| `fromType`  | int    | 否  | 变更来源类型 |
| `page`      | int    | 是  | 页码     |
| `limit`     | int    | 是  | 每页条数   |

#### 6.3.3 储值卡列表 – GetTenantMemberCardList

* Path：`/MemberProfile/GetTenantMemberCardList`

**请求参数：**

| 字段名               | 类型    | 必填 | 说明    |
| ----------------- | ----- | -- | ----- |
| `siteId`          | int64 | 是  | 门店 ID |
| `cardPhysicsType` | int   | 否  | 卡实体类型 |
| `status`          | int   | 否  | 卡状态   |
| `page`            | int   | 是  | 页码    |
| `limit`           | int   | 是  | 每页条数  |

#### 6.3.4 充值记录 – GetRechargeSettleList

* Path：`/Site/GetRechargeSettleList`

**请求参数：**

| 字段名              | 类型     | 必填 | 说明           |
| ---------------- | ------ | -- | ------------ |
| `settleType`     | int    | 否  | 结账/充值类型      |
| `paymentMethod`  | int    | 否  | 支付方式         |
| `rangeStartTime` | string | 是  | 充值时间起        |
| `rangeEndTime`   | string | 是  | 充值时间止        |
| `siteId`         | int64  | 是  | 门店 ID        |
| `isFirst`        | int    | 否  | 是否首单/首充（待确认） |
| `page`           | int    | 是  | 页码           |
| `limit`          | int    | 是  | 每页条数         |

### 6.4 支付 / 结账 / 订单接口

#### 6.4.1 支付记录 – GetPayLogListPage

* Path：`/PayLog/GetPayLogListPage`

**请求参数：**

| 字段名                | 类型     | 必填 | 说明    |
| ------------------ | ------ | -- | ----- |
| `StartPayTime`     | string | 是  | 支付时间起 |
| `EndPayTime`       | string | 是  | 支付时间止 |
| `siteId`           | int64  | 是  | 门店 ID |
| `OnlinePayChannel` | int    | 否  | 支付渠道  |
| `paymentMethod`    | int    | 否  | 支付方式  |
| `relateType`       | int    | 否  | 关联类型  |
| `page`             | int    | 是  | 页码    |
| `limit`            | int    | 是  | 每页条数  |

#### 6.4.2 结账记录 – GetAllOrderSettleList

* Path：`/Site/GetAllOrderSettleList`

**请求参数：**

| 字段名                   | 类型         | 必填 | 说明       |
| --------------------- | ---------- | -- | -------- |
| `settleType`          | int        | 否  | 结账类型     |
| `rangeStartTime`      | string     | 是  | 结账时间起    |
| `rangeEndTime`        | string     | 是  | 结账时间止    |
| `siteId`              | int64      | 是  | 门店 ID    |
| `siteTableAreaIdList` | array<int> | 否  | 台桌区域ID列表 |
| `page`                | int        | 是  | 页码       |
| `limit`               | int        | 是  | 每页条数     |

#### 6.4.3 退款记录 – GetRefundPayLogList

* Path：`/Order/GetRefundPayLogList`

**请求参数：**

| 字段名         | 类型     | 必填 | 说明    |
| ----------- | ------ | -- | ----- |
| `startTime` | string | 是  | 退款时间起 |
| `endTime`   | string | 是  | 退款时间止 |
| `page`      | int    | 是  | 页码    |
| `limit`     | int    | 是  | 每页条数  |

#### 6.4.4 小票详情 – GetOrderSettleTicketNew

* Path：`/Order/GetOrderSettleTicketNew`
* Method：POST
* 设计上非分页接口，每次查询一个 `orderSettleId`，但可以在客户端循环批量调用。

**请求参数：**

| 字段名             | 类型    | 必填 | 说明           |
| --------------- | ----- | -- | ------------ |
| `orderSettleId` | int64 | 是  | 结算单 ID（单个小票） |

脚本级批量用法：遍历 `orderSettleIdList`，每个 ID 调用一次该接口，将结果追加到数组中再保存。

### 6.5 商品 / 库存 / 销售接口

#### 6.5.1 商品档案 – QueryTenantGoods

* Path：`/TenantGoods/QueryTenantGoods`

**请求参数：**

| 字段名                 | 类型  | 必填 | 说明             |
| ------------------- | --- | -- | -------------- |
| `costPriceType`     | int | 否  | 成本价类型          |
| `ableDiscount`      | int | 否  | 是否可打折（-1 表示全部） |
| `tenantGoodsStatus` | int | 否  | 商品状态           |
| `page`              | int | 是  | 页码             |
| `limit`             | int | 是  | 每页条数           |

#### 6.5.2 门店商品档案1 – GetGoodsInventoryList

* Path：`/TenantGoods/GetGoodsInventoryList`

**请求参数：**

| 字段名                     | 类型           | 必填 | 说明                        |
| ----------------------- | ------------ | -- | ------------------------- |
| `goodsSecondCategoryId` | array<int>   | 否  | 二级分类 ID                   |
| `goodsState`            | int          | 否  | 商品状态                      |
| `enableStatus`          | int          | 否  | 启用状态                      |
| `siteId`                | array<int64> | 是  | 门店 ID 列表（脚本会把单个 ID 包装为数组） |
| `existsGoodsStock`      | int          | 否  | 是否仅查有库存                   |
| `page`                  | int          | 是  | 页码                        |
| `limit`                 | int          | 是  | 每页条数                      |


#### 6.5.4 门店销售记录 – GetGoodsSalesList

* Path：`/TenantGoods/GetGoodsSalesList`

**请求参数：**

| 字段名              | 类型     | 必填 | 说明             |
| ---------------- | ------ | -- | -------------- |
| `isSalesBind`    | int    | 否  | 是否按销售绑定过滤      |
| `startTime`      | string | 是  | 销售时间起          |
| `endTime`        | string | 是  | 销售时间止          |
| `goodsSalesType` | int    | 否  | 销售维度（按单品 / 分类） |
| `page`           | int    | 是  | 页码             |
| `limit`          | int    | 是  | 每页条数           |

#### 6.5.5 库存变化记录1 – QueryGoodsOutboundReceipt

* Path：`/GoodsStockManage/QueryGoodsOutboundReceipt`

**请求参数：**

| 字段名         | 类型     | 必填 | 说明     |
| ----------- | ------ | -- | ------ |
| `siteId`    | int64  | 是  | 门店 ID  |
| `stockType` | int    | 否  | 库存变动类型 |
| `startTime` | string | 是  | 变动时间起  |
| `endTime`   | string | 是  | 变动时间止  |
| `page`      | int    | 是  | 页码     |
| `limit`     | int    | 是  | 每页条数   |

#### 6.5.6 库存变化记录2 – QueryPrimarySecondaryCategory

* Path：`/TenantGoodsCategory/QueryPrimarySecondaryCategory`

**请求参数：**

| 字段名         | 类型     | 必填 | 说明      |
| ----------- | ------ | -- | ------- |
| `siteId`    | int64  | 是  | 门店 ID   |
| `startTime` | string | 否  | 时间起（如有） |
| `endTime`   | string | 否  | 时间止（如有） |
| `page`      | int    | 是  | 页码      |
| `limit`     | int    | 是  | 每页条数    |

#### 6.5.7 库存汇总 – GetGoodsStockReport

* Path：`/TenantGoods/GetGoodsStockReport`

**请求参数：**

| 字段名         | 类型     | 必填 | 说明    |
| ----------- | ------ | -- | ----- |
| `siteId`    | int64  | 是  | 门店 ID |
| `startTime` | string | 否  | 时间过滤起 |
| `endTime`   | string | 否  | 时间过滤止 |
| `page`      | int    | 是  | 页码    |
| `limit`     | int    | 是  | 每页条数  |

### 6.6 团购 / 验券接口

#### 6.6.1 团购套餐 – QueryPackageCouponList

* Path：`/PackageCoupon/QueryPackageCouponList`

**请求参数：**

| 字段名                    | 类型  | 必填 | 说明    |
| ---------------------- | --- | -- | ----- |
| `areaId`               | int | 否  | 区域 ID |
| `commonShowStatus`     | int | 否  | 展示状态  |
| `offlineCouponChannel` | int | 否  | 券渠道   |
| `systemGroupType`      | int | 否  | 套餐类型  |
| `page`                 | int | 是  | 页码    |
| `limit`                | int | 是  | 每页条数  |

#### 6.6.2 团购套餐流水 – GetSiteTableUseDetails

* Path：`/Site/GetSiteTableUseDetails`

**请求参数：**

| 字段名                    | 类型     | 必填 | 说明    |
| ---------------------- | ------ | -- | ----- |
| `siteId`               | int64  | 是  | 门店 ID |
| `offlineCouponChannel` | int    | 否  | 券渠道   |
| `startTime`            | string | 是  | 使用时间起 |
| `endTime`              | string | 是  | 使用时间止 |
| `page`                 | int    | 是  | 页码    |
| `limit`                | int    | 是  | 每页条数  |

#### 6.6.3 平台验券记录 – GetOfflineCouponConsumePageList

* Path：`/Promotion/GetOfflineCouponConsumePageList`

**请求参数：**

| 字段名               | 类型     | 必填 | 说明    |
| ----------------- | ------ | -- | ----- |
| `couponChannel`   | int    | 否  | 券渠道   |
| `startTime`       | string | 是  | 验券时间起 |
| `endTime`         | string | 是  | 验券时间止 |
| `siteId`          | int64  | 是  | 门店 ID |
| `couponUseStatus` | int    | 否  | 券使用状态 |
| `page`            | int    | 是  | 页码    |
| `limit`           | int    | 是  | 每页条数  |

---

32 KiB Raw Permalink Blame History Unescape Escape