添加文件: intelligence_finance_v1/refine.md

intelligence_finance_v1/refine.md

@@ -0,0 +1,419 @@
+## 文档概述
+- 接口总数：5个（3个请求接口 + 2个通知/查询接口）
+- 文档包含：业财连接接口规范（认证机制）、订单开票接口、付款单据接口
+
+## 认证与安全
+
+### 请求接口（平台提供的接口）
+- 请求方法：`POST`
+- 测试地址：（未提供具体地址）
+- 接口短码：接口对接时分配
+
+#### 请求头（Header）
+| Header名 | 说明 | 必填 |
+|----------|------|------|
+| tenant-id | 平台分配的租户唯一标识 | 是 |
+| client-id | 平台分配的应用标识，钉钉AI表格固定为 `dd-ai-table` | 是 |
+| x-bfl-signature-timestamp | 请求时间戳，超5分钟丢弃（钉钉AI表格无需配置） | 否 |
+| x-bfl-signature-nonce | 唯一随机数（钉钉AI表格无需配置） | 否 |
+| x-bfl-signature | 签名信息（钉钉AI表格无需配置） | 否 |
+
+#### 响应数据（通用结构）
+| 字段名称 | 类型 | 是否必填 |
+|---------|------|---------|
+| code | Integer | 是 |
+| msg | String | 否 |
+| data | Object | 否 |
+
+### 认证机制
+- 平台为每个应用分配 `client-id` 和 `client-secret`。
+- **客户应用**：使用 `client-secret` 对 `(timestamp + nonce)` 进行签名。
+- **钉钉AI表格**：将 `client-secret` 配置为 `APPSecret`，签名由AI表格自动完成。
+
+#### 客户应用签名算法
+- 算法：`HmacSHA256`
+- 密钥：`client-secret`
+- 签名数据：`x-bfl-signature-timestamp` + `x-bfl-signature-nonce`
+- 结果编码：Base64
+- 代码示例（Java）：PDF中附有示例代码，主要实现HmacSHA256签名并Base64编码
+
+## 通知机制（客户提供接口，平台调用）
+- 请求方法：`POST`
+- 请求地址：由客户提供，在平台配置
+- 验签密钥：由客户提供，在平台配置
+
+#### 通知数据
+| 字段名称 | 类型 | 是否必填 |
+|---------|------|---------|
+| bizType | String | 是 |
+| bizId | String | 是 |
+| data | String | 否 |
+
+#### 通知响应
+响应BODY直接返回字符串：
+- `SUCCESS`：成功
+- `FAILED`：失败
+
+---
+
+## 接口列表
+
+### 接口 1：订单开票
+- 路径：未提供具体路径（接口短码对接时分配）
+- 方法：POST
+- 描述：提交订单开票请求
+
+#### 请求参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| companyCode | String | 否 | 开票的企业主体编码，不传则默认主体开票 |
+| orderId | String | 是 | 订单唯一标识（需保证在贵方系统内唯一） |
+| invoiceType | Integer | 是 | 发票类型枚举：1-专用发票；2-普通发票；3-普通发票(电子)；4-专用发票(电子)；8-数电专票；9-数电普票 |
+| products | List\<Object\> | 是 | 货物/服务明细列表，至少一项 |
+| remark | String | 否 | 订单备注（非发票备注） |
+| purchaser | String | 是 | 购方企业名称 |
+| taxnum | String | 否 | 购方纳税人识别号 |
+| purchaserAddress | String | 否 | 购方地址 |
+| purchaserTel | String | 否 | 购方电话 |
+| bankName | String | 否 | 购方开户行名称 |
+| bankAccount | String | 否 | 购方银行账号 |
+| phone | String | 否 | 收票人手机号（用于接收电票短信） |
+| email | String | 否 | 收票人邮箱（用于接收电票邮件） |
+| applyPerson | String | 否 | 开票申请人名称 |
+| payee | String | 否 | 收款人（发票票面） |
+| reviewer | String | 否 | 复核人（发票票面） |
+| invoiceRemark | String | 否 | 发票备注栏内容 |
+| naturalPerson | String | 否 | 购买方自然人标识：Y-是，N-否（默认N），数电票可选传 |
+| additionInfo | String | 否 | 附加信息（JSON数组字符串） |
+
+**products明细项：**
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| productName | String | 是 | 货物或服务名称 |
+| revenueCode | String | 是 | 19位税收分类编码 |
+| amountIncludeTax | BigDecimal | 是 | 单条明细含税总金额（单位：元） |
+| specs | String | 否 | 规格型号 |
+| unit | String | 否 | 计量单位（如：台、个、次） |
+| quantity | BigDecimal | 是 | 数量 |
+| discount | BigDecimal | 否 | 折扣金额（无折扣传0） |
+| taxSign | Integer | 否 | 是否含税：0-不含税；1-含税（默认建议传1） |
+| taxRate | BigDecimal | 否 | 税率（小数形式，如0.13表示13%） |
+
+**additionInfo 附加信息说明：** 该字段为JSON数组字符串，用于数电发票备注栏展示附加信息。使用前需在智能财务后台维护附加信息模板，且名称和类型必须匹配。
+
+#### 响应参数
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| status | Integer | 是 | 开票状态：0-未开票；1-开票中；2-部分失败；3-开票成功；4-开票失败；5-部分未开；6-未配置数电账号；7-未配置自动开票配置 |
+| errorMsg | String | 否 | 错误信息（开票失败时返回原因） |
+| dataList | List\<Object\> | 是 | 发票数据列表（一张订单可能对应多张发票） |
+
+**data中每条发票的详细字段：**
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| deviceCode | String | 是 | 税控设备号 |
+| drawer | String | 是 | 开票人 |
+| email | String | 是 | 邮箱（购方邮箱） |
+| invoiceType | String | 是 | 发票类型：1-专用发票；2-普通发票；3-普通发票（电子）；4-专用发票（电子）；8-数电专票；9-数电普票 |
+| issueType | String | 是 | 开票类型：0-正数票；1-负数票（红冲） |
+| listFlag | String | 是 | 清单标识：0-无清单；1-有清单 |
+| mobile | String | 是 | 手机号（购方手机） |
+| originalInvCode | String | 否 | 红冲时对应的原蓝票代码 |
+| originalInvNo | String | 否 | 红冲时对应的原蓝票号码 |
+| additionInfo | String | 否 | 数电发票备注栏的附加信息部分 |
+| payee | String | 是 | 收款人 |
+| purchaserAddress | String | 是 | 购方地址 |
+| purchaserBankAccount | String | 是 | 购方银行账号 |
+| purchaserBankName | String | 是 | 购方开户行 |
+| purchaserName | String | 是 | 购方名称 |
+| purchaserTaxNo | String | 是 | 购方税号 |
+| purchaserTel | String | 是 | 购方电话 |
+| naturalPerson | String | 否 | 购买方自然人标识：Y-是；N-否 |
+| remark | String | 是 | 备注 |
+| reviewer | String | 是 | 复核人 |
+| sellerAddress | String | 否 | 销方地址 |
+| sellerBankAccount | String | 是 | 销方开户账号 |
+| sellerBankName | String | 是 | 销方开户行 |
+| sellerName | String | 是 | 销方名称 |
+| checkCode | String | 是 | 校验码 |
+| cipherText | String | 是 | 密码区 |
+| drewDate | String | 否 | 开票日期（格式：yyyy-MM-dd HH:mm:ss） |
+| invoiceCode | String | 是 | 发票代码 |
+| invoiceNo | String | 是 | 发票号码 |
+| invoiceStatus | String | 是 | 发票状态：1-正常；2-已红冲；3-已作废 |
+| layoutFileUrl | String | 否 | 电子发票地址（PDF/OFD） |
+| pdfUrl | String | 否 | 电子发票PDF地址 |
+| ofdUrl | String | 否 | 电子发票OFD地址 |
+| xmlUrl | String | 否 | 电子发票XML数据地址 |
+| totalExcludeTax | String | 是 | 合计金额（不含税） |
+| totalIncludeTax | String | 是 | 合计金额（含税） |
+| totalTaxAmount | String | 是 | 合计税额 |
+| levyingType | String | 是 | 征税方式 |
+| details | List\<Object\> | 是 | 商品明细列表 |
+
+**details商品明细列表：**
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| amount | String | 否 | 金额 |
+| quantity | String | 否 | 数量 |
+| deductionAmount | String | 否 | 扣除金额 |
+| taxAmount | String | 否 | 税额 |
+| itemTitle | String | 是 | 商品合并显示名称 |
+| taxCode | String | 是 | 税收分类编码（19位） |
+| itemType | String | 是 | 商品行性质：0-正常行；1-折扣行；2-被折扣行 |
+| itemName | String | 是 | 商品简称 |
+| specs | String | 否 | 商品规格型号 |
+| taxFreePolicy | String | 是 | 免税政策：1-免税；2-不征税；3-普通零税率 |
+| preferentialPolicy | String | 是 | 优惠政策类型：0-不使用；1-不征税；2-免税；3-先征后退；4-100%先征后退；5-50%先征后退；6-简易征收；7-即征即退30%；8-即征即退50%；9-即征即退70%；10-即征即退100%；11-超税负3%即征即退；12-稀土产品；13-超税负8%即征即退；14-按5%简易征收减按1.5%计征；15-按5%简易征收；16-按3%简易征收；17-超税负12%即征即退 |
+| taxRate | String | 是 | 税率（小数形式，如0.13） |
+| taxSign | String | 是 | 是否含税：0-否；1-是 |
+| unit | String | 否 | 计量单位（如：台、个、次） |
+| unitPrice | String | 否 | 单价 |
+
+---
+
+### 接口 2：开票状态查询
+- 路径：未提供具体路径
+- 方法：POST
+- 描述：查询订单开票状态
+
+#### 请求参数
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| orderId | String | 是 | 订单唯一标识（需保证在贵方系统内唯一） |
+
+#### 响应参数
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| status | Integer | 开票状态（枚举同回调：0-未开票，3-成功，4-失败，6-未配置数电账号，7-未配置自动开票） |
+| message | String | 状态描述（如"开票成功"） |
+| data | List\<Object\> | 发票详细列表，结构与回调中的data字段一致 |
+
+---
+
+### 接口 3：创建付款单据
+- 路径：未提供具体路径
+- 方法：POST
+- 描述：创建付款单据
+
+#### 请求参数
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 是 |
+| yidaAppType | string | 否 |
+| empAccountUserId | string | 否 |
+| department | Department | 否 |
+| usage | string | 否 |
+| paymentUserId | string | 否 |
+| customer | Customer | 否 |
+| principalId | string | 否 |
+| remark | string | 否 |
+| supplier | Supplier | 否 |
+| title | string | 否 |
+| project | Project | 否 |
+| paymentUserIdListStr | string | 否 |
+| needPayment | boolean | 否 |
+| paymentDetailListJsonStr | string | 否 |
+| paymentDetailList | array\<PaymentDetail\> | 否 |
+| company | Company | 否 |
+| amount | string | 否 |
+| recipientAccountInfo | RecipientAccount | 否 |
+| enterpriseAccount | EnterpriseAccount | 否 |
+| category | array\<Category\> | 否 |
+| userId | string | 是 |
+| occurDate | number | 否 |
+| product | Product | 否 |
+| yidaFormUuid | string | 否 |
+| canEditPaymentInfo | boolean | 否 |
+| paymentUserIdList | array(string) | 否 |
+| yidaProcInsId | string | 否 |
+| syncPaymentOrder | boolean | 否 |
+
+**部门信息 Department**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**客户信息 Customer**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**供应商信息 Supplier**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**项目信息 Project**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**收支类别信息 Category**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**商品信息 Product**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**企业主体信息 Company**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 否 |
+| name | string | 是 |
+
+**企业账号信息 EnterpriseAccount**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| enterpriseAccountCode | string | 否 |
+| accountCategory | string | 是 |
+| accountType | string | 否 |
+| cardNo | string | 否 |
+| accountName | string | 否 |
+| officialNumber | string | 否 |
+| officialName | string | 否 |
+| name | string | 否 |
+| code | string | 否 |
+| city | string | 否 |
+| province | string | 否 |
+
+**收款账户信息 RecipientAccount**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| accountCategory | string | 是 |
+| accountType | string | 否 |
+| cardNo | string | 否 |
+| accountName | string | 否 |
+
+**付款明细 PaymentDetail**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| amount | string | 否 |
+| invoiceInfo | InvoiceInfo | 否 |
+| productCode | string | 否 |
+| projectCode | string | 否 |
+| remark | string | 否 |
+| principalId | string | 否 |
+| tax | string | 否 |
+
+**付款明细发票信息 InvoiceInfo**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| invoiceNo | string | 否 |
+| invoiceCode | string | 否 |
+
+#### 响应参数
+| 字段名称 | 类型 | 是否必填 | 描述 |
+|----------|------|----------|------|
+| code | string | 是 | 单据唯一 |
+
+---
+
+### 接口 4：支付完成通知（平台回调客户接口）
+- 路径：由客户提供，在平台配置
+- 方法：POST
+- 描述：平台在支付完成后回调客户系统
+
+#### 通知数据
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 是 |
+| instanceId | string | 是 |
+| corpId | string | 是 |
+| paymentStatus | string | 是 |
+| paymentTime | string | 是 |
+| userId | string | 是 |
+| failReason | string | 否 |
+| payerAccountInfo | object | 否 |
+| payeeAccountInfo | object | 否 |
+| relatedRowNumberList | array(string) | 否 |
+| source | string | 否 |
+| template | string | 否 |
+| amount | string | 否 |
+
+**收款账户信息 payeeAccountInfo**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| bankOpenDTO | object | 否 |
+
+**付款账户信息 payerAccountInfo**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| bankOpenDTO | object | 否 |
+| enterpriseAccountCode | string | 否 |
+| accountType | string | 否 |
+
+**银行信息 bankOpenDTO**
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| bankCode | string | 否 |
+| bankName | string | 否 |
+| bankBranchCode | string | 否 |
+| bankBranchName | string | 否 |
+| accountName | string | 否 |
+| bankCardNo | string | 否 |
+| type | string | 否 |
+
+**支付状态 paymentStatus 枚举**
+| 枚举值 | 说明 |
+|--------|------|
+| SUCCESS | 支付成功 |
+| FAIL | 支付失败 |
+| TERMINATE | 支付取消 |
+| WAIT_PAY | 待支付 |
+| PAYING | 支付中 |
+| PART_SUCCESS | 部分支付成功 |
+| REFUND | 退款（仅支持付款账户是银行且是交通银行） |
+
+**来源 source 枚举**
+| 枚举值 | 说明 |
+|--------|------|
+| approval | 审批单 |
+| openapi | 开发接口 |
+
+**账户类型 type/accountType 枚举**
+| 枚举值 | 说明 |
+|--------|------|
+| ALIPAY | 支付宝 |
+| BANKCARD | 银行卡 |
+| CORP_BANK_CARD | 对公银行卡 |
+| PERSONAL_BANK_CARD | 对私银行卡 |
+
+#### 通知响应
+响应BODY直接返回字符串：
+- `SUCCESS`：成功
+- `FAILED`：失败
+
+---
+
+### 接口 5：支付状态查询
+- 路径：未提供具体路径
+- 方法：POST
+- 描述：查询支付状态
+
+#### 请求参数
+| 字段名 | 字段类型 | 是否必填 |
+|--------|----------|----------|
+| code | string | 是 |
+| userId | string | 是 |
+
+#### 响应参数
+响应数据与支付通知一样（即接口4的通知数据结构）
+
+## 错误码
+- 文档未提供明确的错误码表。通用响应结构为：`code`（Integer，必填）、`msg`（String，可选）、`data`（Object，可选）。
+- 开票状态枚举（status）：0-未开票；1-开票中；2-部分失败；3-开票成功；4-开票失败；5-部分未开；6-未配置数电账号；7-未配置自动开票配置
+- 通知响应：`SUCCESS`（成功）/ `FAILED`（失败）
+
+## 回调通知（如有）
+1. **通用通知机制**：客户提供接口，平台调用。请求方法POST，验签密钥由客户提供并在平台配置。通知数据：bizType（String，必填）、bizId（String，必填）、data（String，可选）。响应BODY直接返回字符串 `SUCCESS` 或 `FAILED`。
+2. **支付完成通知**：平台在支付完成后回调客户系统，通知数据结构见接口4，响应BODY直接返回字符串 `SUCCESS` 或 `FAILED`。