forked from erp-dev/erp
118 lines
3.4 KiB
Markdown
118 lines
3.4 KiB
Markdown
# 销售折扣数据（ZkJinE）接口更新说明
|
||
|
||
## 问题回顾
|
||
|
||
你们反馈 `/api/v1/i-sale/by-customer` 接口的 `ZkJinE` 字段始终返回 0，导致销售折扣金额（583 元部分）无法正确获取。
|
||
|
||
## 根因确认
|
||
|
||
经查证，问题属实但需要澄清：
|
||
|
||
- `/api/v1/i-sale/by-customer` 接口**确实返回了 `ZkJinE` 字段**，但该字段的数据来源是 `I_Sale` 表，而 `I_Sale` 表中该字段的值本身就是 0。这不是接口遗漏字段，而是数据源的问题。
|
||
- **真实的销售折扣数据**存在于 `F_Skd` 表中 `BianHaoID` 以 `XS` 开头的记录里。
|
||
|
||
## 解决方案
|
||
|
||
我们已在 `/api/v1/finance/by-customer` 接口新增了 `sale_discount` 类型，用于从 `F_Skd` 表查询 XS% 行的财务数据（包含 `ZkJinE`）。
|
||
|
||
**此改动为纯增量更新，不影响任何现有接口和字段。**
|
||
|
||
---
|
||
|
||
## 对接方式
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/v1/finance/by-customer?customer_name_b64={base64url编码的客户名}&record_types=sale_discount
|
||
```
|
||
|
||
也可以和其它类型组合使用：
|
||
|
||
```
|
||
GET /api/v1/finance/by-customer?customer_name_b64={base64url编码的客户名}&record_types=sale,sale_discount,receipt
|
||
```
|
||
|
||
### record_types 可选值
|
||
|
||
| 值 | 说明 | 数据来源 |
|
||
|---|---|---|
|
||
| `sale` | 成品销售单 | I_Sale 表 |
|
||
| `sale_return` | 客户退货单 | I_Sale 表 |
|
||
| `receipt` | 收款记录（SK%） | F_Skd 表 |
|
||
| `refund` | 退款记录（XT%） | F_Skd 表 |
|
||
| **`sale_discount`** | **销售折扣记录（XS%）** | **F_Skd 表** ← 新增 |
|
||
|
||
### 响应结构
|
||
|
||
新增字段（在原有响应基础上）：
|
||
|
||
```json
|
||
{
|
||
"mode": "customer_finance",
|
||
"customer_name": "客户名称",
|
||
"customer_ids": ["KH001"],
|
||
"record_types": ["sale_discount"],
|
||
"status": "active",
|
||
"snapshot_at": "2026-05-19T10:00:00Z",
|
||
"total_count": 5,
|
||
"sale_discounts_count": 5,
|
||
"sale_discounts": [
|
||
{
|
||
"BianHaoID": "XS20260101-001",
|
||
"KhID": "KH001",
|
||
"RiQi": "2026-01-01T00:00:00Z",
|
||
"KdRiQi": "2026-01-01T00:00:00Z",
|
||
"YfJinE": 1000.00,
|
||
"FkJinE": 800.00,
|
||
"ZkJinE": 200.00,
|
||
"JieSunFS": "...",
|
||
"YhID": "...",
|
||
"ZhaiYao": "...",
|
||
"BeiZhu": "..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### sale_discount 每条记录包含的字段
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `BianHaoID` | 单据编号（XS 开头） |
|
||
| `KhID` | 客户 ID |
|
||
| `RiQi` | 日期 |
|
||
| `KdRiQi` | 开单日期 |
|
||
| `YfJinE` | 应付金额 |
|
||
| `FkJinE` | 付款金额 |
|
||
| **`ZkJinE`** | **折扣金额（你们需要的字段）** |
|
||
| `JieSunFS` | 结算方式 |
|
||
| `YhID` | 银行 ID |
|
||
| `ZhaiYao` | 摘要 |
|
||
| `BeiZhu` | 备注 |
|
||
|
||
---
|
||
|
||
## 关于差额 816 的对账建议
|
||
|
||
根据你们的分析：
|
||
- receipt.ZkJinE = 233 → 通过 `record_types=receipt` 获取 ✅
|
||
- sales.ZkJinE = 583 → 现在通过 `record_types=sale_discount` 获取 ✅
|
||
|
||
建议对账时同时请求：
|
||
```
|
||
record_types=receipt,sale_discount
|
||
```
|
||
|
||
然后分别对 `receipts` 和 `sale_discounts` 数组中的 `ZkJinE` 字段求和，即可得到完整的折扣金额。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. `sale_discount` 不会包含在默认查询中。如果不传 `record_types` 参数，默认只返回 `sale, sale_return, receipt, refund` 四种类型（保持向后兼容）。
|
||
2. 请求 `sale_discount` 时不需要传 `include_cash_movement` 或 `include_adjustments` 参数，这两个参数只对 `receipt` 和 `refund` 类型生效。
|
||
3. `customer_name_b64` 使用 base64url 编码（无 padding），与之前的用法一致。
|
||
|
||
如有疑问请随时联系。
|