416 lines
10 KiB
Markdown
416 lines
10 KiB
Markdown
# 财务结算接口文档
|
||
|
||
本文档汇总财务结算相关接口，覆盖供应商/分销商日结、月结费用查询，平台收入查询，结算单创建、审批和记账闭环。
|
||
|
||
## 通用说明
|
||
|
||
接口域名: https://dev.opencomputing.cn
|
||
|
||
金额口径：
|
||
|
||
- `sales_amount`：销售金额，来源于 `bill.amount`。
|
||
- `settlement_amount`：应结算金额。
|
||
- 供应商：当前账本 `bill_detail.subjectname LIKE '待结转%'` 且 `accounting_dir='贷'`。
|
||
- 分销商：当前账本 `bill_detail.subjectname='分销商存放资金'` 且 `accounting_dir='借'`，`participantid=分销商orgid`。
|
||
- `platform_income_amount`：平台收入，当前账本 `bill_detail.subjectname IN ('折扣收入', '底价收入')` 且 `accounting_dir='贷'`。
|
||
- 所有正式结算金额只统计已记账账单：`bill.bill_state = '1'`。
|
||
|
||
状态说明：
|
||
|
||
| 状态 | 含义 |
|
||
| --- | --- |
|
||
| `draft` | 草稿，已创建结算单但未提交审批 |
|
||
| `approving` | 审批中 |
|
||
| `approved` | 审批通过，等待或正在记账 |
|
||
| `rejected` | 审批拒绝 |
|
||
| `settled` | 已完成结算记账 |
|
||
| `failed` | 结算记账失败 |
|
||
| `cancelled` | 审批撤销 |
|
||
|
||
推荐调用流程：
|
||
|
||
```text
|
||
summary -> preview -> create -> submit -> apv_callback
|
||
```
|
||
|
||
## 1. 汇总查询
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_summary.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
查询供应商或分销商在指定日结/月结账期内的销售金额、结算金额、平台收入和账单数量。支持按对手方聚合，也支持指定某个供应商或分销商查询。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
|
||
| `counterparty_type` | 是 | string | `supplier` 供应商，`reseller` 分销商 |
|
||
| `period_type` | 否 | string | `day` 或 `month`，默认 `day` |
|
||
| `start_date` | 是 | string | 查询开始日期，格式 `YYYY-MM-DD` |
|
||
| `end_date` | 是 | string | 查询结束日期，格式 `YYYY-MM-DD` |
|
||
| `counterparty_orgid` | 否 | string | 指定供应商或分销商机构 ID |
|
||
| `current_page` | 否 | number | 页码，默认 `1` |
|
||
| `page_size` | 否 | number | 每页数量，默认 `20` |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"accounting_orgid": "org001",
|
||
"counterparty_type": "supplier",
|
||
"period_type": "month",
|
||
"start_date": "2026-06-01",
|
||
"end_date": "2026-06-30",
|
||
"current_page": 1,
|
||
"page_size": 20
|
||
}
|
||
```
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.summary.sales_amount` | 销售金额合计 |
|
||
| `data.summary.settlement_amount` | 结算金额合计 |
|
||
| `data.summary.platform_income_amount` | 平台收入合计 |
|
||
| `data.summary.bill_count` | 账单数量 |
|
||
| `data.items[].period` | 账期，日结为 `YYYY-MM-DD`，月结为 `YYYY-MM` |
|
||
| `data.items[].counterparty_orgid` | 对手方机构 ID |
|
||
| `data.items[].counterparty_name` | 对手方名称 |
|
||
| `data.items[].sales_amount` | 当前行销售金额 |
|
||
| `data.items[].settlement_amount` | 当前行结算金额 |
|
||
| `data.items[].platform_income_amount` | 当前行平台收入 |
|
||
| `data.items[].bill_count` | 当前行账单数量 |
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"status": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"accounting_orgid": "org001",
|
||
"counterparty_type": "supplier",
|
||
"period_type": "month",
|
||
"start_date": "2026-06-01",
|
||
"end_date": "2026-06-30",
|
||
"summary": {
|
||
"sales_amount": 1000.0,
|
||
"settlement_amount": 700.0,
|
||
"platform_income_amount": 300.0,
|
||
"bill_count": 10
|
||
},
|
||
"total_count": 1,
|
||
"current_page": 1,
|
||
"page_size": 20,
|
||
"items": []
|
||
}
|
||
}
|
||
```
|
||
|
||
## 2. 结算单预览
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_preview.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
创建结算单前预览明细，检查指定账期是否已有结算单，并返回可结算账单明细。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
|
||
| `counterparty_type` | 是 | string | `supplier` 或 `reseller` |
|
||
| `counterparty_orgid` | 是 | string | 供应商或分销商机构 ID |
|
||
| `period_type` | 否 | string | `day` 或 `month`，默认 `day` |
|
||
| `period_start` | 是 | string | 账期开始日期 |
|
||
| `period_end` | 是 | string | 账期结束日期 |
|
||
| `current_page` | 否 | number | 页码，默认 `1` |
|
||
| `page_size` | 否 | number | 每页数量，默认 `50` |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"accounting_orgid": "org001",
|
||
"counterparty_type": "reseller",
|
||
"counterparty_orgid": "reseller001",
|
||
"period_type": "month",
|
||
"period_start": "2026-06-01",
|
||
"period_end": "2026-06-30"
|
||
}
|
||
```
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.can_create` | 是否可以创建结算单 |
|
||
| `data.existing_settlement` | 已存在结算单信息，没有则为 `null` |
|
||
| `data.summary` | 汇总金额 |
|
||
| `data.items[]` | 账单明细 |
|
||
| `data.items[].bill_id` | 账单 ID |
|
||
| `data.items[].order_id` | 订单 ID |
|
||
| `data.items[].bill_date` | 账单日期 |
|
||
| `data.items[].sale_mode` | 销售模式，`0` 折扣，`1` 代付费，`2` 底价 |
|
||
| `data.items[].sales_amount` | 销售金额 |
|
||
| `data.items[].settlement_amount` | 结算金额 |
|
||
| `data.items[].platform_income_amount` | 平台收入 |
|
||
|
||
## 3. 创建结算单
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_create.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
创建结算单主表和明细快照。创建后状态为 `draft`。同一账本机构、对手方、账期不能重复创建。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
|
||
| `counterparty_type` | 是 | string | `supplier` 或 `reseller` |
|
||
| `counterparty_orgid` | 是 | string | 供应商或分销商机构 ID |
|
||
| `period_type` | 否 | string | `day` 或 `month`，默认 `day` |
|
||
| `period_start` | 是 | string | 账期开始日期 |
|
||
| `period_end` | 是 | string | 账期结束日期 |
|
||
| `userid` | 否 | string | 当前操作用户 ID |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"accounting_orgid": "org001",
|
||
"counterparty_type": "supplier",
|
||
"counterparty_orgid": "supplier001",
|
||
"period_type": "day",
|
||
"period_start": "2026-06-01",
|
||
"period_end": "2026-06-01",
|
||
"userid": "user001"
|
||
}
|
||
```
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.settlement_id` | 结算单 ID |
|
||
| `data.settlement_no` | 结算单号 |
|
||
| `data.status` | 初始状态，固定为 `draft` |
|
||
| `data.summary` | 创建时锁定的汇总金额 |
|
||
|
||
## 4. 结算单列表
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_list.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
分页查询结算单主表数据。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
|
||
| `counterparty_type` | 否 | string | `supplier` 或 `reseller` |
|
||
| `counterparty_orgid` | 否 | string | 对手方机构 ID |
|
||
| `status` | 否 | string | 结算单状态 |
|
||
| `period_type` | 否 | string | `day` 或 `month` |
|
||
| `start_date` | 否 | string | 账期范围开始 |
|
||
| `end_date` | 否 | string | 账期范围结束 |
|
||
| `current_page` | 否 | number | 页码，默认 `1` |
|
||
| `page_size` | 否 | number | 每页数量，默认 `20` |
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.total_count` | 总数 |
|
||
| `data.current_page` | 当前页 |
|
||
| `data.page_size` | 每页数量 |
|
||
| `data.items[]` | 结算单列表 |
|
||
|
||
`items[]` 中主要字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `id` | 结算单 ID |
|
||
| `settlement_no` | 结算单号 |
|
||
| `counterparty_type` | 对手方类型 |
|
||
| `counterparty_orgid` | 对手方机构 ID |
|
||
| `counterparty_name` | 对手方名称 |
|
||
| `period_start` | 账期开始 |
|
||
| `period_end` | 账期结束 |
|
||
| `sales_amount` | 销售金额 |
|
||
| `settlement_amount` | 结算金额 |
|
||
| `platform_income_amount` | 平台收入 |
|
||
| `status` | 结算单状态 |
|
||
| `approval_id` | 审批 ID |
|
||
|
||
## 5. 结算单详情
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_detail.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
查询结算单主表和明细快照。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `settlement_id` | 是 | string | 结算单 ID |
|
||
| `current_page` | 否 | number | 明细页码，默认 `1` |
|
||
| `page_size` | 否 | number | 明细每页数量，默认 `100` |
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.settlement` | 结算单主表 |
|
||
| `data.detail_total_count` | 明细总数 |
|
||
| `data.items[]` | 结算明细快照 |
|
||
|
||
## 6. 提交审批
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_submit.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
将 `draft`、`rejected`、`failed` 状态的结算单提交审批。提交成功后状态更新为 `approving`，并写入 `approval_id`。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `settlement_id` | 是 | string | 结算单 ID |
|
||
| `userid` | 是 | string | 当前操作用户 ID |
|
||
| `business_name` | 否 | string | 审批业务名，默认 `财务结算` |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"settlement_id": "settlement001",
|
||
"userid": "user001",
|
||
"business_name": "财务结算"
|
||
}
|
||
```
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.settlement_id` | 结算单 ID |
|
||
| `data.approval_id` | 审批实例 ID |
|
||
| `data.status` | `approving` |
|
||
|
||
注意：
|
||
|
||
- `apv_business` 表中需要存在 `business_name='财务结算'` 的审批业务配置。
|
||
- 当前账本机构下需要存在角色为 `财务` 的审批用户。
|
||
|
||
## 7. 审批回调
|
||
|
||
接口：
|
||
|
||
```text
|
||
/bill/finance_settlement_apv_callback.dspy
|
||
```
|
||
|
||
功能：
|
||
|
||
处理审批回调。审批通过后自动结算记账：
|
||
|
||
- 供应商结算：调用现有 `SettleAccounting`。
|
||
- 分销商结算：写入 `bill`、`bill_detail`、`accounting_log`、`acc_detail`、`acc_balance`。
|
||
|
||
入参：
|
||
|
||
| 字段 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `apv_id` | 是 | string | 审批实例 ID，也可传 `approval_id` |
|
||
| `status` | 是 | string | 审批状态 |
|
||
|
||
`status` 支持：
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `start` | 审批中 |
|
||
| `agree` | 审批通过，执行结算记账 |
|
||
| `refuse` | 审批拒绝 |
|
||
| `terminate` | 审批撤销 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"apv_id": "approval001",
|
||
"status": "agree"
|
||
}
|
||
```
|
||
|
||
出参：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data[].settlement_id` | 结算单 ID |
|
||
| `data[].status` | 处理后的状态 |
|
||
| `data[].failure_reason` | 失败原因，仅失败时返回 |
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"status": true,
|
||
"msg": "ok",
|
||
"data": [
|
||
{
|
||
"settlement_id": "settlement001",
|
||
"status": "settled"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 8. 页面
|
||
|
||
浅色科技风财务结算页面，包含：
|
||
|
||
- 汇总查询
|
||
- 平台收入展示
|
||
- 结算单预览
|
||
- 创建结算单
|
||
- 结算单列表
|
||
- 结算单详情
|
||
- 提交审批
|
||
- 审批回调
|