intelligence_finance_v1-20260817171812/README.md at f352a4349f2f02532a9a4bea6ddcdfdb7a84fac1

25 KiB

Raw Blame History

文档概述

接口总数：9个（订单开票2个、付款单据3个、供应商4个）
文档类型：业财连接接口规范（含请求接口与通知机制）

认证与安全

请求接口（平台提供，客户调用）

请求方法：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：订单开票

路径：未提供具体URL（接口短码对接时分配）
方法：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：开票状态查询

路径：未提供具体URL（接口短码对接时分配）
方法：POST
描述：查询订单开票状态

请求参数

字段名	类型	是否必填	字段说明
orderId	String	是	订单唯一标识（需保证在贵方系统内唯一）

响应参数

字段名	类型	字段说明
status	Integer	开票状态（枚举同回调：0-未开票，3-成功，4-失败，6-未配置数电账号，7-未配置自动开票）
message	String	状态描述（如"开票成功"）
data	List<Object>	发票详细列表，结构与回调中的data字段一致

接口 3：创建付款单据

路径：未提供具体URL（接口短码对接时分配）
方法：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：支付状态查询

路径：未提供具体URL（接口短码对接时分配）
方法：POST
描述：查询支付状态

请求参数

字段名	字段类型	是否必填
code	string	是
userId	string	是

响应参数

响应数据与支付通知一样（即接口4的通知数据结构）

接口 6：创建供应商

路径：未提供具体URL（接口短码对接时分配）
方法：POST
描述：创建供应商

请求参数

名称	类型	是否必填	描述
invokeId	String	否	请求ID
userId	String	是	员工ID
data	String	否	Array字符串
bizType	String	是	固定

业务数据 BizData

字段	类型	是否必填	说明
corpId	String	是	企业ID
creator	String	是	创建该供应商的员工userid
supplierInfo	SupplierInfo	否	供应商

供应商数据 SupplierInfo

字段	类型	是否必填	说明
name	String	是	供应商名称
corpId	String	是	企业ID
userDefineCode	String	否	用户自定义编码
description	String	否	备注
contactAddress	String	否	地址
contactCompanyTelephone	String	否	公司电话
contactEmail	String	否	邮箱
contactName	String	否	联系人
contactTelephone	String	否	手机号
creator	String	是	创建该供应商的员工userid
invoiceAccount	String	否	银行卡号
invoiceAddress	String	否	发票地址
invoiceBankName	String	否	银行支行、开户行
invoiceName	String	否	发票信息-发票抬头
invoiceTaxNo	String	否	税号
purchaserTel	String	否	发票电话
bankName	String	否	银行总行名称
invoiceTelephone	String	否	发票信息-电话
accountName	String	否	户名
accountType	String	否	账户类型

响应参数

名称	类型	是否必填	描述
invokeId	String	否	请求ID
bizType	String	是	固定
data	String	否	响应数据

响应数据 ResponseData

名称	类型	是否必填	描述
result	String	否	钉钉
success	Boolean	是	true

供应商信息（响应）

字段	类型	是否必填	说明
supplierId	String	是	钉钉供应商ID
supplierName	String	是	钉钉供应商名称
name	String	是	供应商名称
corpId	String	是	企业ID
userDefineCode	String	否	用户自定义编码
description	String	否	备注
contactAddress	String	否	地址
contactCompanyTelephone	String	否	公司电话
contactEmail	String	否	邮箱
contactName	String	否	联系人
contactTelephone	String	否	手机号
creator	String	是	创建该供应商的员工userid
invoiceAccount	String	否	银行卡号
invoiceAddress	String	否	发票地址
invoiceBankName	String	否	银行支行、开户行

接口 7：根据名称查询供应商

路径：未提供具体URL（接口短码对接时分配）
方法：POST
描述：根据供应商名称查询供应商

请求参数

名称	类型	是否必填	描述
invokeId	String	否	请求ID
userId	String	是	员工ID
data	String	否	Array<QueryByName>
bizType	String	是	固定：query_supplier_by_name

业务数据 QueryByName

字段	类型	是否必填	说明
corpId	String	是	企业ID
name	String	是	供应商名称

响应参数

名称	类型	是否必填	描述
invokeId	String	否	请求ID
bizType	String	是	固定：query_supplier_by_name
data	String	否	响应数据
result	String	否	钉钉
success	Boolean	是	true

重要字段介绍

字段	类型	说明
supplierName	String	供应商名称
userDefineCode	String	用户自定义供应商编码
invoiceName	String	开户行
supplierId	String	供应商唯一标识
corpId	String	企业id
contactTelephone	String	手机号
contactEmail	String	邮箱
contactName	String	联系人姓名
invoiceBankName	String	开户行
invoiceAccount	String	账户
description	String	备注
invoiceAddress	String	发票地址
invoiceTaxNo	String	税号
contactCompanyTelephone	String	公司电话
createTime	Number	创建时间（时间戳）
invoiceTelephone	String	发票电话
contactAddress	String	地址

接口 8：更新供应商

路径：未提供具体URL（接口短码对接时分配）
方法：POST
描述：更新供应商信息

请求参数

名称	类型	是否必填	描述
invokeId	String	否	业务调用ID
userId	String	是	员工ID
data	String	否	业务数据
bizType	String	是	固定：update_supplier

业务数据 BizData

字段	类型	是否必填	说明	示例
supplierId	String	是	供应商ID	SUP_XXXXX
name	String	是	供应商名称，最长64字符	王经理
corpId	String	是	企业ID	dingXXXXXX
userDefineCode	String	否	用户自定义编码	XXXXX
description	String	否	备注，最长512字符	长期合作
contactAddress	String	否	地址，最长128字符	xx路xx号
contactCompanyTelephone	String	否	公司电话，最长64字符	1888888
contactEmail	String	否	邮箱，最长64字符	a@aa.com
contactName	String	否	联系人，最长64字符	张三
contactTelephone	String	否	手机号，最长64字符	1888888
userId	String	是	修改该供应商的员工userid	04221***
invoiceAccount	String	否	银行卡号，最长64字符	6222222222231321323
invoiceAddress	String	否	发票地址，最长200字符	xx路xx号
invoiceBankName	String	否	银行支行、开户行，最长200字符	建设银行xx支行
invoiceName	String	否	发票信息-发票抬头，最长64位	浙江xxx科技有限责任公司
invoiceTaxNo	String	否	税号，最长30字符	1231231231231231
purchaserTel	String	否	发票电话，最长20字符	0571-12345678
bankName	String	否	银行总行名称	中国建设银行
invoiceTelephone	String	否	发票信息-电话，最长64位	166888888
accountName	String	否	户名	XXXX
accountType	String	否	账户类型对公/对私；私：PERSONAL_BANK_CARD；对公：CORP_BANK_CARD	CORP_BANK_CARD
bankBranchCode	String	否	银行支行联行号信息，如果传递需要准确	-
bankCode	String	否	银行CODE，例如ICBC	ICBC
bankCity	String	否	银行卡城市	杭州
bankProvince	String	否	银行卡省份	浙江

响应参数

名称	类型	是否必填	描述
invokeId	String	否	请求ID
bizType	String	是	固定：update_supplier
data	String	否	响应数据

响应数据 ResponseData

名称	类型	是否必填	描述
result	String	否	返回
success	Boolean	是	true

接口 9：根据用户自定义编码查询供应商信息

路径：未提供具体URL（接口短码对接时分配）
方法：POST
描述：根据用户自定义编码查询供应商

请求参数

名称	类型	是否必填	描述
invokeId	String	否	业务调用ID
userId	String	是	员工ID
data	String	否	业务数据
bizType	String	是	固定：query_supplier_by_userDefineCode

业务数据 BizData

字段	类型	是否必填	说明
corpId	String	是	企业ID
userDefineCode	String	是	用户自定义编码

响应参数

名称	类型	是否必填	描述
invokeId	String	否	请求ID
bizType	String	是	固定：query_supplier_by_userDefineCode
data	String	否	响应数据

响应数据 ResponseData

名称	类型	是否必填	描述
success	Boolean	是	true

重要字段介绍

字段	类型	说明
userDefineCode	String	用户自定义供应商编码
supplierName	String	供应商名称
modifiedTime	Number	数据最新修改时间戳（毫秒）
creator	String	创建该供应商的员工userid
supplierId	String	供应商唯一标识
code	String	供应商编码
corpId	String	企业ID（钉钉企业corpId）
createTime	Number	创建时间（时间戳，毫秒）
name	String	供应商名称（冗余字段，同supplierName）
id	Number	供应商内部数字ID
status	String	供应商状态（如valid表示有效）

错误码

文档未提供明确的错误码表。通用响应结构中的 code（Integer）与 msg（String）用于返回业务结果，具体错误码含义未在文档中说明。

回调通知（如有）

通用通知机制：客户提供接口地址与验签密钥，平台以 POST 调用。通知数据含 bizType、bizId、data，响应需返回字符串 SUCCESS 或 FAILED。
支付完成通知：平台在支付完成后回调客户，通知数据见接口4，响应返回 SUCCESS/FAILED。
开票状态回调：文档提及开票状态枚举"同回调"（0-未开票，3-成功，4-失败，6-未配置数电账号，7-未配置自动开票），但未提供开票回调的具体数据结构。

25 KiB Raw Blame History Unescape Escape

文档概述

认证与安全

请求接口（平台提供，客户调用）

请求头（Header）

通用响应结构

认证机制

客户应用签名算法

通知机制（客户提供接口，平台调用）

通知数据

通知响应

接口列表

接口 1：订单开票

请求参数

响应参数

接口 2：开票状态查询

请求参数

响应参数

接口 3：创建付款单据

请求参数

响应参数

接口 4：支付完成通知（平台回调客户）

通知数据

响应数据

接口 5：支付状态查询

请求参数

响应参数

接口 6：创建供应商

请求参数

响应参数

接口 7：根据名称查询供应商

请求参数

响应参数

接口 8：更新供应商

请求参数

响应参数

接口 9：根据用户自定义编码查询供应商信息

请求参数

响应参数

错误码

回调通知（如有）

25 KiB

Raw Blame History