Files
ZQYY.FQ-ETL/docs/api-reference/endpoints/refund_transactions.md

712 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 退款流水GetRefundPayLogList
> 自动生成于 2026-02-13 | 数据来源:实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Order/GetRefundPayLogList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Order/GetRefundPayLogList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token`Authorization` 头) |
| ODS 对应表 | `refund_transactions` |
| 分页方式 | `page` + `limit`(最大 100 |
| 时间范围 | 需要startTime / endTime |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `page` | int | `1` | 页码(从 1 开始) |
| `limit` | int | `100` | 每页条数(最大 100 |
## 响应字段(共 32 个)
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `tenantName` | string | '朗朗桌球' |
| 2 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 3 | `id` | int | 3089577798995141 |
| 4 | `site_id` | int | 2790685415443269 |
| 5 | `tenant_id` | int | 2790683160709957 |
| 6 | `pay_sn` | int | 0 |
| 7 | `pay_amount` | float | -8.0 |
| 8 | `pay_status` | int | 2 |
| 9 | `pay_time` | string | '2026-02-10 23:41:06' |
| 10 | `create_time` | string | '2026-02-10 23:41:06' |
| 11 | `relate_type` | int | 1 |
| 12 | `relate_id` | int | 3089548319804869 |
| 13 | `is_revoke` | int | 0 |
| 14 | `is_delete` | int | 0 |
| 15 | `online_pay_channel` | int | 0 |
| 16 | `payment_method` | int | 4 |
| 17 | `balance_frozen_amount` | float | 0.0 |
| 18 | `card_frozen_amount` | float | 0.0 |
| 19 | `member_id` | int | 0 |
| 20 | `member_card_id` | int | 0 |
| 21 | `round_amount` | float | 0.0 |
| 22 | `online_pay_type` | int | 0 |
| 23 | `action_type` | int | 2 |
| 24 | `refund_amount` | float | 0.0 |
| 25 | `cashier_point_id` | int | 0 |
| 26 | `operator_id` | int | 0 |
| 27 | `pay_terminal` | int | 1 |
| 28 | `pay_config_id` | int | 0 |
| 29 | `channel_payer_id` | string | '' |
| 30 | `channel_pay_no` | string | '' |
| 31 | `check_status` | int | 1 |
| 32 | `channel_fee` | float | 0.0 |
## 详细字段分析
> 以下内容迁移自旧版 `refund_transactions-Analysis.md`,包含字段的业务含义、枚举值、跨表关联等详细说明。
2. 记录内容类型(这份 JSON 实际记录的是什么)
从字段组合和数值特征看,每条记录代表:
“一笔已发生的退款支付流水(资金层面的退款交易)”
特点:
pay_amount 全为负数(例如 -12.0, -44000.0, -3000.0),很明显是“钱从店里流出”的方向。
pay_status 全为 2结合支付记录推测是“退款/完成状态”(至少表示“已处理完成”)。
action_type 全为 2极大概率是“退款动作类型”的枚举。
relate_type 只出现 2 与 5对应两类不同业务一种是“消费类”一种是“充值/储值类”(具体含义依赖系统配置,但肯定是区分不同业务来源)。
这份“退款记录”是 资金维度 的退款流水,不是“业务维度”的退款单(比如没记录退款原因、操作备注等)。业务上的退款原因应从对应的订单、充值记录或其他业务表中去追踪。
二、字段逐一说明(含数据类型 & 枚举推断)
下面按功能分组,对每个字段说明其含义、类型,是否枚举,以及这些记录中实际出现的取值。
1. 门店 / 租户维度字段
tenantName
类型string
示例:"朗朗桌球"
含义:租户(商户)名称。
特点:本文件中固定为“朗朗桌球”,完全冗余于 siteProfile.shop_name。
作用:方便直接在流水中看到店名,无需再查门店档案。
tenant_id
类型int
示例2790683160709957
含义:租户/品牌 ID全系统维度标识该商户。
特点:本文件中所有记录相同。
作用:
作为所有门店数据的“租户分区键”;
与其他 JSON 中同名字段一致,用来确认“同一商户”。
site_id
类型int
示例2790685415443269
含义:门店 ID。
特点:本文件中所有记录相同(单门店)。
作用:
关联其他数据表中同一门店的数据;
与 siteProfile.id 一致,是 siteProfile 的主键。
siteProfile
类型object
含义:门店信息快照,结构与其他 JSON 中的 siteProfile 完全一致。包含字段包括但不限于:
id门店 ID= site_id
shop_name店名
full_address / address地址
longitude / latitude经纬度
business_tel电话
一系列门店配置项(灯控、考勤、营业状态等)。
作用:
为每条退款记录附带一份当时的门店元信息;
提供冗余信息,避免联表查询门店档案。
2. 退款流水主键与关联业务字段
id
类型int
示例2955202296416389
含义:本条 退款流水 的唯一 ID。
特点:
每条记录一个不同的长整型 ID疑似雪花 ID 或类似分布式 ID。
作用:作为退款记录表主键,内部检索用。
relate_type
类型int枚举
当前取值:{2, 5}
含义:本退款对应的“业务类型”。
结合支付记录的 relate_type 推测:
1在支付记录中存在某类订单支付可能是结账单支付
2另一类业务比如“台费/商品类消费单”或“综合订单”;在退款记录中有多条。
5通常用来标记“储值/充值类业务”,这里的几条金额很大,形态上很像“退充值款”。
结构作用:
不直接指向某张表,而是先告知“这是哪种业务”,再配合 relate_id 确定具体业务记录。
relate_id
类型int
示例2948246513454661
含义:本次退款关联的业务 ID。
对于 relate_type = 2应该对应某个订单/结算的主键;
对于 relate_type = 5应该对应某条充值记录或储值业务记录的主键。
特点:
同一个 relate_id 可能对应多条退款流水(例如先退 88.33,又退 0.67,对应两个不同撤销动作,都关联到同一 relate_id
与其他 JSON 的关系:
在“支付记录”中也有 relate_type + relate_id 组合,含义一致:指向业务实体;
本文件里的退款流水和“支付记录”是通过“共同指向同一业务实体”来间接关联,而不是直接指向支付记录。
3. 时间字段
create_time
类型string格式为 "YYYY-MM-DD HH:MM:SS"
示例:"2025-11-03 15:36:19"
含义:本条退款流水在系统内创建时间。
特点:
当前数据中create_time 与 pay_time 完全相同,说明系统在退款发生时立刻生成流水记录。
如果未来有“申请退款-审核-执行”流程create_time 有可能偏早。
pay_time
类型string格式同上
示例:"2025-11-03 15:36:19"
含义:退款在支付渠道层面实际发生的时间。
特点:
当前数据中与 create_time 一致,可以视为“退款完成时间”。
结构提示:
保留 create_time 和 pay_time 两个字段,说明系统设计上区分“记录生成时间”与“渠道交易时间”。如果引入异步处理,二者可能就会出现差异。
4. 金额相关字段
pay_amount
类型float
示例:-12.0, -44000.0, -3000.0, -0.67 等
含义:本次退款的 资金变动金额。
特征很重要:
全部为负数,绝对值就是退款金额。
表示“从门店账户流出的金额”(相对于支付记录中的正数进账)。
结构意义:
这份“退款记录.json”在设计上没有专门用 refund_amount 存实际退款额,而是直接用 pay_amount < 0 表示退款金额大小。
这点对之后做数据抽取/ETL 很重要:判断退款金额只看 pay_amount 的负数refund_amount 字段在当前实现中并未使用。
refund_amount
类型float
当前全部为0.0
含义(推测):
设计上本应显示“实际退款金额”(正数),与 pay_amount 配合使用;
但在目前实现里,系统只用了 pay_amount 表示金额,并没有填充这个字段。
在当前数据中的状态:
可以视为“保留字段/未启用”。
balance_frozen_amount
类型float
当前:全部 0.0
含义(推测):
涉及会员储值卡退款时,暂时冻结的余额金额;
用于一些“先冻结后解冻/退款”的逻辑。
当前数据状态:
所有退款记录的 member_id / member_card_id 都是 0对应的冻结金额自然也是 0
说明这 11 笔退款都不是“退到会员卡余额”,而是对普通支付渠道(例如刷卡)的退款。
card_frozen_amount
类型float
当前:全部 0.0
含义:与上一个类似,偏向“某张卡的被冻结金额”,也与会员卡/储值账户相关。
状态同上:本数据中未发生“卡冻结退款”。
round_amount
类型float
当前:全部 0.0
含义(推测):
舍入金额/抹零金额;
在某些场景下,如果退款金额存在四舍五入等调整,会单独记录到这个字段。
当前未使用。
channel_fee
类型float
当前:全部 0.0
含义(推测):
第三方支付渠道对本次退款收取的手续费;
正常应该在“通道成本核算”里用到。
当前数据中没有任何通道手续费记录(可能通道不收手续费,或者手续费隐藏在其他费用内)。
5. 支付方式 / 渠道相关字段
结合“支付记录.json”一起看更容易理解这些字段的结构设计。
payment_method
类型int枚举
当前取值:仅 4
在“支付记录.json”中出现的取值有2、4。
含义(推测):
支付/退款的 方式类型:
2某种线上支付渠道很可能是微信
4另一种支付方式很可能是银行卡 POS 或现金),当前这批退款全是 4说明都是同一支付方式的退款。
具体枚举值定义要以“非球科技”系统文档为准,但可以确定是“支付方式枚举”。
online_pay_channel
类型int枚举
当前:全部 0
在“支付记录.json”里同样全部为 0。
含义(推测):
线上支付的 渠道编号,例如:
0线下/默认渠道;
其他值(如 1,2可能分别代表微信、支付宝等。
当前门店的退款记录全部为 0说明这 11 笔退款要么是线下渠道,要么系统没有区分线上子渠道。
online_pay_type
类型int枚举
当前:全部 0
含义(推测):
在线退款的类型:
0原路退回
其他值(如果存在)可能代表“退到余额”、“退到其他银行卡”等。
当前数据中未出现其他值,说明门店的退款都是默认策略(很可能就是原路退回)。
pay_terminal
类型int枚举
当前:全部 1
含义(推测):
退款所使用的 终端类型:
1前台收银端
其他值可能为:小程序、自助机、后台管理系统等。
本文件中所有退款都来自同一种终端类型。
pay_config_id
类型int
当前:全部 0
含义(推测):
支付配置 ID例如商户在“非球科技”内配置的某一条支付通道某个微信商户号、银联通道的主键。
当前数据未填(可能全部走默认配置),因此都是 0。
channel_payer_id
类型string
当前:全部为空字符串 ""
含义(推测):
支付渠道侧的 payer ID例如微信 openid、银行卡号掩码等。
当前数据未使用(可能系统没回写或导出时屏蔽了)。
channel_pay_no
类型string
当前:全部为空字符串 ""
含义(推测):
第三方支付平台的交易号(如微信支付单号、支付宝交易号等)。
当前为空:要么是通道未返回,要么导出接口没带出这部分数据。
6. 会员关联字段
member_id
类型int
当前:全部 0
含义:
租户内部的会员 ID对应会员档案中的某个主键
当前状态:
这 11 笔退款中没有任何一笔标记了会员 ID说明是“非会员退款”或退款没绑定到会员档案。
member_card_id
类型int
当前:全部 0
含义:
关联的会员卡账户 ID对应“储值卡列表”或“会员档案”中的某一张卡
当前状态:
没有记录任何“退到某张会员卡”的情况;
结合 balance_frozen_amount = 0、card_frozen_amount = 0可以确定当前导出时间范围的退款全部是对外部支付渠道的退款没有会员卡内部余额的退款。
7. 状态标志字段
pay_status
类型int枚举
当前:全部 2
在“支付记录.json”中同样只有值 2。
含义(推测):
支付/退款状态枚举:
1 可能为“待支付/处理中”;
2 为“已完成”(支付成功 / 退款完成)。
鉴于所有支付、退款记录导出时都已经完成,因此本文件中只有 2。
is_revoke
类型int枚举
当前:全部 0
含义(推测):
是否撤销型退款/撤销原支付:
0正常退款
1撤销类型操作。
当前为 0说明所有记录按“正常退款”处理而不是“支付撤销”这类特殊类型。
is_delete
类型int枚举
当前:全部 0
含义:逻辑删除标志。
0未删除
1已删除逻辑上标记删除但记录仍存在
当前数据中所有退款记录都处于“未删除”状态。
check_status
类型int枚举
当前:全部 1
含义(推测):
审核状态:
1已审核/通过;
其他值可能表示“待审核/审核拒绝”等。
结构意义:
说明系统设计上支持“退款需审核”的流程,但当前导出时这些记录已经审过。
action_type
类型int枚举
当前:全部 2
含义(推测):
行为类型:
1支付
2退款
或类似的“资金动作类型”。
结合:
支付记录并没有此字段,退款记录有 action_type=2
再加上 pay_amount<0基本可以确定这是“退款动作”的枚举标识。
8. 其他操作相关字段
cashier_point_id
类型int
当前:全部 0
含义(推测):
收银点 ID例如前台 1、前台 2、自助机等。
当前数据中未区分具体收银点,统一为 0。
operator_id
类型int
当前:全部 0
含义:
执行该退款操作的操作员 ID。
当前全部为 0说明
要么系统没有记录具体操作员;
要么导出接口未把这个信息带出(但字段已预留)。
三、与其它 JSON 文件的关联关系(结构层面)
从字段角度,退款记录.json 与其它数据之间主要有以下关联:
与门店/租户:
tenant_id ↔ 所有 JSON 中的 tenant_id
site_id ↔ 所有 JSON 中的 site_id
siteProfile 内部的 id、tenant_id 与上述字段一致。
→ 说明:退款记录明确挂在“朗朗桌球”这个门店下,与其它消费、库存、助教等记录在同一数据域。
与支付记录(支付记录.json
两者都拥有:
relate_type + relate_id指向同一个业务实体订单、充值等
payment_method、online_pay_channel同一套支付方式枚举
pay_amount、pay_status、pay_time结构一致。
差异:
支付记录的 pay_amount 为正数(进账),退款记录的 pay_amount 为负数(出账);
退款记录多了一些退款专用字段refund_amount、balance_frozen_amount、card_frozen_amount、is_revoke、online_pay_type、channel_fee 等。
结构性结论:
支付记录 = 资金正向流入流水;
退款记录 = 资金反向流出流水;
通过 同一个 relate_type + relate_id 指向同一业务主单,从而把“支付”和“退款”绑定在同一个订单/充值实体之上。
与订单/充值等业务表:
relate_type 通知你“这是哪种业务”relate_id 是那种业务表里的主键。
在已导出的 JSON 中,对应的业务表大致为:
relate_type = 2 → 多数对应“订单类业务”(例如结账记录、小票详情、消费明细);
relate_type = 5 → 多数对应“充值类业务”(对照余额变更记录、充值记录)。
虽然我们在当前导出中没拿到完整的充值记录明细,但这两字段的存在,已经把退款挂在“业务主单”的坐标上了。
与会员体系:
通过 member_id、member_card_id 理论上可以关联到:
会员档案(会员档案.json
储值卡列表(储值卡列表.json
余额变更记录(余额变更记录.json
当前这批数据里二者均为 0说明这 11 笔退款完全与会员卡无关,是纯支付渠道层面的退款。
结构意义:
一旦未来有“退到储值卡”的场景member_id/member_card_id 会出现非 0 值,进而通过上述表串联起“资金退款 → 会员余额变更 → 卡账户状态”。
四、结构层面的额外重要线索(不涉及金额分析)
正/负号决定资金方向:
退款记录并没有用一个单独的“类型字段 + 正数金额”来描述退款,而是直接用 pay_amount 为负,配合 action_type=2 表示“退款”。
对后续数据对接/迁移很关键:判断“是支付还是退款”,不能只看 pay_status而是要同时看 action_type + pay_amount 的符号。
业务实体与资金流水是一对多关系:
两条记录中 relate_id 相同但 id 不同的情况,意味着同一业务单可以产生多笔退款(例如分批退)。
这也解释了为什么系统用 relate_type + relate_id 来指业务,而“支付 record ID / 退款 record ID”本身只是在资金流水表内唯一。
退款文件是资金维,不含任何“原因类字段”:
没有“退款原因”、“备注”、“操作人姓名”等文本字段;
“是否审核通过”、“是否撤销”等只通过状态位表示;
说明系统将“业务解释”留给业务表(订单/充值),这里只关心钱动了多少、从哪儿来、到哪儿去。
会员退款与普通退款在结构上是统一模型:
即使当前数据里没有会员退款记录,字段已经预留了:
member_id / member_card_id
balance_frozen_amount / card_frozen_amount
online_pay_type 等。
一旦发生“退到余额/退到会员卡”的场景,这份结构可以无缝承载,不需要变更表结构。
审核流程是结构预留但未复杂使用:
有 check_status 字段,也有 is_revoke表明系统支持“审核 + 撤销”这类管理流程。
当前导出数据中全部为 check_status=1、is_revoke=0说明
要么店内流程简单,退款都直接通过;
要么导出只包含“已审核通过的记录”。
与支付记录共用枚举体系:
payment_method、online_pay_channel、pay_terminal、relate_type 等枚举字段,与支付记录完全共用。
这一点对于你后续构建统一的资金流水视图很关键:可以把支付记录和退款记录 union 在一起,通过这些枚举和正负金额,就能得到一张统一的资金流水大表。