Balance API
1. Introduction
The HORISEN Balance API contains the logic behind the SMS Platform application part on the HORISEN platform. It is a JSON based REST API that provides access to objects, like Customer and Supplier Balances, that are in use by other HORISEN services.
The HORISEN Balance API authorization is implemented as the industry-standard OAuth 2.0 protocol. An example of how to implement OAuth 2.0 and obtain an access token, as well as an example of using a HORISEN API service, is available at OAuth2 Authentication Guidelines page.
The HORISEN Balance API belongs to the Finance domain. The subject domain of an endpoint URL is:
https://api{separator}{platform_domain}/finance/sit/v1
Note: A domain is presented with placeholders as https://api{separator}{platform_domain}
, where {separator}
can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.
2. Methods Overview
Balance API endpoints.
3. Methods Details
Method Overview
The method returns a list of balances on customer/supplier and currency level, with optional possibility to make wider grouping for deeper analysis.
Example:
/finance/sit/v1/balances/biz-partners/customers?page_number=1&page_size=10
Authorization privilege needed for this endpoint:
- finance-balance-view,
- finance-balance-own-view.
This endpoint supports URL filtering. For more information, please refer to URL Filtering Guidelines page.
Filter fields are: bizPartnerName, bizPartnerBriefName, bizPartnerId, bizPartnerType, rounding, totalPaid, currency, currencyCode, ownerId, ownerBpName, ownerBpBriefName, docClassId, docClassCodeName, docClassDomain, docClassArea, dataSourceId, dataSourceCodeName, domainId, domainCodeName, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName.
For fields: amountNoVat, amountVat, total, totalUnpaid, totalPaid in filter, it works every operator except equal (=) operator.
URL Parameters
Name | Type | Description |
---|---|---|
page_number | integer (query) | Page number. Default value is 1. |
page_size | integer (query) | Page size. Default value is 10. |
paging | string (query) | Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10 |
sort | string (query) | Sorting options. The format is: sort=-attribute1,attribute2,-attribute3.Available fields: bizPartnerId, bizPartnerType, bizPartnerName, bizPartnerBriefName, amountNoVat, amountVat, vat, rounding, total, totalUnpaid, totalPaid, currency, currencyCode, ownerId, ownerBpName, ownerBpBriefName, docClassId, docClassCodeName, docClassDomain, docClassArea, dataSourceId, dataSourceCodeName, domainId, domainCodeName, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName. |
group | string (query) | Grouping by criteria options. Default group criteria which is always performed is by biz_partner_id and currency.Available fields: domainId, domainCodeName, docClassId, docClassCodeName, docClassDomain, docClassArea, documentTypeId, dataSourceId, dataSourceCodeName, documentTypeName, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName, documentTypeSelfBilling.Attributes listed in available fields list, will be returned in a response object only if they are passed in query for grouping but on following suggestions:
|
Responses
Code | Description | Links |
---|---|---|
200 | List of balances. | No links. |
default | Unexpected error. | No links. |
Success Response 200: List of Balances
{
"data": [
{
"instanceId": 0,
"bizPartnerId": 0,
"bizPartnerName": "string",
"bizPartnerBriefName": "string",
"bizPartnerType": "string",
"currency": 0,
"currencyCode": "string",
"amountNoVat": 0,
"amountVat": 0,
"vat": 0,
"rounding": 0,
"total": 0,
"totalUnpaid": 0,
"totalPaid": 0,
"ownerId": 0,
"ownerBpName": "string",
"ownerBpBriefName": "string",
"domainId": 0,
"domainCodeName": "string",
"docClassId": 0,
"docClassCodeName": "string",
"docClassDomain": "string",
"docClassArea": "string",
"dataSourceId": 0,
"dataSourceCodeName": "string",
"documentTypeId": 0,
"documentTypeName": "string",
"documentTypeSelfBilling": "no",
"documentTypeDtsSelectorId": 0,
"documentTypeDtsSelectorCodeName": "string"
}
],
"meta": {
"pagination": {
"total": 0,
"totalPages": 0,
"currentPage": 0,
"perPage": 0,
"count": 0
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
Method Overview
The method returns a list of balances on supplier and currency level, with optional possibility to make wider grouping for deeper analysis.
Example:
/finance/sit/v1/balances/biz-partners/suppliers?page_number=1&page_size=10
Authorization privilege needed for this endpoint:
- finance-balance-view,
- finance-balance-own-view.
This endpoint supports URL filtering. For more information, please refer to URL Filtering Guidelines page.
Filter fields are: bizPartnerName, bizPartnerBriefName, bizPartnerId, bizPartnerType, rounding, totalPaid, currency, currencyCode, ownerId, ownerBpName, ownerBpBriefName, docClassId, docClassCodeName, docClassDomain, docClassArea, dataSourceId, dataSourceCodeName, domainId, domainCodeName, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName.
For fields: amountNoVat, amountVat, total, totalUnpaid, totalPaid in filter, it works every operator except equal (=) operator.
URL Parameters
Name | Type | Description |
---|---|---|
page_number | integer (query) | Page number. Default value is 1. |
page_size | integer (query) | Page size. Default value is 10. |
paging | string (query) | Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10 |
sort | string (query) | Sorting options. The format is: sort=-attribute1,attribute2,-attribute3.Available fields: bizPartnerId, bizPartnerType, bizPartnerName, bizPartnerBriefName, amountNoVat, amountVat, vat, rounding, total, totalUnpaid, totalPaid, currency, currencyCode, ownerId, ownerBpName, ownerBpBriefName, docClassId, docClassCodeName, docClassDomain, docClassArea ,dataSourceId, dataSourceCodeName, domainId, domainCodeName, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName. |
group | string (query) | Grouping by criteria options. Default group criteria which is always performed is by biz_partner_id and currency.Available fields: domainId, domainCodeName, docClassId, docClassCodeName, docClassDomain, docClassArea, documentTypeId, dataSourceId, dataSourceCodeName, documentTypeName, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName, documentTypeSelfBilling.Attributes listed in available fields list, will be returned in a response object only if they are passed in query for grouping but on following suggestions:
|
Responses
Code | Description | Links |
---|---|---|
200 | List of balances. | No links. |
default | Unexpected error. | No links. |
Success Response 200: List of Balances
{
"data": [
{
"instanceId": 0,
"bizPartnerId": 0,
"bizPartnerName": "string",
"bizPartnerBriefName": "string",
"bizPartnerType": "string",
"currency": 0,
"currencyCode": "string",
"amountNoVat": 0,
"amountVat": 0,
"vat": 0,
"rounding": 0,
"total": 0,
"totalUnpaid": 0,
"totalPaid": 0,
"ownerId": 0,
"ownerBpName": "string",
"ownerBpBriefName": "string",
"domainId": 0,
"domainCodeName": "string",
"docClassId": 0,
"docClassCodeName": "string",
"docClassDomain": "string",
"docClassArea": "string",
"dataSourceId": 0,
"dataSourceCodeName": "string",
"documentTypeId": 0,
"documentTypeName": "string",
"documentTypeSelfBilling": "no",
"documentTypeDtsSelectorId": 0,
"documentTypeDtsSelectorCodeName": "string"
}
],
"meta": {
"pagination": {
"total": 0,
"totalPages": 0,
"currentPage": 0,
"perPage": 0,
"count": 0
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
Method Overview
The method returns a balance per document.
startDate and endDate are used as period filter for documentDate field.
If these dates are not sent in query, all documents will be presented for biz-partner without date filter.
Time format should be RFC3339 date format without time component (YYYY-MM-DD).
Example:
/finance/sit/v1/balances/biz-partners/customers/1061/sheets?page_number=1&page_size=10&startDate=2012-05-10&endDate=2013-05-10
Authorization privilege needed for this endpoint:
- finance-balance-view,
- finance-balance-own-view.
This endpoint supports URL filtering. For more information, please refer to URL Filtering Guidelines page.
Filter fields are: documentId, documentUuid, bizPartnerId, bizPartnerType, rounding, bizPartnerName, bizPartnerBriefName, vat, docClassDomain, docClassArea, documentNumber, documentDate, documentDueDate, documentIssuingDate, currency, currencyCode, paymentStatus, docClassId, docClassCodeName, dataSourceId, dataSourceCodeName, domainId, ownerId, ownerBpName, ownerBpBriefName, domainCodeName, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName.
For fields: amountNoVat, amountVat, total, totalUnpaid, totalPaid in filter, it works every operator except equal (=) operator.
URL Parameters
Name | Type | Description |
---|---|---|
bizPartnerId (required) | integer (path) | Biz partner ID. |
startDate | string($date) (query) | Start date of search. |
endDate | string($date) (query) | End date of search. |
page_number | integer (query) | Page number. Default value is 1. |
page_size | integer (query) | Page size. Default value is 10. |
sort | string (query) | Sorting options.Available fields: bizPartnerId, bizPartnerType, bizPartnerName, bizPartnerBriefName, amountNoVat, amountVat, vat, rounding, total, totalPaid, totalUnpaid, currency, currencyCode, paymentStatus, ownerId, ownerBpName, ownerBpBriefName, docClassId, docClassCodeName, docClassDomain, docClassArea, dataSourceId, dataSourceCodeName, domainId, domainCodeName, documentId, documentUuid, documentNumber, documentDate, documentDueDate, documentIssuingDate, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName. |
dir | string (query) | Sorting direction. Available values : asc, desc. |
paging | string (query) | Paging options. The format is: &paging=page_num,page_size eg. paging=1,10 |
Responses
Code | Description | Links |
---|---|---|
200 | List of balances. | No links. |
default | Unexpected error. | No links. |
Success Response 200: List of Balances
{
"data": [
{
"documentId": 0,
"documentUuId": "string",
"instanceId": 0,
"bizPartnerId": 0,
"bizPartnerName": "string",
"bizPartnerBriefName": "string",
"bizPartnerType": "string",
"currency": 0,
"currencyCode": "string",
"amountNoVat": 0,
"amountVat": 0,
"vatPercent": 0,
"vat": 0,
"rounding": 0,
"total": 0,
"totalUnpaid": 0,
"totalPaid": 0,
"ownerId": 0,
"ownerBpName": "string",
"ownerBpBriefName": "string",
"domainId": 0,
"domainCodeName": "string",
"docClassId": 0,
"docClassCodeName": "string",
"docClassDomain": "string",
"docClassArea": "string",
"dataSourceId": 0,
"dataSourceCodeName": "string",
"documentTypeId": 0,
"documentTypeName": "string",
"documentTypeSelfBilling": "yes",
"documentTypeDtsSelectorId": 0,
"documentTypeDtsSelectorCodeName": "string",
"documentNumber": "string",
"documentDate": "2021-11-04",
"documentDueDate": "2021-11-04",
"documentIssuingDate": "2021-11-04",
"paymentStatus": "none"
}
],
"meta": {
"pagination": {
"total": 0,
"totalPages": 0,
"currentPage": 0,
"perPage": 0,
"count": 0
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
Method Overview
The method returns balance per document.
startDate and endDate are used as period filter for documentDate field.
If these dates are not sent in query, all documents will be presented for biz-partner without date filter.
Time format should be RFC3339 date format without time component (YYYY-MM-DD).
Example:
/finance/sit/v1/balances/biz-partners/suppliers/1061/sheets?page_number=1&page_size=10&startDate=2012-05-10&endDate=2013-05-10
Authorization privilege needed for this endpoint:
- finance-balance-view,
- finance-balance-own-view.
This endpoint supports URL filtering. For more information, please refer to URL Filtering Guidelines page.
Filter fields are: documentId, documentUuid, bizPartnerId, bizPartnerType, rounding, bizPartnerName, bizPartnerBriefName, vat, docClassDomain, docClassArea, documentNumber, documentDate, documentDueDate, documentIssuingDate, currency, currencyCode, paymentStatus, docClassId, docClassCodeName, dataSourceId, dataSourceCodeName, domainId, ownerId, ownerBpName, ownerBpBriefName, domainCodeName, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName.
For fields: amountNoVat, amountVat, total, totalUnpaid, totalPaid in filter, it works every operator except equal (=) operator.
URL Parameters
Name | Type | Description |
---|---|---|
bizPartnerId (required) | integer (path) | Biz partner ID. |
startDate | string($date) (query) | Start date of search. |
endDate | string($date) (query) | End date of search. |
page_number | integer (query) | Page number. Default value is 1. |
page_size | integer (query) | Page size. Default value is 10. |
sort | string (query) | Sorting options.Available fields: bizPartnerId, bizPartnerType, bizPartnerName, bizPartnerBriefName, amountNoVat, amountVat, vat, rounding, total, totalUnpaid, totalPaid, currency, currencyCode, paymentStatus, ownerId, ownerBpName, ownerBpBriefName, docClassId, docClassCodeName, docClassDomain, docClassArea, dataSourceId, dataSourceCodeName, domainId, domainCodeName, documentId, documentUuid, documentNumber, documentDate, documentDueDate, documentIssuingDate, documentTypeId, documentTypeName, documentTypeSelfBilling, documentTypeDtsSelectorId, documentTypeDtsSelectorCodeName. |
dir | string (query) | Sorting direction. Available values : asc, desc. |
paging | string (query) | Paging options. The format is: &paging=page_num,page_size eg. paging=1,10 |
Responses
Code | Description | Links |
---|---|---|
200 | List of balances. | No links. |
default | Unexpected error. | No links. |
Success Response 200: List of Balances
{
"data": [
{
"documentId": 0,
"documentUuId": "string",
"instanceId": 0,
"bizPartnerId": 0,
"bizPartnerName": "string",
"bizPartnerBriefName": "string",
"bizPartnerType": "string",
"currency": 0,
"currencyCode": "string",
"amountNoVat": 0,
"amountVat": 0,
"vatPercent": 0,
"vat": 0,
"rounding": 0,
"total": 0,
"totalUnpaid": 0,
"totalPaid": 0,
"ownerId": 0,
"ownerBpName": "string",
"ownerBpBriefName": "string",
"domainId": 0,
"domainCodeName": "string",
"docClassId": 0,
"docClassCodeName": "string",
"docClassDomain": "string",
"docClassArea": "string",
"dataSourceId": 0,
"dataSourceCodeName": "string",
"documentTypeId": 0,
"documentTypeName": "string",
"documentTypeSelfBilling": "yes",
"documentTypeDtsSelectorId": 0,
"documentTypeDtsSelectorCodeName": "string",
"documentNumber": "string",
"documentDate": "2021-11-04",
"documentDueDate": "2021-11-04",
"documentIssuingDate": "2021-11-04",
"paymentStatus": "none"
}
],
"meta": {
"pagination": {
"total": 0,
"totalPages": 0,
"currentPage": 0,
"perPage": 0,
"count": 0
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
4. Data Models
Data Models define the structure of a JSON document.
4.1 Data
Data describe all the data related to the Customer/Supplier Balance API.
BizPartnerBalanceSheetCollection object properties:
Name | Type | Description |
---|---|---|
data (required) | array | An array of BizPartnerBalanceSheet objects. |
meta (required) | object | collectionMeta object. |
BizPartnerBalanceSheet object properties:
Name | Type | Description |
---|---|---|
documentId | integer | Document ID. |
documentUuId | string | Document UUID. |
instanceId | integer | Instance ID. |
bizPartnerId | integer | Biz Partner ID. |
bizPartnerName | string | Biz Partner name. |
bizPartnerBriefName | string | Biz Partner brief name. |
bizPartnerType | string | Biz Partner type. |
currency | integer | Balance currency. |
currencyCode | string | Balance currency code. |
amountNoVat | number($float) | Amount without VAT. |
amountVat | number($float) | Amount including VAT. |
vatPercent | number($float) | VAT percent. |
vat | number($float) | vat = amountVat - amountNoVat |
rounding | number($float) | rounding = total - amountVat |
total | number($float) | Balance total. |
totalUnpaid | number($float) | Total unpaid amount. |
totalPaid | number($float) | Total paid amount. |
ownerId | integer | Owner ID. |
ownerBpName | string | Owner Biz Partner name. |
ownerBpBriefName | string | Owner Biz Partner brief name. |
domainId | integer | It will be returned in response if grouped by domainId. |
domainCodeName | string | It will be returned in response if grouped by domainCodeName. |
docClassId | integer | It will be returned in response if grouped by docClassId. |
docClassCodeName | string | It will be returned in response if grouped by docClassCodeName. |
docClassDomain | string | It will be returned in response if grouped by docClassDomain. |
docClassArea | string | It will be returned in response if grouped by docClassArea. |
dataSourceId | integer | It will be returned in response if grouped by dataSourceId. |
dataSourceCodeName | string | It will be returned in response if grouped by dataSourceCodeName. This attribute has repeatable codeName among different domains (domainId or domainCodeName). If you want to target exact value then better use dataSourceId attribute, or add domainId or domainCodeName in grouping. |
documentTypeId | integer | It will be returned in response if grouped by documentTypeId. |
documentTypeName | string | It will be returned in response if grouped by documentTypeName. |
documentTypeSelfBilling | string | It will be returned in response if grouped by documentTypeSelfBilling. Possible values are: no, yes. When 'yes' then indicates that money flows in opposite direction than for regular documents of the same docClassCodeName. Good example is docClass NETTING_INVOICE which is in 'sales' area, if documentTypeId has documentTypeSelfBilling = 'yes' then netting is in favor of document receiver (platform owner owes the amount). |
documentTypeDtsSelectorId | integer | It will be returned in response if grouped by documentTypeDtsSelectorId. |
documentTypeDtsSelectorCodeName | string | It will be returned in response if grouped by documentTypeDtsSelectorCodeName. This attribute has repeatable codeName among different dataSources. If you want to target exact value then better use documentTypeDtsSelectorId attribute, or add dataSource attributes in grouping. |
documentNumber | string | Document number. |
documentDate | string($date) | Document date. |
documentDueDate | string($date) | Document due date. |
documentIssuingDate | string($date) | Document issuing date. |
paymentStatus | string | Possible values are: none, open, closed, on-hold. |
BizPartnerBalanceCollection object properties:
Name | Type | Description |
---|---|---|
data (required) | array | Array of BizPartnerBalance objects. |
meta (required) | object | collectionMeta object. |
BizPartnerBalance object properties:
Name | Type | Description |
---|---|---|
instanceId | integer | Instance ID. |
bizPartnerId | integer | BizPartner ID. |
bizPartnerName | string | BizPartner name. |
bizPartnerBriefName | string | BizPartner brief name. |
bizPartnerType | string | BizPartner type. |
currency | integer | Balance currency. |
currencyCode | string | Balance currency code. |
amountNoVat | number($float) | Amount without VAT. |
amountVat | number($float) | Amount including VAT. |
vat | number($float) | vat = amountVat - amountNoVat |
rounding | number($float) | rounding = total - amountVat |
total | number($float) | Balance total. |
totalUnpaid | number($float) | Total unpaid amount. |
totalPaid | number($float) | Total paid amount. |
ownerId | integer | Owner ID. |
ownerBpName | string | Owner Biz Partner name. |
ownerBpBriefName | string | Owner Biz Partner brief name. |
domainId | integer | It will be returned in response if grouped by domainId. |
domainCodeName | string | It will be returned in response if grouped by domainCodeName. |
docClassId | integer | It will be returned in response if grouped by docClassId. |
docClassCodeName | string | It will be returned in response if grouped by docClassCodeName. |
docClassDomain | string | It will be returned in response if grouped by docClassDomain. |
docClassArea | string | It will be returned in response if grouped by docClassArea. |
dataSourceId | integer | It will be returned in response if grouped by dataSourceId. |
dataSourceCodeName | string | It will be returned in response if grouped by dataSourceCodeName. This attribute has repeatable codeName among different domains (domainId or domainCodeName). If you want to target exact value then better use dataSourceId attribute, or add domainId or domainCodeName in grouping. |
documentTypeId | integer | It will be returned in response if grouped by documentTypeId. |
documentTypeName | string | It will be returned in response if grouped by documentTypeName. |
documentTypeSelfBilling | string | It will be returned in response if grouped by documentTypeSelfBilling. Possible values are: no, yes. |
documentTypeDtsSelectorId | integer | It will be returned in response if grouped by documentTypeDtsSelectorId. |
documentTypeDtsSelectorCodeName | string | It will be returned in response if grouped by documentTypeDtsSelectorCodeName. This attribute has repeatable codeName among different dataSources. If you want to target exact value then better use documentTypeDtsSelectorId attribute, or add dataSource attributes in grouping. |
JSON Example
{
"data": [
{
"documentId": 0,
"documentUuId": "string",
"instanceId": 0,
"bizPartnerId": 0,
"bizPartnerName": "string",
"bizPartnerBriefName": "string",
"bizPartnerType": "string",
"currency": 0,
"currencyCode": "string",
"amountNoVat": 0,
"amountVat": 0,
"vatPercent": 0,
"vat": 0,
"rounding": 0,
"total": 0,
"totalUnpaid": 0,
"totalPaid": 0,
"ownerId": 0,
"ownerBpName": "string",
"ownerBpBriefName": "string",
"domainId": 0,
"domainCodeName": "string",
"docClassId": 0,
"docClassCodeName": "string",
"docClassDomain": "string",
"docClassArea": "string",
"dataSourceId": 0,
"dataSourceCodeName": "string",
"documentTypeId": 0,
"documentTypeName": "string",
"documentTypeSelfBilling": "yes",
"documentTypeDtsSelectorId": 0,
"documentTypeDtsSelectorCodeName": "string",
"documentNumber": "string",
"documentDate": "2021-11-04",
"documentDueDate": "2021-11-04",
"documentIssuingDate": "2021-11-04",
"paymentStatus": "none"
}
],
"meta": {
"pagination": {
"total": 0,
"totalPages": 0,
"currentPage": 0,
"perPage": 0,
"count": 0
}
}
}
Name | Type | Description |
---|---|---|
code (required) | integer($int32) | An error code. |
message (required) | string | An error message. |
JSON Example
{
"Code": 0,
"Message": "string"
}
4.2 Meta
Meta contains data for the number of rows and pages that have been received for a given API call.
collectionMeta object properties:
Name | Type | Description |
---|---|---|
collectionMetaPagination | object | collectionMetaPagination object. |
collectionMetaPagination object properties:
Name | Type | Description |
---|---|---|
total (required) | integer | Total number of rows. |
totalPages (required) | integer | Total number of pages. |
currentPage (required) | integer | The current page number. |
perPage (required) | integer | The maximum rows per page. |
count (required) | integer | A number of rows in the current page. |
JSON Example
"meta": {
"pagination": {
"total": 0,
"totalPages": 0,
"currentPage": 0,
"perPage": 0,
"count": 0
}
}