b2894lxlx/tms-erp-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

:docs: 新增BFI推送入参取值映射表（含收票单往来类型固定客户）

Browse Source
This commit is contained in:
刘泉佳
2026-10-16 13:11:33 +08:00
parent 809977b5a6
commit 709c633dbb
1 changed files with 405 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/docs/业务流程/2026-10-15-金蝶（星瀚）BFI推送入参取值映射表（页面字段-表字段-配置对照）.md
+405
View File
@@ -0,0 +1,405 @@
# 金蝶（星瀚）BFI 推送入参取值映射表：页面字段 → 数据库表字段 / 配置对照
> 整理日期：2026-10-15
> 代码基线：`tms-api` 当前 master（分支 `feature/payment-apply-bfi-sync`，提交 `259407c3` 之后）。
> 用途：给联调/实施/排查用——每个送金蝶的入参，**页面上是哪个字段、落库在哪张表哪个字段、或来自哪个配置/常量**。逐字段核对代码（文件+行号见各节备注）。
> 配套文档：《2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.md》。
---
## 目录
- [0. 公共取数与通用规则](#0-公共取数与通用规则)
- [1. A100-1 获取令牌](#1-a100-1-获取令牌)
- [2. A902-2 客户保存](#2-a902-2-客户保存)
- [3. A801-5 黑名单查询](#3-a801-5-黑名单查询)
- [4. A102-2 财务应付单保存](#4-a102-2-财务应付单保存)
- [5. A302-2 财务应收单保存（与应付差异）](#5-a302-2-财务应收单保存与应付差异)
- [6. A103-1 付款申请下推](#6-a103-1-付款申请下推)
- [7. A103-3 预付款申请保存](#7-a103-3-预付款申请保存)
- [8. A303-1 开票申请单保存](#8-a303-1-开票申请单保存)
- [9. A303-2 收票单保存 + A302-6 指定应付](#9-a303-2-收票单保存--a302-6-指定应付)
- [10. A301-3 收款认领结果推送](#10-a301-3-收款认领结果推送)
- [11. lockBusiData 单据锁定](#11-lockbusidata-单据锁定)
- [12. A902 附件上传](#12-a902-附件上传)
- [13. 查询类接口入参简表](#13-查询类接口入参简表)
- [14. 与总纲记载不一致的核对结论](#14-与总纲记载不一致的核对结论)
---
## 0. 公共取数与通用规则
### 0.1 配置前缀（两套并存，勿混）
| 前缀 | 归属 | 内容 |
|---|---|---|
| `third-party.bfi.*` | bfi-api 客户端（令牌/网关） | baseUrl、authorization、clientId、clientSecret、username、accountId、language |
| `thirdparty.bfi.*` | blade-transport 业务 | srcSys、各业务开关/cron、payApply.*、invoiceApply.*、receivedInvoice.*、material.*、claimAnnounce.*、blacklist.*、billLock.*（宽松绑定兼容 camelCase） |
### 0.2 通用取数
| 项 | 规则 | 代码 |
|---|---|---|
| awrp_src_sys / systemsource / sourceSystem | Nacos `thirdparty.bfi.srcSys`，默认常量 `WLTMS` | BfiProperties(srcSys) |
| 组织 org/结算/付款/收款/申请组织 | 合同/申请单所属组织 → `SysCache.getDept()` → **部门金蝶组织编码**，空拦截 | `blade_contract_manage.organization_id` / 申请单 dept_id → `blade_dept.kingdee_dept_code`（KingdeeApBillSyncSupport.bfiOrgNumber L933-944） |
| 币种 | 合同结算币种，`RMB→CNY` | `blade_contract_manage.settlement_currency`（bfiCurrency L952-956） |
| 往来户 | 名称 → `blade_customer_archive` 按 `full_name/short_name` 匹配（limit 1）取 `customer_code`，查不到报错 | queryCustomerCode L966-984 |
| 日期文本 | 统一 `yyyy-MM-dd HH:mm:ss` | bfiDateTimeText L922-925 |
| 防重键 awrp_src_code | `ExternalSrcCodeSupport.buildSrcCode`：下划线拼接、去空白、去重保序 | ExternalSrcCodeSupport L54-63 |
### 0.3 分录拆分规则（A102-2/A302-2/A303-2 共用 `resolveEntryGroups`）
- 拆分维度：**货物 → 费用大类（装卸/运输）→ 税率** 三级分组，各组成一条分录；手动合计费用项（manual_flag=1）每行一条。
- 物料编码：装卸大类/手动非运费杂费 → `thirdparty.bfi.material.loading`（默认 XDWL11002004）；项目业务模式或业务类型含「国际」→ `.international`（Item-00001081）；国内按运单运输方式 → `.domestic.公路运输`=XDWL11010001 / `.铁路运输`=XDWL11010002 / `.水路运输`=XDWL11010003 / `.航空运输`=Item-00001082；运输方式未配置直接拦截。
- 税率：货物费用行按合同计费方案规则分组（`blade_contract_manage.billing_plan_json` 的 `rules[].feeType/feeItem/taxRate`）；税率未配置并入无税率组。
- 数量：运输类=结算明细运输量（≤0 兜底 1，同税率拆多行每行都取运输量）；装卸/合计费用项行=1；单价=金额÷数量反算（2 位 HALF_UP）。
- 0 元费用项（signum==0）与 0 元货物行整行跳过。
- 计量单位**当前不送**（DTO 有字段无赋值）。
---
## 1. A100-1 获取令牌
| 入参 | 含义 | 来源：配置键 / 生成方式 |
|---|---|---|
| client_id | 应用编码 | `third-party.bfi.clientId` |
| client_secret | 认证密钥 | `third-party.bfi.clientSecret` |
| username | 访问用户名 | `third-party.bfi.username` |
| accountId | 数据中心 ID | `third-party.bfi.accountId` |
| language | 语言 | `third-party.bfi.language`（默认 `zh_CN`） |
| nonce | 随机数 | 每次生成 `UUID` |
| timestamp | 时间戳（±5 分钟校验） | 每次生成 `yyyy-MM-dd HH:mm:ss` |
> 令牌缓存 Redis `blade:third:bfi:token`，TTL=expires_in−120s；`setIfAbsent` 写入。代码：BfiServiceImpl L136-156、BfiTokenDTO L44-65。
---
## 2. A902-2 客户保存
调用链：`CustomerArchiveServiceImpl.syncKingdee → pushCustomerToKingdee → CustomerBfiConverter.buildSaveDTO`
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 常量 |
|---|---|---|---|
| number | 客户编码（不传由星瀚生成） | 客商编号（提交时生成 KS+6 位） | blade_customer_archive.customer_code |
| name【必】 | 名称 | 客商名称 | blade_customer_archive.full_name |
| societycreditcode【必】 | 统一社会信用代码（金蝶候选键） | 统一社会信用代码 | blade_customer_archive.unified_credit_code |
| tx_register_no | 纳税人识别号 | 同上（同一字段） | blade_customer_archive.unified_credit_code |
| artificialperson | 法人代表 | 企业法人 | blade_customer_archive.legal_person |
| type【必】 | 伙伴类型（1~17） | 客商性质字典 | blade_customer_archive.customer_nature + 字典 `nature_of_client` dictKey（文本值反查 dictKey，无效抛异常） |
| bizpartner_address | 详细地址 | 注册地址 | blade_customer_archive.registered_address |
| bizpartner_phone | 联系电话 | 联系电话 | blade_customer_archive.contact_phone |
| businessterm | 营业期限 | 营业期限类型=长期→「长期」；否则「至 yyyy-MM-dd」 | blade_customer_archive.business_term_type / business_end_date |
| businessscope | 经营范围 | 经营范围多选 → 字典 `scope_of_business` 文本「、」拼接 | blade_customer_archive.business_scope |
| bizfunction | 业务职能 | 固定全选 | 常量 `"1,2,3,4"` |
| fcusbeizhu | 备注 | 备注（空不传） | blade_customer_archive.remark |
| awrp_datasourcesys | 数据来源 | 配置 | `thirdparty.bfi.srcSys` |
| awrp_cusfortrade【必】 | 是否贸易客商 | 固定 | 常量 `"A"` |
| entry_groupstandard[].standardid_number【必】 | 分类标准 | 固定 | 常量 `"JBFLBZ"` |
| entry_groupstandard[].groupid_number【必】 | 客户分组 | 客户类型：internal→1101，其余→1102 | blade_customer_archive.customer_kind + 常量 1101/1102 |
| entry_bank[].bankaccount | 银行账号（金蝶候选键） | 收款账号 | blade_customer_receipt_account.bank_account |
| entry_bank[].accountname | 账户名称 | **传开户行名称** | blade_customer_receipt_account.bank_name |
| entry_bank[].bank_number | 开户银行.编码（联行号） | 联行号 | blade_customer_receipt_account.cnaps_code |
| entry_bank[].currency_number【必】 | 币种 | 固定 | 常量 `"CNY"` |
| entry_bank[].isdefault_bank | 默认银行 | 固定 | `true` |
| entry_linkman[].contactperson | 联系人 | 客商负责人（空则整组分录不传） | blade_customer_archive.principal |
| entry_linkman[].phone | 电话 | 联系电话 | blade_customer_archive.contact_phone |
| entry_linkman[].isdefault_linkman | 默认联系人 | 固定 | `true` |
不传字段：status、linkman、establishdate、postal_code、createorg_number（已注释）等。
> 代码：CustomerBfiConverter L67-280、常量 CustomerBfiConstants / BfiConstant L288-313。
---
## 3. A801-5 黑名单查询
| 入参 | 含义 | 来源 |
|---|---|---|
| enable | 使用状态 | 固定 `"1"`（可用） |
| number | 企业税号数组 | 客商发票信息所有纳税人识别号，`trim().toUpperCase()` 去重 → blade_customer_invoice_info.tax_no |
| pageNo / pageSize | 分页 | 自动翻页（50 页保护）/ 固定 `2000` |
| name | 企业名称数组 | 不传 |
> 命中判定按应答 awrpCombofield：A 硬拦截；B 默认放行告警（`thirdparty.bfi.blacklist.blockRiskWarning=true` 时拦截）；查询异常上抛阻断提审。代码：CustomerArchiveServiceImpl L1043-1092、BfiConstant L90。
---
## 4. A102-2 财务应付单保存
### 4.1 单据头
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| awrp_src_code【必·候选键】 | 来源单据号（防重键） | 结算单号+结算明细单据号 | blade_formal_settlement.formal_settlement_no + blade_formal_settlement_detail.document_no（document_no 空兜底明细行 id）下划线拼接 |
| awrp_src_sys【必】 | 外部系统编号 | 配置 | `thirdparty.bfi.srcSys`（WLTMS） |
| awrp_src_type【必】 | 外部单据类型 | — | 常量 `TMS财务应付单` |
| billtypeid_number【必】 | 单据类型.编码 | — | 常量字典「服务采购应付」→ `ApFin_service_BT_S` |
| org_number / payorg_number【必】 | 结算/付款组织.编码 | 合同所属组织 | blade_contract_manage.organization_id → blade_dept.kingdee_dept_code |
| bizdate【必】 | 单据日期 | 同步当日 | LocalDate.now() |
| asstacttype【必】 | 往来类型 | — | 常量 `bd_customer`（固定，供应商分支已注释） |
| asstact_number【必】 | 往来户.编码 | 合同乙方 | blade_contract_manage.party_b → blade_customer_archive.customer_code |
| purmode【必】 | 付款方式 | — | 常量 `CASH`（现购） |
| currency_number【必】 | 结算币别 | 合同结算币种 | blade_contract_manage.settlement_currency（RMB→CNY） |
| payproperty_number【必】 | 款项性质.编码 | — | 常量 `2001`（材料采购） |
| isincludetax / ispricetotal | 含税价/总价录入 | — | `true` / `true` |
| isintax | 按应付金额分配 | — | `false` |
| exratedate / exchangerate | 汇率日期/汇率 | 结算单页面「汇率日期/结算汇率」，未维护不送 | blade_formal_settlement.exchange_rate_date / .exchange_rate |
| settlementtype_number | 结算方式 | **不送**（仅 A103-1 分录需要） | — |
| taxrateid_number / purorg_number / exratetable_number / planentity 等 | 可选 | **均不送**（planentity 由金蝶按分录自动汇总付款计划） | — |
### 4.2 明细分录 detailentry
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| awrp_entry_code【必·候选键】 | 分录标识 | 拆分行=`明细单据号-货物序号-大类-税率`；合计费用项行=`结算单号-费用类型-费用项` | blade_formal_settlement_detail.document_no / blade_formal_settlement_summary_fee.fee_type+fee_item |
| material_number【必】 | 物料编码.编码 | 按拆分规则映射（见 0.3） | 配置 `thirdparty.bfi.material.loading / international / domestic.公路运输 / .铁路运输 / .水路运输 / .航空运输`；判定字段 blade_project_apply.business_mode / business_type、blade_formal_settlement_detail.transport_type |
| awrp_transport | 运输货物 | 货物名称（合计费用项行不传） | blade_formal_settlement_detail.cargo_name（一车多货取 blade_formal_settlement_detail_fee.cargo_name） |
| awrp_lpn | 车号 | 车号（合计费用项行不传） | blade_formal_settlement_detail.vehicle_no |
| quantity【必】 | 数量 | 运输量（≤0 兜底 1；装卸/合计行=1） | blade_formal_settlement_detail.transport_quantity（一车多货取 detail_fee.transport_quantity） |
| price | 单价 | 金额÷数量反算 | 派生值 |
| e_pricetaxtotal【必】 | 应付金额（含税） | 结算金额 | blade_formal_settlement_detail.settlement_amount_tax / blade_formal_settlement_summary_fee.settlement_amount |
| e_amount | 金额（不含税） | 不含税结算金额（仅运输类携带；合计行不传） | blade_formal_settlement_detail.settlement_amount_no_tax |
| project_number【必】 | 项目.编码 | 联调临时值 | 常量 `"999"` |
| taxrateid_number | 税率.编码 | 不送（税率只作拆行依据） | blade_contract_manage.billing_plan_json |
---
## 5. A302-2 财务应收单保存（与应付差异）
分录与应付**同源同口径**（复用 resolveEntryGroups，分录字段名前缀 e_：e_material_number/e_quantity/e_unitprice/e_recamount(含税)/e_amount(不含税)）。头字段差异：
| 金蝶入参 | 应收取值 | 来源 |
|---|---|---|
| awrp_src_type | `TMS财务应收单` | 常量 |
| billtype_number | 「服务销售应收」→ `arfin_sersal_BT_S` | 常量映射 |
| recorg_number | 收款组织=结算组织 | 同 org_number |
| asstact_number | **结算单付款方**（非合同乙方） | blade_formal_settlement.payer_name → blade_customer_archive.customer_code |
| paymode | 现销 `CASH` | 常量 |
| payproperty_number | `1001`（一般销售） | 常量 |
| bizdate | 同步当日 | LocalDate.now() |
| settlementtype_number / duedate 等 | 不送（TODO 待金蝶确认） | — |
---
## 6. A103-1 付款申请下推
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| awrp_src_code【必·候选键】 | 来源单据号 | 付款申请单号 | blade_payment_application.payment_no |
| awrp_src_sys【必】 | 外部系统 | 配置 | `thirdparty.bfi.srcSys` |
| applydate【必】 | 申请日期 | 付款申请页-申请日期（空取当天） | blade_payment_application.apply_date |
| entry[].e_paymenttype_number【必】 | 付款类型 | 正式付款 | 常量 `201` |
| entry[].e_settlementtype_number | 结算方式 | 付款方式含「汇票」→`012-02`（电子银行承兑汇票），其余→`02`（银行转账） | 字典 `pay_method` + blade_payment_application.payment_method |
| entry[].awrp_finapbill_entryid【必】 | 勾稽应付单分录标识 | 主结算单应付单防重键（本地组装） | blade_formal_settlement.formal_settlement_no + blade_formal_settlement_detail.document_no（主结算单=blade_payment_application.settlement_id，空取关联明细首个结算单） |
| entry[].awrp_entry_code【必】 | 行 id | 付款申请号-1 | payment_no + "-1" |
| entry[].e_assacct【必】 | 往来账户（收款账号） | 收款账号 | blade_payment_application.bank_account |
| entry[].e_bebank_number【必】 | 往来银行.编码（联行号） | 收款账户联行号（缺失拦截；兜底按合同乙方客商+收款账号匹配） | blade_customer_receipt_account.cnaps_code（按 blade_payment_application.receipt_account_id 直查） |
| entry[].e_applyamount【必】 | 申请金额 | 申请付款金额（2 位 HALF_UP） | blade_payment_application.applied_amount |
| entry[].project_number【必】 | 项目.编码 | 联调临时值 | 常量 `"999"` |
| entry[].awrp_src_type【必】 | 外部单据类型 | 配置 | `thirdparty.bfi.payApply.srcType`（默认 `0KzXs`） |
| exratetable_number / awrp_textfield1 | 汇率表/付款渠道 | **实际不送**（仅 A103-3 送；配置 exratetable=01 在此接口不生效） | — |
---
## 7. A103-3 预付款申请保存
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| billtype_number【必】 | 单据类型 | 配置 | `thirdparty.bfi.payApply.billtype`（默认 `ap_payapply_oth_BT_S`） |
| settleorg/awrp_department/applyorg/payorg_number【必】 | 组织/部门 | 合同所属组织 | blade_contract_manage.organization_id → blade_dept.kingdee_dept_code |
| paycurrency/settlecurrency_number【必】 | 币种 | 合同结算币种（RMB→CNY） | blade_contract_manage.settlement_currency |
| applycause | 请款事由 | 按付款类型映射文案：项目垫资→「项目预付款申请」、进度垫资→「进度预付款申请」、结算付款→「结算付款申请」 | blade_payment_application.payment_type |
| exratetable_number【必】 | 汇率表 | 配置（**此接口实际送**） | `thirdparty.bfi.payApply.exratetable`（默认 `01`） |
| exratedate【必】 | 汇率日期 | 关联结算单维护值，兜底申请日期 | blade_formal_settlement.exchange_rate_date → blade_pre_settlement.exchange_rate_date → blade_payment_application.apply_date |
| awrp_textfield1 | 付款渠道 | 付款方式字典标签（**此接口实际送**） | 字典 `pay_method` 翻译 blade_payment_application.payment_method |
| entry[].e_paymenttype_number【必】 | 付款类型 | 结算付款→`201`；项目垫资/进度垫资→`202` | 常量 BFI_PAYMENT_TYPE_FORMAL / BFI_PAYMENT_TYPE_PREPAY |
| entry[].e_asstacttype / e_asstactnumber【必】 | 往来类型/户 | 固定客户 / 合同乙方→客商编码 | `bd_customer`；blade_contract_manage.party_b → customer_code |
| entry[].e_assacct / e_bebank_number【必】 | 账号/联行号 | 同 A103-1 | blade_payment_application.bank_account / blade_customer_receipt_account.cnaps_code |
| entry[].e_applyamount【必】 | 申请金额 | 申请付款金额 | blade_payment_application.applied_amount |
| entry[].project_number【必】 | 项目.编码 | **实际固定 999**（取项目档案真实编码的逻辑已注释停用） | 常量 `"999"`（备用：blade_project_apply.project_code） |
| entry[].e_remark | 备注 | 付款申请备注（空不传） | blade_payment_application.remark |
| entry[].awrp_entry_code / awrp_src_type【必】 | 行 id / 单据类型 | payment_no-1 / 配置 | `thirdparty.bfi.payApply.srcType` |
---
## 8. A303-1 开票申请单保存（每张发票张次一单）
### 8.1 主表
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| billno【必·候选键】 | 单据编号 | 开票申请单号（多张加张次序号） | blade_invoice_application.application_no（多张 + "-" + blade_invoice_application_sheet.sheet_no） |
| orgid_number / awrp_orgfield_number【必】 | 组织/申请部门 | 申请部门 | blade_invoice_application.dept_id → blade_dept.kingdee_dept_code |
| billdate【必】 | 单据日期 | 申请日期（空取当天） | blade_invoice_application.application_date |
| billproperties / taxationstyle / buyerproperty | 单据性质/征税方式/购方类型 | 固定 | `"1"` / `"0"` / `"0"` |
| invoicetype【必】 | 发票种类 | 发票类型：数电专票→`08xdp`，其余→`10xdp` | blade_invoice_application.invoice_type |
| buyeremail【必】 | 推送邮箱 | 部门邮箱（空拦截） | blade_invoice_application.department_emails |
| buyertaxno / buyername【必】 | 购方税号/名称 | 受票方快照 | blade_invoice_application.taxpayer_no / receiver_name |
| buyeraddr / buyerbank | 购方地址电话/开户行账号 | 受票方快照 | blade_invoice_application.registered_address+contact_phone / bank_name+bank_account |
| salername【必】 | 销方名称 | 开票单位（空拦截） | blade_invoice_application.issuer_name |
| salertaxno【必】 | 销方税号 | 开票单位→客商档案 | blade_customer_archive.unified_credit_code（按 issuer_name 匹配） |
| saleraddr / salerbank | 销方地址电话/开户行账号（数电专票强制） | 客商档案（启用开票信息优先） | blade_customer_archive.registered_address+contact_phone；blade_customer_invoice_info.bank_name+bank_account |
| totalamount【必】 | 申请价税合计 | 本张开票金额 | blade_invoice_application_sheet.invoice_amount |
| hsbz | 是否含税 | 固定不含税 | 常量 `"0"` |
| specialtype | 特殊票种 | 本张商品行**全部**为货物运输类→`E04`，否则→`00`（名称/分类含「运费/货物运输」关键字） | 常量 BFI_INVOICE_SPECIAL_TYPE_FREIGHT / NONE + BFI_INVOICE_FREIGHT_KEYWORDS |
| freights[] | 货物运输单据体（E04 报送） | 结算明细快照，见 8.2 | blade_invoice_application_detail |
| customnameid_number【必】 | 客户.编码 | 受票方客户 | blade_invoice_application.receiver_customer_id → blade_customer_archive.customer_code |
| awrp_project_number【必】 | 项目.编码 | 联调临时值 | 常量 `"999"` |
| awrp_src_bt | 上游单据类型 | 固定 | `ar_finarbill` |
| awrp_src_con_no | 上游单据号 | 首张关联结算单金蝶应收防重键 | blade_formal_settlement.formal_settlement_no + detail.document_no（经 blade_invoice_application_settlement 关联） |
| systemsource | 来源系统 | 配置 | `thirdparty.bfi.srcSys` |
| showbuyeraddresstel / showbuyerbank | 票面展示开关 | 固定 | `true` |
### 8.2 freights[]（按「车牌×起运×到达×货物×种类」去重归并，全空行剔除）
| 入参 | 来源：blade_invoice_application_detail 字段 |
|---|---|
| transporttype 运输工具种类 | transport_type（字典 `transport_type` 翻译，不在合法枚举兜底「其它运输工具」） |
| licenseplate 牌号 | vehicle_no |
| transportgoods 货物名称 | cargo_name |
| startplace 起运地 | departure_address |
| endplace 到达地 | arrival_address |
### 8.3 sim_original_bill_item[] 分录（blade_invoice_application_line 商品行，line_no 升序）
| 入参 | 来源：blade_invoice_application_line 字段 |
|---|---|
| awrp_entry_code【必】 | id（雪花 id） |
| rowtype / benchmark【必】 | 常量 `"2"`（商品行）/ `"0"`（数量基准） |
| goodsname【必】 | goods_name（货物或服务简称） |
| goodssimplename【必】 | goods_category（商品和服务分类） |
| taxratecodeid_number / goodscode【必】 | tax_classification_code（税收分类编码，空拦截） |
| num / unit | quantity（0 兜底 1）/ unit（空兜底「个」） |
| unitprice / amount / tax | unit_price_no_tax / amount_no_tax / tax_amount |
| taxrate | tax_rate（百分数÷100 转小数，0 送 "0.00"） |
| remark | remark |
| awrp_src_type【必】 | 配置 `thirdparty.bfi.invoiceApply.srcType`（默认 `0KzXs`） |
（specification 规格型号、含税金额等本期不传。）
---
## 9. A303-2 收票单保存 + A302-6 指定应付
### A303-2 收票单批量保存
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| awrp_src_code【必·候选键】 | 来源单据号 | 收票登记 id（一票一登记） | blade_invoice_receipt.id |
| awrp_src_sys / awrp_src_type【必】 | 系统/单据类型 | 配置 / 常量 | `thirdparty.bfi.srcSys`；`TMS收票登记` |
| invoiceno | 发票号码 | 收票登记发票号 | blade_invoice_receipt.invoice_no |
| receivedate【必】 | 收票日期 | 推送当日 | LocalDate.now() |
| issuedate【必】 | 开票日期 | 票池镜像票面 | blade_kingdee_invoice_pool.invoice_date |
| biztype【必】 | 业务类型 | 固定采购 | `PUR` |
| invoicetypef7_number【必】 | 发票类型.编码 | 票易通原始编码（缺失拦截并按票号回源 A801-1 补填） | blade_kingdee_invoice_pool.invoice_type_code |
| paymenttype【必】 | 付款方式 | 固定现购 | `CASH` |
| asstacttype【必】 | 往来类型 | 统一固定客户（与应付单/付款申请同口径） | `bd_customer` |
| org_number / currency_number【必】 | 组织/币种 | 分摊应付结算单关联合同 | blade_contract_manage.organization_id / settlement_currency |
| receivablessupp_number【必】 | 往来户.编码 | 合同乙方→客商编码 | blade_contract_manage.party_b → customer_code |
| exratetable_number【必】 | 汇率表 | 固定 | `"01"` |
| asstactname / buyertin / sellertin【必】 | 销方名称/购销方税号 | 票池镜像票面 | blade_kingdee_invoice_pool.issuer_name / buyer_tax_no / saler_tax_no |
| buyername【必】 | 购方名称 | 镜像受票单位 | blade_kingdee_invoice_pool.receiver_name |
| sellertel / sellerbank / selleracct | 销方电话/开户行/账号 | 镜像 | blade_kingdee_invoice_pool.phone / bank_name / bank_account |
| isincludetax | 含税录入 | 固定 | `true` |
| entry[] | 分录 | 与 A102-2 同源同口径（复用 resolveEntryGroups） | 同 4.2 |
### A302-6 收票指定应付
| 入参 | 来源 |
|---|---|
| op | 常量 `"assign"` |
| ap_invoice[0].awrp_src_code / awrp_src_sys | blade_invoice_receipt.id / `thirdparty.bfi.srcSys` |
| ap_finapbill[0].awrp_src_code / awrp_src_sys | 应付防重键（结算单号_明细单据号）/ 同上 |
---
## 10. A301-3 收款认领结果推送
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|---|---|---|---|
| billid【必】 | 认领公告 id | 流水同步落库（缺失拦截「请先同步金蝶收款流水」） | blade_kingdee_receipt_flow.bill_id |
| awrp_src_sys【必】 | 来源系统 | 配置 | `thirdparty.bfi.srcSys` |
| awrp_src_code【必】 | 来源单据编码 | 该流水全部分摊结算单号去重下划线拼接（推送时生成落库，分摊不变重试复用） | blade_receipt_claim_settlement.formal_settlement_no（status=1，结算单 id 升序）→ 回写 blade_kingdee_receipt_flow.awrp_src_code |
| recpaytype_number【必】 | 收款类型 | **常量当前值 `"999"`**（注释「示例 101 待金蝶确认」） | KingdeeBfiConstant.BFI_CLAIM_REC_PAY_TYPE |
| paymenttype【必】 | 付款人类型 | 固定 | `bd_customer` |
| recviewpayer / recpayer【必】 | 付款人名称/id | 流水付款方 | blade_kingdee_receipt_flow.payer_name / payer_id |
| entryentity[0].e_receivableamt【必】 | 应收金额（单条分录） | 全部有效认领分摊金额合计 | SUM(blade_receipt_claim_settlement.allocated_receipt_amount) |
| entryentity[0].seq / e_corebillno【必】 | 行序/核心单据编号 | 第一张分摊结算单 id / 其金蝶星瀚内码（缺失拦截「未同步金蝶」） | blade_receipt_claim_settlement.formal_settlement_id / blade_formal_settlement.kingdee_bill_id |
| entryentity[0].e_corebilltype | 核心单据类型 | **注释不传** | — |
---
## 11. lockBusiData 单据锁定
| 入参 | 含义 | 来源 |
|---|---|---|
| lockAction【必】 | 操作 | 常量 `LOCK` |
| sourceSystem【必】 | 源系统 | `thirdparty.bfi.srcSys`（默认 WLTMS） |
| targetSystem【必】 | 目标系统 | 常量 `XH` |
| operationType【必】 | 操作类型 | 常量 `SAVE` |
| sourceBillType【必】 | 源单据类型 | 见下表常量 |
| sourceBillNo【必】 | 本地单据号 | 见下表 |
| targetBillType【必】 | 金蝶单据类型 | 见下表 |
| targetBillNo【必】 | 金蝶单号（逐张） | 见下表 |
| operator | 操作人 | 当前用户名（定时/补偿兜底 `system`；补偿取 blade_kingdee_bill_lock.lock_operator） |
| time | 操作时间 | 当前时间 `yyyy-MM-dd HH:mm:ss` |
| sourceBillType | sourceBillNo | targetBillType | targetBillNo |
|---|---|---|---|
| `SETTLEMENT` | blade_formal_settlement.formal_settlement_no | receivable→`arfin_other_BT_S`；否则 `ApFin_other_BT_S` | 推送返回 billNo（多张逗号拆分逐张锁） |
| `PAY_APPLY` | blade_payment_application.payment_no | `ap_payapply_oth_BT_S` | blade_payment_application.kingdee_bill_no |
| `INVOICE_APPLY` | blade_invoice_application.application_no | `cdm_paybill_bank_elect_BT_S` | 推送返回 billNo（多张逗号拆分） |
| `RECEIVED_INVOICE` | — | `cdm_recbill_bank_BT_S` | 预留，**本期不锁** |
> 锁记录表 blade_kingdee_bill_lock（lock_status: failed/locked/unlocked，try_count≤5）；开关 `thirdparty.bfi.billLock.enabled`（默认 true）。代码：KingdeeBillLockServiceImpl L331-344、KingdeeLockConstant L24-87。
---
## 12. A902 附件上传
multipart 上传：`file`=文件流，`args`=JSON `{entityNumber, billPkId, controlKey}`。
| 入参 | 来源 |
|---|---|
| entityNumber（星止单据类型） | biz_type 映射：`pay_application`→ap_payapply；`formal_settlement_ap`→ap_finapbill；`formal_settlement_ar`→ar_finarbill；`invoice_application`→sim_original_bill；`invoice_receipt`→ap_invoice |
| billPkId（星瀚内码） | 推送落库的金蝶内码：blade_payment_application.kingdee_bill_id / blade_invoice_application.kingdee_bill_id / 结算单与收票推送返回内码（为空整单跳过待重推补传） |
| controlKey | 常量 `attachmentpanel` |
| 文件名 | 业务表 attachments_json 行内 originalName/name/fileName（空兜底 attachment；票池镜像兜底「发票文件」） |
| 文件流 | 业务表 attachments_json 的 url 下载；收票票池镜像按 path 经 A801-2 下载 |
- 附件存储：各业务单据 `attachments_json` 列（非 blade_attachment 表）；同步流水落 `blade_kingdee_attachment_sync`（biz_type/biz_id/attachment_key/kingdee_path/sync_status/fail_reason）。
- 单文件软限制 20MB，超限拦截（重推时跳过该件继续其余）。
- 调用时机：推送成功事务提交后联带上传，失败不污染主单状态；重推补传。
> 代码：KingdeeAttachmentConstant L45-108、KingdeeAttachmentSyncSupport L125-264、BfiServiceImpl L613-638。
---
## 13. 查询类接口入参简表
| 接口 | 关键入参 | 取值来源 / 常量 / 配置 |
|---|---|---|
| A102-4 应付单查询 | awrp_src_code 多值（50/批）、awrp_src_sys、pageSize 200 | 应付防重键批次；`thirdparty.bfi.srcSys` |
| A302-4 应收单查询 | 同上（50/批、200） | 应收防重键批次 |
| A103-2 付款申请单查询 | awrp_src_code=paymentNo（50/批）、pageSize 200 | blade_payment_application.payment_no |
| A103-4 付款处理查询 | org_number（优先取 A103-2 返回 payorg_number，兜底合同组织）、业务日期今天回溯 1 个月、200/页 | A103-2 返回值 → blade_dept.kingdee_dept_code |
| A303-4 开票申请查询 | billno 多值（application_no、-张次序号）、pageSize=max(张数,10) | blade_invoice_application(.sheet) |
| A303-5 开票发票查询（openApi） | serialNo=金蝶单号逗号拆分（≤50/批）、sellerTaxpayerId=开票单位税号、请求体 Base64 | blade_invoice_application.kingdee_bill_no；blade_customer_archive.unified_credit_code |
| A801-3 收票单查询 | buyername（按镜像受票单位分组）、modifytimeS/E=回看 30 天、200/页；本地按 srcCode=登记 id 匹配 | blade_kingdee_invoice_pool.receiver_name；`thirdparty.bfi.receivedInvoice.queryWindowDays/resultWindowDays`（默认 30）；blade_invoice_receipt.id |
| A801-1 票池查询 | invoiceStatus=`0`（正常票）；invoiceType 单值（白名单逐轮）；updateTime 窗口=incrementDays 增量、2.5 万触顶二分；500/页。**expenseStatus 不下推**（可用性本地过滤 amount_use_status=0 且 available_amount>0） | `thirdparty.bfi.invoiceReceipt.invoiceTypes / incrementDays`(30)；本地表 blade_kingdee_invoice_pool |
| A801-2 附件下载 | path=文件地址（镜像优先、实时回源兜底；优先级 pdfurl→taxPdfUrl→downloadUrl，fileType=4 判 OFD） | blade_kingdee_invoice_pool.attachments_json |
| A301-1 收款单查询 | 业务日期今天回溯 30 天、200/页；勾稽 sourcebillnumber==awrp_src_code | blade_kingdee_receipt_flow.awrp_src_code |
| A301-2 认领公告查询 | claimusers=**Nacos 配置值**（登录人入参已废弃）、modifytimeS/E=回溯 months 个月、200/页；billstatus 字段存在但不传 | `thirdParty.bfi.claimAnnounce.claimusers`（必配）、`.months`(6) |
---
## 14. 与总纲记载不一致的核对结论（已按代码核实）
| # | 事项 | 代码事实 |
|---|---|---|
| 1 | A103-1 的 exratetable_number / awrp_textfield1 | **实际不送**（L1245/L1249 注释）；配置 `payApply.exratetable=01` 只在 A103-3 生效 |
| 2 | A103-3 项目编码 | **实际固定 999**，「取项目档案 projectCode 真实编码」逻辑已注释停用（bfiProjectNumber L1508-1513）——总纲 12.2-#2「仅 A103-3 用真实编码」的说法作废，全部链路均为 999 |
| 3 | A301-3 recpaytype_number | 常量当前值 **"999"**（非旧文档写的 101；注释「示例 101 待金蝶确认」） |
| 4 | A301-2 claimusers | 只读 Nacos 配置，方法入参（当前登录人姓名）已不参与取值；billstatus 字段存在但不传 |
| 5 | A801-1 expenseStatus | 同步**不下推**（常量已定义未使用），「在用/已用票随窗口刷新」，可选票过滤在本地 SQL |
| 6 | 应付 asstact_number | 取**合同乙方 party_b**（payer_name 仅应收侧使用） |
> 校验提醒：以上配置键的**环境实际值**以 Nacos 为准（本文只列键名与代码默认值）；blade_* 表列名按 Entity 驼峰↔下划线约定标注，个别快照列以建表 SQL 为准。