保证金/押金开放接口总览

说明

保证金/押金开放能力不是单独新增一个查询接口，本次涉及保证金台账查询、外部凭证号更新，以及费用导入、费用更新、单据详情查询的字段扩展。

涉及接口

台账查询返回口径

保证金台账查询接口返回对外业务对象，不返回台账内码、费用内码、formDataCode、费用表单编码等内部字段。对象字段以业务编码和单号为主：

• 费用类型返回 expenseTypeBizCode。
• 预付款类型返回 noReceiptSubTypeBizCode。
• 往来单位返回 tradingPartnerBizCode。
• 公司抬头返回 legalEntityBizCode。
• 创建人返回 createdByEmployeeId。
• 关联合同单号返回 contractCodes 数组。
• 共享字段返回在 customObject 中，按 OpenAPI 字段格式转换。

预付款类型传参

费用导入/更新时，预付款类型仍放在 customObject 中，字段 key 以费用表单中“预付款类型”组件的业务编码为准；以下示例使用 noReceiptSubType。调用方传预付款类型选项业务编码即可。

• 导入接口：推荐直接传选项业务编码字符串，例如 "BID_DEPOSIT"；也支持对象写法。
• 更新接口：customObject 是全覆盖字段，推荐传对象，例如 { "bizCode": "BID_DEPOSIT" }。
• 单据详情查询：预付款类型从费用明细 customObject 返回，返回值为选项对象结构，不再作为费用明细平铺字段返回。

收据附件规则

费用导入/更新时，receiptAttachments 单次最多 30 个。附件会保存为费用附件，并打 DEPOSIT_RECEIPT 标签；单据详情查询只在费用明细 receiptAttachments 中返回该标签下的收据附件。

保证金台账查询返回的 receiptAttachments 来源于保证金台账关联的收据附件，按台账维度返回，不使用费用内码作为对外关联依据。

台账共享字段

保证金台账会返回转换后的 customObject，不会返回内部 referenceFormCode。共享字段筛选按字段类型分组传入：

• itemSearches：档案/选项类字段，使用 searchCodeList
• singleTextSearches / multiTextSearches：文本字段，使用 searchText
• numberSearches：数字字段，使用 min / max；账龄范围筛选也通过 field=ageDays 传入
• amountSearches：金额字段，使用 min / max
• dateTimeSearches：日期时间字段，使用 startTime / endTime
• staffSearches：人员字段，使用 searchText
• serialNumberSearches：流水号字段，使用 searchText

修改记录

2026-06-30  同步保证金台账查询最新返回口径：不返回内部 code，台账收据附件按台账维度返回
2026-06-29  同步单据详情返回口径：预付款类型位于费用明细 customObject，收据介质和收据附件为费用明细顶层字段
2026-06-17  同步保证金台账共享字段筛选和 OpenAPI 查询口径
2026-05-29  新增保证金/押金开放接口总览