文档概述

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