ai_sdk
/
intelligence_finance_v1_ga-20260817161307
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
intelligence_finance_v1_ga-.../intelligence_finance_v1_ga/refine.md

16 KiB
Raw Blame History

文档概述

  • 接口总数：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。