Balances #
Balances represent Transactions in Balance Sheet Accounts that are still outstanding at the end of the previous Reporting Period. Balances arise from Clearable Transactions such as Client Invoices, Supplier Bills and Journal Entries.
Properties #
Direct Properties #
| Property | Type | Definition |
|---|---|---|
| Balance Type | String | Must be one of DEBIT or CREDIT and represents the side of the Double Entry the Balance falls |
| Transaction Type | String | Must be one of IN, BL or JN. Represents the type of Transaction that gave rise to the Balance |
| Transaction Date | Date | The date of the Transaction that gave rise to the Balance |
| Reference | String | Identifying information about the Transaction that gave rise to the Balance e.g Invoice Number |
| Balance | Float | The amount outstanding on the balance Transaction from the Previous Period |
Indirect Properties #
| Property | Type | Definition |
|---|---|---|
| Currency | Dictionary | The Foreign Currency used in the Transaction |
| Exchange Rate | Dictionary | The Closing Rate from the previous Reporting Period for Foreign Currency Transaction |
| Account | Dictionary | The Account for which the Balance relates |
| Reporting Period | Dictionary | The Reporting Period to which the Balance relates |
Basics #
The parameters required to create a balance are the Id of the account for which the balance is for, the balance type, the transaction type and the date.
Request #
curl --location --request POST 'api.microbooks.io/books/v1/balance' \
--data-raw '{
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}'
import requests
url = "https://api.microbooks.io/books/v1/balance"
body = {
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("POST", url, headers=headers, json=body)
print(response.text)
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.microbooks.io/books/v1/balance',
'headers': {'Authorization': 'Bearer <bearer_token>'},
'body': '{
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}'
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
$client = new Client();
$body = '{
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/balance',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/balance");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
\"currency_id\" : 2,
\"exchange_rate_id\" : 1,
\"account_id\" : 1,
\"reporting_period_id\" : 2,
\"balance_type\" : \"DEBIT\",
\"transaction_type\" : \"IN\",
\"transaction_date\" : \"2021-10-21\",
\"balance\" : 100
}";
request.AddParameter("text/plain", body, ParameterType.RequestBody);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response #
{
"status": "success",
"message": "Debit Balance: Barrett Runolfsdottir DVM for year 2022 created successfully",
"resource": {
"reporting_period_id": 2,
"exchange_rate_id": 1,
"balance_type": "DEBIT",
"currency_id": 2,
"account_id": 1,
"transaction_date": "2021-10-21",
"balance": 100,
"transaction_no": "1EGP2008",
"entity_id": 1,
"id": 1,
"transaction_name": "Client Invoice",
"amount": 100,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...},
"account": {...},
"currency": {..},
"reporting_period": {...}
}
}
Variations #
The Balance Resource has no Variations.
Operations #
Opening Balances #
The Opening Balances Endpoint provides a comparison between the Credit and Debit Balances recorded for a given Reoprting Period, making it easy to make sure that their totals are equal.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/balance/opening-balances'
import requests
url = "https://api.microbooks.io/books/v1/balance/opening-balances"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)
print(response.text)
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://api.microbooks.io/books/v1/balance/opening-balances',
'headers': {'Authorization': 'Bearer <bearer_token>'},
'body': '{}'
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/balance/opening-balances',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/balance/opening-balances");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
var body = null;
request.AddParameter("text/plain", body, ParameterType.RequestBody);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response #
{
"status": "success",
"balances": {
"balances": {
"debit": 90,
"credit": -90
},
"accounts": [
{
"uuid": "d686186b-e2a4-4780-892a-d9d400e53f61",
"id": 1,
"entity_id": 1,
"category_id": null,
"currency_id": 1,
"code": 6,
"name": "Violette Howell",
"description": null,
"opening_balance": 70,
"type": "Receivable",
"is_closed": false,
"balances": [
{
"uuid": "9f56af92-1568-4b93-b47a-d60cab4a87d0",
"id": 1,
"entity_id": 1,
"account_id": 1,
"currency_id": 4,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "at",
"transaction_date": "2021-10-21 15:07:59",
"transaction_no": "est",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Client Invoice",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...}
},
{
"uuid": "4d979036-4c34-4f88-9429-3241e980dd73",
"id": 2,
"entity_id": 1,
"account_id": 1,
"currency_id": 6,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "quaerat",
"transaction_date": "2021-10-21 15:08:00",
"transaction_no": "qui",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Journal Entry",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {..}
}
]
},
{
"uuid": "cc60ebf8-cbf7-4924-9b07-d15df6c9c451",
"id": 2,
"entity_id": 1,
"category_id": null,
"currency_id": 1,
"code": 9,
"name": "Clara Ritchie",
"description": null,
"opening_balance": 20,
"type": "Inventory",
"is_closed": false,
"balances": [...]
},
{
"uuid": "70b5b64e-ec7a-4e21-a6b8-2af221e61adf",
"id": 4,
"entity_id": 1,
"category_id": null,
"currency_id": 1,
"code": 1,
"name": "Friedrich Schneider",
"description": null,
"opening_balance": -40,
"type": "Payable",
"is_closed": false,
"balances": [...]
}
]
}
}
Errors #
Below are the Errors that are returned by the Balance Resource.
| Detail Code | Name | Definition |
|---|---|---|
| 101 | Missing Entity | The Balance Resource requires an existing Entity because it is used for transfering uncleared Transactions accross Reporting Periods, which Transactions are scoped to the Entity |
| 102 | Negative Amount | A negative amount on a Balance Resource is meaningless |
| 103 | Invalid Balance Transaction | The type of Balance Transcation provided cannot be transfered accross Reporting Periods and is therefore invalid according to the rules of IFRS/Bookkeeping |
| 104 | Invalid Balance Type | The type of Balance provided is invalid according to the rules of IFRS/Bookkeeping |
| 105 | Invalid Account Class Balance | Balances of Accounts in the class of the Account provided cannot be transfered accross Reporting Periods and it is therefore invalid according to the rules of IFRS/Bookkeeping |
| 106 | Invalid Balance Date | The date provided at which the Balance arose is invalid according to the rules of IFRS/Bookkeeping and/or the Balance Resource Entity’s settings |
| 107 | Invalid Currency | The Currency of the Balance must be the same as that of the provided Balance Account |