Accounts #
Accounts are records in the General Ledger that agreggate the transactions of the entity and represent the building blocks of the financial statements produced by the system.
Properties #
Direct Properties #
| Property | Type | Definition |
|---|---|---|
| Name | String | A human readable label for the Account |
| Account Code | Integer | A numerical identifier for the Account, generated in sequence if none is provided |
| Account Type | String | Must be one of the types described in the API reference here |
| Description | String | Information about the types of transactions that are posted to the Account Resource |
| Is Closed | Boolean | (For foreign currency denominated Accounts) Whether the Account’s balance has been translated at the Closing Rate for the current Reporting Period |
Indirect Properties #
| Property | Type | Definition |
|---|---|---|
| Currency | Dictionary | The Currency the Account Resource is denominated in |
| Exchange Rate | Dictionary | The Closing Rate from the previous Reporting Period for Foreign Currency Transaction |
| Category | Dictionary | The Category Resource to which the Account Resource belongs |
| Balances | List | The Balance Resources recorded for the Account |
Basics #
The parameters required to create a Balance Resource 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/account' \
--data-raw '{
"name": "Test Account",
"account_type": "RECEIVABLE",
"currency_id": 1,
"category_id": 1,
"entity_id": 1
}'
import requests
url = "https://api.microbooks.io/books/v1/account"
body = {
"name": "Test Account",
"account_type": "RECEIVABLE",
"currency_id": 1,
"category_id": 1,
"entity_id": 1
}
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/account',
'headers': {'Authorization': 'Bearer <bearer_token>'},
'body': '{
"name": "Test Account",
"account_type": "RECEIVABLE",
"currency_id": 1,
"category_id": 1,
"entity_id": 1
}'
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
$client = new Client();
$body = '{
"name": "Test Account",
"account_type": "RECEIVABLE",
"currency_id": 1,
"category_id": 1,
"entity_id": 1
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/account',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/account");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
\"name\": \"Test Account\",
\"account_type\": \"RECEIVABLE\",
\"currency_id\": 1,
\"category_id\": 1,
\"entity_id\": 1
}";
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": "Control: Test Account created successfully",
"resource": {
"name": "Test Account",
"currency_id": 1,
"entity_id": 1,
"category_id": 1,
"code": 2102,
"id": 3,
"type": "Receivable",
"is_closed": false,
"category": {
"uuid": "c3565687-faa3-45bb-9521-e759faaa205f",
"id": 1,
"entity_id": 1,
"name": "ad",
"type": "Receivable"
}
}
}
Variations #
The Account Resource has no Variations.
Operations #
Account Statement #
The Account Statement endpoint lists the Transactions posted to the Account Resource inn chronological order from oldest to the newest.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/account/1/statement'
import requests
url = "https://api.microbooks.io/books/v1/account/1/statement"
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/account/1/statement',
'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/account/1/statement',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/account/1/statement");
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",
"statement": [
{
"id": 1,
"transaction_date": "2022-10-21 15:58:18",
"transaction_no": "CS05/0001",
"reference": null,
"transaction_type": "CS",
"credited": false,
"narration": "perspiciatis",
"rate": "1.0000",
"amount": 116,
"balance": 186,
"credit": 0,
"debit": 116,
"contribution": 116,
"type": "Cash Sale",
"date": "Oct 21, 2022"
},
{
"id": 4,
"transaction_date": "2022-10-21 15:58:18",
"transaction_no": "CE05/0001",
"reference": null,
"transaction_type": "CE",
"credited": false,
"narration": "consequatur",
"rate": "1.0000",
"amount": 50,
"balance": 136,
"credit": 50,
"debit": 0,
"contribution": -50,
"type": "Contra Entry",
"date": "Oct 21, 2022"
}
],
"statement_balances": {
"opening": 70,
"closing": 136
}
}
Account Schedule #
The Account Schedule endpoint, like the Account Statement endpoint also lists the Transactions posted to the Account Resource, but only those which have not yet been cleared i.e. still have outstanding balances.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/account/1/schedule'
import requests
url = "https://api.microbooks.io/books/v1/account/1/schedule"
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/account/1/schedule',
'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/account/1/schedule',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/account/1/schedule");
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",
"schedule": [
{
"uuid": "fe091120-11ab-4f8a-ad8b-aa47200daa3c",
"id": 1,
"entity_id": 1,
"account_id": 1,
"currency_id": 2,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "voluptatem",
"transaction_date": "2021-10-21 16:00:54",
"transaction_no": "molestiae",
"balance_type": "DEBIT",
"balance": "50.0000",
"original_amount": 50,
"amount_cleared": 15,
"clearable_Type": "Balance",
"age": 365,
"date": "Oct 21, 2021",
"uncleared_amount": 35,
"transaction_name": "Journal Entry",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...},
"clearances": [...]
},
{
"uuid": "35a18926-6597-4ab7-af25-0d1a518c3bcd",
"id": 6,
"entity_id": 1,
"account_id": 1,
"currency_id": 2,
"exchange_rate_id": 4,
"transaction_date": "2022-10-21T16:00:54.000000Z",
"reference": null,
"transaction_no": "IN01/0001",
"transaction_type": "IN",
"narration": "suscipit",
"credited": false,
"compound": false,
"main_account_amount": "0.0000",
"original_amount": 116,
"amount_cleared": 50,
"clearable_Type": "Transaction",
"age": 0,
"date": "Oct 21, 2022",
"uncleared_amount": 66,
"transaction_name": "Client Invoice",
"is_posted": true,
"is_credited": false,
"amount": 116,
"tax": {
"total": 16,
"BDCAE": "16.0000"
},
"assignable": false,
"clearable": true,
"has_integrity": true,
"clearances": [...],
"line_items": [...],
"assignments": [...]
}
],
"schedule_balances": {
"original_amount": 166,
"amount_cleared": 65,
"uncleared_amount": 101,
"total_age": 365,
"average_age": 183
}
}
Section Movement #
The Section Movement endpoint provides details on the Account Resource level of the changes in balances of the sections of Financial Statements (Account Resource Types), aggregated by the Categories of the Accounts. This is useful for providing summaries of the totals on the Statements which can then be drilled down to the Account Resource balances.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/account/movement?section=ASSETS'
import requests
url = "https://api.microbooks.io/books/v1/account/movement?section=ASSETS"
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/account/movement?section=ASSETS',
'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/account/movement?section=ASSETS',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/account/movement?section=ASSETS");
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": {
"section_opening_balance": 70,
"section_closing_balance": 186,
"section_movement": -116,
"section_categories": {
"facere": {
"accounts": [
{
"uuid": "2eadaeb2-944f-4a9d-bdca-076a18e2f445",
"id": 1,
"entity_id": 1,
"category_id": 1,
"currency_id": 1,
"code": 501,
"name": "Leola Ferry",
"description": null,
"account_type": "Receivable",
"opening_balance": 70,
"balance_movement": 0,
"closing_balance": 70
}
],
"total": 70,
"category_id": 1
},
"vel": {
"accounts": [
{
"uuid": "5fb5f2f0-3497-433d-a996-cc5f0048e7a6",
"id": 2,
"entity_id": 1,
"category_id": 2,
"currency_id": 1,
"code": 502,
"name": "Nathan Huel MD",
"description": null,
"account_type": "Receivable",
"opening_balance": 0,
"balance_movement": -116,
"closing_balance": 116
}
],
"total": 116,
"category_id": 2
}
}
}
}
Aging Schedule #
The Aging Schedule endpoint shows balances outstanding in Receivable and Payable Accounts categorized by how long they have been outstanding.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/account/aging?end-date=2022-10-21&account-type=RECEIVABLE'
import requests
url = "https://api.microbooks.io/books/v1/account/aging?end-date=2022-10-21&account-type=RECEIVABLE"
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/account/aging?end-date=2022-10-21&account-type=RECEIVABLE',
'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/account/aging?end-date=2022-10-21&account-type=RECEIVABLE',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/account/aging?end-date=2022-10-21&account-type=RECEIVABLE");
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",
"schedule": {
"accounts": [
{
"uuid": "56947640-81a0-45bb-ac70-45b621264ea1",
"id": 1,
"entity_id": 1,
"category_id": null,
"currency_id": 2,
"code": 8,
"name": "Magali Kohler III",
"description": null,
"agedBalances": {
"current": 50,
"31 - 90 days": 100,
"91 - 180 days": 75,
"181 - 270 days": 150,
"271 - 365 days": 175,
"365+ (bad debts)": 25
},
"type": "Receivable",
"is_closed": false
}
],
"agedBalances": {
"current": 50,
"31 - 90 days": 100,
"91 - 180 days": 75,
"181 - 270 days": 150,
"271 - 365 days": 175,
"365+ (bad debts)": 25
},
"period": {
"endDate": "2022-10-21T00:00:00.000000Z"
}
}
}
Closing Transactions #
The Closing Transactions Endpoint retrieves the Journal Entry Transactions entered for the Account Resource to reconcile its foreign currency balance to the Reporting Period’s Closing Rate.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/account/1/closing-transactions'
import requests
url = "https://api.microbooks.io/books/v1/account/1/closing-transactions"
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/account/1/closing-transactions',
'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/account/1/closing-transactions',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/account/1/closing-transactions");
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",
"closing_transactions": [
{
"id": 3,
"account_id": 2,
"currency_id": 1,
"reporting_period_id": 1,
"credited": true,
"transaction_type": "JN",
"transaction_date": "2022-12-31 00:00:00",
"narration": "JOD 2022 Forex Balance Translation",
"amount": 0,
"balance": 0,
"credit": 0,
"debit": 0,
"contribution": 0,
"type": "Journal Entry",
"date": "Dec 31, 2022"
},
{
"id": 4,
"account_id": 2,
"currency_id": 1,
"reporting_period_id": 1,
"credited": false,
"transaction_type": "JN",
"transaction_date": "2022-12-31 00:00:00",
"narration": "KPW 2022 Forex Balance Translation",
"amount": 0,
"balance": 0,
"credit": 0,
"debit": 0,
"contribution": 0,
"type": "Journal Entry",
"date": "Dec 31, 2022"
}
]
}
Opening Balances #
The Opening Balances Endpoint retrieves the Balances recorded for the Account Resource for the Reporting Period.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/account/1/balances'
import requests
url = "https://api.microbooks.io/books/v1/account/1/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/account/1/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/account/1/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/account/1/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",
"account_balances": [
{
"uuid": "339c1d88-9653-4e19-8bef-9ddc84cf936c",
"id": 1,
"entity_id": 1,
"account_id": 1,
"currency_id": 4,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "maxime",
"transaction_date": "2021-10-21 16:17:55",
"transaction_no": "esse",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Supplier Bill",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...}
},
{
"uuid": "d08c2d44-cb33-4c80-b8af-1adf5493744d",
"id": 2,
"entity_id": 1,
"account_id": 1,
"currency_id": 6,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "repellendus",
"transaction_date": "2021-10-21 16:17:55",
"transaction_no": "soluta",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Client Invoice",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...}
},
{
"uuid": "039cce94-9df6-4bbe-ae30-44eddc160281",
"id": 3,
"entity_id": 1,
"account_id": 1,
"currency_id": 8,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "iste",
"transaction_date": "2021-10-21 16:17:55",
"transaction_no": "odit",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Journal Entry",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...}
},
{
"uuid": "b50feee7-7d54-4918-bd19-15dd7d3cab90",
"id": 4,
"entity_id": 1,
"account_id": 1,
"currency_id": 11,
"exchange_rate_id": 6,
"reporting_period_id": 1,
"reference": "deserunt",
"transaction_date": "2021-10-21 16:17:56",
"transaction_no": "quia",
"balance_type": "CREDIT",
"balance": "40.0000",
"transaction_name": "Supplier Bill",
"amount": 40,
"type": "Credit",
"is_posted": true,
"is_credited": true,
"exchange_rate": {...}
},
{
"uuid": "f2ce00ad-4298-4720-8ac6-493a2f385881",
"id": 5,
"entity_id": 1,
"account_id": 1,
"currency_id": 13,
"exchange_rate_id": 6,
"reporting_period_id": 1,
"reference": "non",
"transaction_date": "2021-10-21 16:17:56",
"transaction_no": "aliquid",
"balance_type": "CREDIT",
"balance": "40.0000",
"transaction_name": "Supplier Bill",
"amount": 40,
"type": "Credit",
"is_posted": true,
"is_credited": true,
"exchange_rate": {...}
}
]
}
Errors #
Below are the Errors that are returned by the Account Resource.
| Detail Code | Name | Definition |
|---|---|---|
| 100 | Orphaned Items | Cannot recycle the Account Resource because it has dependent Resources |
| 101 | Missing Entity | The Account Resource requires an existing Entity because it is used for grouping Transactions made for the Entity in accordance with the rules of IFRS |
| 102 | Missing Account Type | Each Account Resource must have an Account Type to enable the platform to enforce the IFRS/Bookeeping Rules that apply to the type in order to produce IFRS compatible reports |
| 103 | Invalid Account Type | The type of the Account Resource is invalid for the action according to the Rules of IFRS/Bookeeping |
| 104 | Invalid Category Type | The type of the Account Resource must match the Account Type of the Category Resource its being assigned to |
Types of Accounts #
Non-Current Asset Account #
Also called fixed asset accounts, these track transactions that affect the long term assets of the entity such as machinery and motor vehicles.
Contra Asset Account #
The balances of these accounts reduce a specific asset account balannce. Examples are Provision for Bad Debts and Accumulated Depreciation.
Inventory Account #
The value of stocks held for sale is recorded in accounts of this type.
Bank Account #
Accounts of this type contain liquid Cash assets of the entity.
Current Asset Account #
These accounts contain assets that are expected to be realized within a Reporting Period.
Receivable Account #
Accounts of this type keep track of amounts owed to the entity by clients arising from Sales made on Credit.
Non-Current Liability Account #
These accounts contain obligations that are expected to be settled over durations of more than one Reporting Period.
Control Account #
These accounts serve as checks for reconciling recurring short term liabilities. Examples include Salaries Account and Vat account.
Current Liability Account #
These accounts contain liabilities that are expected to be setlled within a Reporting Period.
Payable Account #
Accounts of this type keep track of amounts owed by the entity to suppliers arising from Purchases made on Credit.
Equity Account #
The value of owners’s interest in the Entity is recorded in accounts of this type.
Operating Revenue Account #
These accounts record amounts arising from Sales from the core business of the entity.
Operating Expense Account #
These accounts record amounts arising from direct Purchases from the core business of the entity.
Operating Revenue Account #
These accounts record income amounts but from transactions arising from activities other than the core business of the entity. An example of such income is profit on disposal of fixed assets or capital gains.
Direct Expense Account #
These accounts record expenses that have to do with the administration of the Entity.
Overhead Expense Account #
These accounts record expenses that have to do with the utilities consumed of the Entity in the course of its business.
Other Expense Account #
These accounts record expenses that do not fit either of the above classes such as depreciation and donations.
Reconciliation Account #
These accounts are used to reconcile the balances of all other accounts. An example is a suspense account.