ZQYY.FQ-ETL/docs/api-reference/README.md

API 参考文档

飞球 ETL 系统上游 SaaS API 的标准化文档。 自动生成于 2026-02-13，基于实时 API 调用 + 本地 JSON 样本。

目录结构

docs/api-reference/
├── README.md                 # 本文件（索引）
├── api_registry.json         # API 注册表（标准化参数存储）
├── _api_call_results.json    # API 调用结果（字段提取）
├── endpoints/                # 每个 API 一个 .md 文档
│   ├── assistant_accounts_master.md
│   ├── ...（共 25 个）
│   └── tenant_member_balance_overview.md
└── samples/                  # 每个 API 的响应样本（单条记录 JSON）
    ├── assistant_accounts_master.json
    ├── ...
    └── tenant_member_balance_overview.json

API 总览（25 个接口）

人事管理

API	中文名	ODS 表	字段数
SearchAssistantInfo	助教账号主数据	assistant_accounts_master	61
GetOrderAssistantDetails	助教服务流水	assistant_service_records	64
GetAbolitionAssistant	助教撤销记录	assistant_cancellation_records	13

订单与结算

API	中文名	ODS 表	字段数
GetAllOrderSettleList	结账记录	settlement_records	92
GetSiteTableOrderDetails	台费流水	table_fee_transactions	39
GetTaiFeeAdjustList	台费优惠记录	table_fee_discount_records	20
GetOrderSettleTicketNew	结账小票明细	settlement_ticket_details	⚠️ 不可用

支付与退款

API	中文名	ODS 表	字段数
GetPayLogListPage	支付流水	payment_transactions	11
GetRefundPayLogList	退款流水	refund_transactions	32
GetRechargeSettleList	充值结算记录	recharge_settlements	92

会员

API	中文名	ODS 表	字段数
GetTenantMemberList	会员档案	member_profiles	15
GetTenantMemberCardList	会员储值卡	member_stored_value_cards	68
GetMemberCardBalanceChange	会员余额变动	member_balance_changes	25

优惠券与团购

API	中文名	ODS 表	字段数
GetOfflineCouponConsumePageList	平台券核销记录	platform_coupon_redemption_records	26
QueryPackageCouponList	团购套餐定义	group_buy_packages	35
GetSiteTableUseDetails	团购核销记录	group_buy_redemption_records	43

商品与库存

API	中文名	ODS 表	字段数
QueryTenantGoods	租户商品主数据	tenant_goods_master	31
GetGoodsSalesList	门店商品销售记录	store_goods_sales_records	50
GetGoodsInventoryList	门店商品库存主数据	store_goods_master	45
QueryPrimarySecondaryCategory	商品分类树	stock_goods_category_tree	2
QueryGoodsOutboundReceipt	库存出入库流水	goods_stock_movements	19
GetGoodsStockReport	库存汇总报表	goods_stock_summary	14

台桌

API	中文名	ODS 表	字段数
GetSiteTables	台桌主数据	site_tables_master	25

新增 API（尚未建 ODS 表）

API	中文名	ODS 表	字段数
QueryRoleAreaAssociation	角色区域关联	无	1
TenantMemberBalanceOverview	会员余额总览	无	9

关键发现

分页参数差异

• 大多数端点接受 page + limit
• GetAllOrderSettleList、GetRechargeSettleList、GetPayLogListPage 拒绝 pageSize/pageNo（HTTP 1400），必须用 limit
• limit 最大值为 100

特殊参数格式

• GetGoodsInventoryList 的 siteId 必须为数组格式 [sid]
• GetGoodsSalesList 需要 isSalesBind/goodsSalesType 业务过滤参数
• QueryPackageCouponList 的 areaId 为数组格式

响应结构差异

• 大多数端点：{code, data: {list: [...], total}}
• settlement_records / recharge_settlements：{code, data: {settleList: [{siteProfile, settleList: {...}}]}}
• stock_goods_category_tree：{code, data: {goodsCategoryList: [...]}}
• payment_transactions / refund_transactions：记录中嵌套 siteProfile 对象

与旧文档的关系

旧文档位于 docs/test-json-doc/（已废弃），包含：

• *.json — 本地 JSON 样本文件（仍可用于离线回放）
• *-Analysis.md — 详细字段分析文档（内容已迁移至本目录各端点文档的"详细字段分析"章节）

新文档优势：

• 标准化结构（请求参数表 + 响应字段表 + 详细分析）
• api_registry.json 提供机器可读的 API 定义
• samples/ 目录提供最新响应样本