预算占用明细查询接口需求文档
说明
用户在每刻系统内查看预算卡片外联数据
1. 接口基本信息
请求方式
POST
2. 请求参数
2.1 请求体（Body）
{
"formDataCode":"xxxxxxxx",
"formCode": "您的单据code",
"formType":"REIMBURSE",
"operation" :"EXPENSE_ADJUST",
"payableAmount": {
"currencyCode": "CNY",
"text": "1000.00"
},
"approvedAmount": {
"currencyCode": "CNY",
"text": "1000.00"
},
"reason": "调整原因",
"operatorEmployeeId": "USER001",
"deductionHistory":[{
"owedAmount": 800.00,
"owedCurrency": "CNY",
"deductionAmount": 800.00,
"approvedDeductionAmount": 800.00,
"deductionCurrency": "CNY",
"title": "借款单1000元,已核销200元",
"repaymentAt": 1546272000000,
"loanCode": "CODE001001",
"comment": "评论信息",
"description": ["描述信息"]
}],
"formData":{
}
}
备注：请求体传具体字段由前端传给集成的单据信息决定，接口内部根据单据上下文自动解析所需参数。
3. 返回参数
3.1 响应结构
{
"code": "200",
"message": "success",
"data": [
{
"budgetDisplayName": "2026年市场营销预算",
"currentOrderAmount": "¥1,250.00",
"currentPeriodOccupiedAmount": "¥45,680.50",
"currentPeriodRemainingAmount": "¥54,319.50"
},
{
"budgetDisplayName": "2026年差旅预算",
"currentOrderAmount": "¥3,500.00",
"currentPeriodOccupiedAmount": "¥128,000.00",
"currentPeriodRemainingAmount": "¥22,000.00"
}
]
}
3.2 外层响应字段
| 字段名 | 类型 | 说明 |
|---|---|---|
| code | String | 状态码，支持外部自定义字符串编码。"200" 表示成功，非 "200" 表示业务或系统错误 |
| message | String | 响应描述。当 code 不为 "200" 时，必须返回具体错误信息 |
| data | Object[] | 预算占用明细数组，每个元素对应一个预算资源。错误时可为 null |
3.3 Data 数组元素字段（预算卡片对象）
| 字段描述 | 字段名 | 类型 | 是否必填 | 备注 |
|---|---|---|---|---|
| 使用预算显示名称 | budgetDisplayName | String | Y | 对应预算卡片展示的使用预算名称，支持特殊字符 |
| 本单使用金额 | currentOrderAmount | String | Y | 需含币种，保留两位小数，对应预算卡片「本单」 |
| 本期已占用金额 | currentPeriodOccupiedAmount | String | Y | 需含币种，保留两位小数，对应预算卡片「本期已占用」 |
| 本期剩余金额 | currentPeriodRemainingAmount | String | Y | 需含币种，保留两位小数，对应预算卡片「本期剩余」 |
格式说明：金额字段统一返回格式化字符串，包含货币符号（如
¥/$/€）和千分位分隔符，例如：¥12,345.67。
4. 错误码说明
设计原则：错误码为字符串类型，支持接入方自定义。当
code不为"200"时，表示请求处理失败，此时message字段必须返回具体可读的错误信息，用于前端提示或日志记录。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
"200" |
成功 | — |
"400" |
请求参数非法 | 检查请求体是否合法；核对必填单据信息 |
"401" |
鉴权失败 | 检查 Authorization Token 是否有效或已过期 |
"404" |
预算资源不存在 | 核对集成的单据信息是否正确 |
"429" |
请求过于频繁 | 降低请求频率或联系管理员提升限流阈值 |
"500" |
系统内部错误 | 稍后重试或联系技术支持 |
接入方自定义错误码示例：
| 错误码 | 说明 |
|---|---|
"BUDGET_NOT_FOUND" |
未找到对应预算方案 |
"PERIOD_NOT_MATCH" |
单据期间与预算期间不匹配 |
"AMOUNT_EXCEEDED" |
本单金额超出本期剩余预算 |
5. 示例
5.1 成功响应示例
{
"code": "200",
"message": "success",
"data": [
{
"budgetDisplayName": "2026年市场营销预算",
"currentOrderAmount": "¥1,250.00",
"currentPeriodOccupiedAmount": "¥45,680.50",
"currentPeriodRemainingAmount": "¥54,319.50"
}
]
}
5.2 失败响应示例
{
"code": "BUDGET_NOT_FOUND",
"message": "未找到单据关联的预算方案，请检查单据是否已绑定预算",
"data": null
}
6. 约束与注意事项
- 请求体说明：请求体由前端直接透传集成的单据信息，接口内部自行解析所需字段，无需调用方拼接预算相关参数。
- 金额精度：所有金额字段统一保留两位小数，按标准四舍五入规则处理。
- 币种显示：返回金额中的币种符号根据单据上下文自动识别，默认人民币
¥。 - 错误信息必填：只要
code不为"200"，message必须返回可读的业务错误信息，禁止返回空字符串或内部异常堆栈。 - 自定义错误码：接入方可根据业务场景自定义错误码字符串（如
"BUDGET_NOT_FOUND"），便于调用方做差异化处理。