## 文档概述
- 接口总数：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`。