From 6a1ed50a7e0e4ce9b1ed3ccc1c7a3e712c9b54ef Mon Sep 17 00:00:00 2001 From: renzhiyuan <465386466@qq.com> Date: Mon, 17 Aug 2026 16:35:45 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E6=96=87=E4=BB=B6:=20intelli?= =?UTF-8?q?gence=5Ffinance=5Fv1=5Fga/refine.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- intelligence_finance_v1_ga/refine.md | 419 +++++++++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 intelligence_finance_v1_ga/refine.md diff --git a/intelligence_finance_v1_ga/refine.md b/intelligence_finance_v1_ga/refine.md new file mode 100644 index 0000000..2e56e09 --- /dev/null +++ b/intelligence_finance_v1_ga/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\ | 是 | 货物/服务明细列表，至少一项 | +| 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\ | 是 | 发票数据列表（一张订单可能对应多张发票） | + +**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\ | 是 | 商品明细列表 | + +**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\ | 发票详细列表，结构与回调中的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\ | 否 | +| company | Company | 否 | +| amount | string | 否 | +| recipientAccountInfo | RecipientAccount | 否 | +| enterpriseAccount | EnterpriseAccount | 否 | +| category | array\ | 否 | +| 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`。 \ No newline at end of file