@[TOC]
## 接口介绍
在客户使用星瀚系统时，存在第三方系统对接时会有需要查询科目余额的或者核算维度余额的场景，为此提供了API余额接口供使用，可以按照科目或者核算维度的角度查询**单组织某个期间**余额数据。
## 接口说明
### 接口路径
开发服务云-->开放平台-->API开发
### 接口配置
#### 5.0.020及以后版本
系统已经在开发平台预置了余额取数接口服务，直接使用即可。详细使用可以参看API文档，菜单为API文档。
API服务路径：开放平台-->API管理列表-->财务云-->总账-->余额接口-->getBalance
请求url格式:https://xxx.kdcloud.com/test/kapi/v2/gl/getBalanceApi
#### 5.0.020以前版本
5.0.020版本之前需要自己新建API服务。路径：开放平台-->其他-->API服务管理1.0
1、打开API1.0的新增按钮配置开关，默认1.0的新增已经关闭
2、新增API服务，建立总账的自定义调用接口
3、获取总账余额服务getBalanceService，选择post方式
4、建立插件kd.fi.gl.api.BanlanceServiceApiHelper
这样一个自定义的操作服务就注册好了，访问地址为星瀚系统地址+/api+API高级信息中的URL内容。
### 使用说明
建立参数类BalanceQueryParamApi (可不建参数类，参数类主要为了方便传参)
```java
public class BalanceQueryParamApi{
//查询字段
private List<String> selectors = new ArrayList<String>();
//组织编码
private String orgNumber;
//账簿类型编码
private String bookTypeNumber;
//期间编码
private String periodNumber;
//币别编码
private String currencyNumber;
//科目表编码
private String accountTableNumber;
//科目编码：多组核算维度编码
//accountAssgrp的内部Map -> 核算维度类型编码：核算维度值的编码
private Map<String, List<Map<String, String>>> accountAssgrp = new HashMap<>();
//分组字段；只包含：余额表字段与查询的核算维度
private List<String> groupBys = new ArrayList<String>();
//是否扣减损益类金额
private boolean isSubstractPL = false;
//指定科目查询
private boolean isSpecialAccount = true;
// 省略getter setter方法
}
```
#### 参数字段说明
| 字段 | 说明 | 备注 |
| ------------ | ------------ | ------------ |
| selectors | 需要查询的余额表字段，字段标识对应gl_balance元数据，后面会有介绍 | 必录，selector加了period期间字段则只查询当期有发生的数据，当期无发生不返回 |
| orgNumber | 核算组织编码 | 必录 |
| bookTypeNumber | 账簿类型编码 | 必录 |
| accountTableNumber | 科目表 | 必录 |
| periodNumber | 期间编码 | 必录 |
| currencyNumber | 币别编码 | 非必录，不传查询综合本位币 |
| accountAssgrp | 科目维度Map参数，下文详细展开 | 科目必录 |
| groupBys | 分组字段 | |
| isSubstractPL | 是否扣减结转损益发生 | 默认为false |
|isSpecialAccount| 指定科目查询，为true时只返回查询参数的科目余额数据 | 默认为true |
accountAssgrp 科目数据传递在此详细说明下：
key是科目对应版本的ID，value是一个List<Map<String, Long>>，对应多个维度信息，Map为核算维度类型编码：核算维度值的编码，比如核算维度中客户编码为customer，客户A的编码为0001，则内部Map值为：{customer:0001}
#### 余额表gl_balance字段说明
| 字段 | 说明 | 备注 |
| ------------ | ------------ | ------------ |
| org | 核算组织 | |
| booktype | 账簿类型 | |
| period | 期间 | 该维度余额记录的发生期间 |
| endperiod | 结束期间 | 该维度下一个发生期间，无下一期则该值为99999999999L，表示最大期间 |
| accounttable | 科目表 | |
| account | 科目 | |
| currency | 币别 | |
| assgrp | 核算维度 | 弹性域，维度的横表组合 |
| measureunit | 计量单位 | |
| beginfor | 期初原币金额 | |
| beginlocal | 期初本位币金额 | |
| beginqty | 期初数量 | |
| debitfor | 本期借方原币金额 | |
| debitlocal | 本期借方本位币金额 | |
| creditfor | 本期贷方原币金额 | |
| creditlocal | 本期贷方本位币金额 | |
| debitqty | 本期借方数量 | |
| creditqty | 本期贷方数量 | |
| yeardebitfor | 本年借方原币金额 | |
| yeardebitlocal | 本年借方本位币金额 | |
| yearcreditfor | 本年贷方原币金额 | |
| yearcreditlocal | 本年贷方本位币金额 | |
| yeardebitqty | 本年借方数量 | |
| yearcreditqty | 本年贷方数量 | |
| endfor | 期末原币金额 | |
| endlocal | 期末本位币金额 | |
| endqty | 期末数量 | |
| count | 凭证分录数 | 用于记录对应余额的汇总凭证分录发生数 |
| comassist1 | 公共维度1 | 对应科目表的公共维度1，不启用公共维度则不需要关心 |
| comassist2 | 公共维度2 | 对应科目表的公共维度2，不启用公共维度则不需要关心 |
#### API请求结构示例
查询组织org1下，202304期，1002并且客户维度挂了“custom-001”的本位币期初余额和本位币期末余额
```json
{
"orgNumber":"org1",
"bookTypeNumber":"100001",
"accountAssgrp":{
"1002":[
{
"0001":"custom-001"
}
]
},
"isSpecialAccount":true,
"periodNumber":"202304",
"groupBys":[
"account",
"0001"
],
"currencyNumber":"CNY",
"accountTableNumber":"100000",
/** 公共维度传值示例
"comassist":{
"comassist1":[
"custom-001"
]
},
*/
"selectors":[
"org",
"beginlocal",
"endlocal"
],
"isSubstractPL":false
}
```
更多使用场景示例可以参考【科目余额微服务接口】中的使用示例。
#### postman调用示例
#### API返回结构示例
```json
{
"data": "[
{"number":"1033.02","creditlocal":0.000000,"assgrp":{},"debitlocal":123.000000,"yeardebitlocal":123.000000,"beginlocal":123.000000,"yearcreditlocal":534.000000,"endlocal":0.000000},
{"number":"1033.02","creditlocal":12.000000,"assgrp":{"00001":{"name":"腾宇","number":"000001"}},"debitlocal":12.000000,"yeardebitlocal":12.000000,"beginlocal":0.000000,"yearcreditlocal":12.000000,"endlocal":0.000000}]",
"errorCode":"",
"message":"",
"status":true
}
```
