Transactions

Transactions #

Transactions are the primary means via which the platform records data on financial events relating to an Entity. Each Transaction represents a single financial event and contains the Accounts affected by the event on both sides of the Double Entry, whose amounts must balance thereby maintaining the integrity of the Ledger.

Properties #

Direct Properties #

PropertyTypeDefinition
Transaction DateDateThe date Transaction occurred
Transaction NumberStringA unique identifier for the Transaction, generated in sequence if none is provided
AmountFloatThe total amount of the Transaction
NarrationStringA short description of the Transaction
Is CreditedBooleanIndicates whether the Transaction’s main account was posted to the Credit side of the Double Entry
Is PostedBooleanIndicates whether the Transaction has been commited to the Ledger
CompoundBoolean(For Journal Entries) Indicates whether the Transaction has Line Items on both sides of the Double Entry
AssignableBooleanIndicates whether the Transaction can be used to clear Clearable Transactions
ClearableBooleanIndicates whether the Transaction can be cleared by Assignable Transactions
Has IntegrityBooleanIndicates whether the Transaction’s Ledger records have not been tampered with
Transaction typestringMust be one of the types described in the API reference here
Transaction namestringA human readable version of the Transaction type
TaxListThe Types and total amounts of Taxes recorded for the Transaction’s Line Items
DiscountListThe Types and total amounts of Discounts recorded for the Transaction’s Line Items

Indirect Properties #

PropertyTypeDefinition
CurrencyDictionaryThe Currency of the Transaction
AccountDictionaryThe main Account of the Transaction. In most cases, this Resource aggregates the amounts of the Line Items posted to one side of the Double Entry (Debit/Credit) and has the total posted to it on the opposite side
Exchange RateDictionaryThe Exchange Rate of the Transaction
Line ItemsListThe Line Items associated with the Transaction. The Account Resource of each Line Item represent one side of the Double Entry
AssignmentsListFor Transactions that can be used to clear the amounts outstanding on other Transactions, this list shows those Transactions that have been assigned to it for clearance and the amounts cleared
ClearancesListFor Transactions that can be cleared, this list shows those Transactions that have been used to clear their outstanding amounts and the amounts cleared

Basics #

The parameters required to create a Transaction Resource are the Id of the Account for which the Balance is for and the Transaction’s type, narration and date.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/transaction' \
--data-raw '{
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    
}'

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
}
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/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": 1,
        "transaction_type": "JN",
        "narration": "Test Transaction",
        "transaction_date": "2022-07-25",
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": 1,
	\"transaction_type\": \"JN\",
	\"narration\": \"Test Transaction\",
	\"transaction_date\": \"2022-07-25\",
}";
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": "Journal Entry: JN01/0003 created successfully",
    "resource": {
        "transaction_type": "JN",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "currency_id": 2,
        "account_id": 1,
        "narration": "Test Transaction",
        "compound": false,
        "transaction_no": "JN01/0003",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 3,
        "transaction_name": "Journal Entry",
        "is_posted": false,
        "is_credited": true,
        "assignable": true,
        "clearable": true,
        "has_integrity": true,
        "clearances": [],
        "assignments": []
    }
}

Variations #

With Line Items #

By adding Line item information, including taxes and discounts on each Item, you can create and directly attach Line Items to the Transaction in a single call. More details about paramaters for creating Line Items can be found here.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/transaction' \
--data-raw '
    "currency_id": 2,
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    "compound": false,
	"line_items": [	{
		"account_id": 2,
		"quantity": 20,
		"amount": 10,
		"narration": "Line Item 1"
	},{
        "account_id": 2,
        "amount": 10,
        "narration": "Line Item 2"
    }]'

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "currency_id": 2,
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    "compound": false,
	"line_items": [{
		"account_id": 2,
		"quantity": 20,
		"amount": 10,
		"narration": "Line Item 1"
	},{
        "account_id": 2,
        "amount": 10,
        "narration": "Line Item 2"
    }]
}
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/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "currency_id": 2,
        "account_id": 1,
        "transaction_type": "JN",
        "narration": "Test Transaction",
        "transaction_date": "2022-07-25",
        "compound": false,
        "line_items": [{
            "account_id": 2,
            "quantity": 20,
            "amount": 10,
            "narration": "Line Item 1"
        },{
            "account_id": 2,
            "amount": 10,
            "narration": "Line Item 2"
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "currency_id": 2,
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    "compound": false,
	"line_items": [{
		"account_id": 2,
		"quantity": 20,
		"amount": 10,
		"narration": "Line Item 1"
	},{
        "account_id": 2,
        "amount": 10,
        "narration": "Line Item 2"
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"currency_id\": 2,
	\"account_id\": 1,
	\"transaction_type\": \"JN\",
	\"narration\": \"Test Transaction\",
	\"transaction_date\": \"2022-07-25\",
    \"compound\": false,
	\"line_items\": [{
		\"account_id\": 2,
		\"quantity\": 20,
		\"amount\": 10,
		\"narration\": \"Line Item 1\"
	},{
        \"account_id\": 2,
        \"amount\": 10,
        \"narration\": \"Line Item 2\"
    }]
}";
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": "Journal Entry: JN01/0003 for 210.00 created successfully",
    "resource": {
        "transaction_type": "JN",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "currency_id": 2,
        "account_id": 1,
        "narration": "Test Transaction",
        "compound": false,
        "transaction_no": "JN01/0003",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 3,
        "transaction_name": "Journal Entry",
        "is_posted": false,
        "is_credited": true,
        "amount": 210,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": true,
        "has_integrity": true,
        "line_items": [
            {
                "uuid": "166d90f2-996c-4a87-a83d-d487e8a1e282",
                "id": 3,
                "entity_id": 1,
                "account_id": 2,
                "transaction_id": 3,
                "narration": "Line Item 1",
                "amount": "10.0000",
                "quantity": "20.0000",
                "tax_inclusive": false,
                "compound_tax": false,
                "entry_type": "DEBIT",
                "credited": false,
                "tax": {
                    "total": 0
                },
                "discount": {
                    "total": 0
                },
                "net_amount": 200,
                "has_withholding_tax": false,
                "has_gross_discount": false,
                "has_operations_discounts": false
            },
            {
                "uuid": "7f48ebe9-ecf9-4d5d-8401-9fe4ac0e732f",
                "id": 4,
                "entity_id": 1,
                "account_id": 2,
                "transaction_id": 3,
                "narration": "Line Item 1",
                "amount": "10.0000",
                "quantity": "1.0000",
                "tax_inclusive": false,
                "compound_tax": false,
                "entry_type": "DEBIT",
                "credited": false,
                "tax": {
                    "total": 0
                },
                "discount": {
                    "total": 0
                },
                "net_amount": 10,
                "has_withholding_tax": false,
                "has_gross_discount": false,
                "has_operations_discounts": false
            }
        ],
        "clearances": [],
        "assignments": []
    }
}

Compound Journal Entry #

A compound Journal Entry allows for the specifying of arbitrary sides of the Double Entry for the main and Line Item Accounts of the Transaction. The totals of each side must balance, which is why an amount also needs to be specified for the main Account.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/transaction' \
--data-raw '
    "currency_id": 2,
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    "main_account_amount" => 50,
    "compound": true,
    "credited": true,
	"line_items": [	{
		"account_id": 2,
		"quantity": 2,
		"amount": 30,
        "credited": false,
		"narration": "Line Item 1"
	},{
        "account_id": 3,
        "amount": 10,
        "credited": true,
        "narration": "Line Item 2"
    }]'

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "currency_id": 2,
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    "main_account_amount" => 50,
    "compound": true,
    "credited": true,
	"line_items": [	{
		"account_id": 2,
		"quantity": 2,
		"amount": 30,
        "credited": false,
		"narration": "Line Item 1"
	},{
        "account_id": 3,
        "amount": 10,
        "credited": true,
        "narration": "Line Item 2"
    }]'
}
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/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "currency_id": 2,
        "account_id": 1,
        "transaction_type": "JN",
        "narration": "Test Transaction",
        "transaction_date": "2022-07-25",
        "main_account_amount" => 50,
        "compound": true,
        "credited": true,
        "line_items": [	{
            "account_id": 2,
            "quantity": 2,
            "amount": 30,
            "credited": false,
            "narration": "Line Item 1"
        },{
            "account_id": 3,
            "amount": 10,
            "credited": true,
            "narration": "Line Item 2"
        }]'
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "currency_id": 2,
	"account_id": 1,
	"transaction_type": "JN",
	"narration": "Test Transaction",
	"transaction_date": "2022-07-25",
    "main_account_amount" => 50,
    "compound": true,
    "credited": true,
	"line_items": [	{
		"account_id": 2,
		"quantity": 2,
		"amount": 30,
        "credited": false,
		"narration": "Line Item 1"
	},{
        "account_id": 3,
        "amount": 10,
        "credited": true,
        "narration": "Line Item 2"
    }]'
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"currency_id\": 2,
	\"account_id\": 1,
	\"transaction_type\": \"JN\",
	\"narration\": \"Test Transaction\",
	\"transaction_date\": \"2022-07-25\",
    \"main_account_amount\" => 50,
    \"compound\": true,
    \"credited\": true,
	\"line_items\": [	{
		\"account_id\": 2,
		\"quantity\": 2,
		\"amount\": 30,
        \"credited\": false,
		\"narration\": \"Line Item 1\"
	},{
        \"account_id\": 3,
        \"amount\": 10,
        \"credited\": true,
        \"narration\": \"Line Item 2\"
    }]'
}";
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": "Journal Entry: JN01/0001 for 60.00 created successfully",
	"resource": {
		"transaction_type": "JN",
		"transaction_date": "2023-02-02T18:18:03.000000Z",
		"currency_id": 2,
		"account_id": 1,
		"narration": "Test Transaction",
		"compound": true,
		"main_account_amount": 50,
		"transaction_no": "JN01/0001",
		"exchange_rate_id": 1,
		"entity_id": 1,
		"id": 1,
		"transaction_name": "Journal Entry",
		"is_posted": false,
		"is_credited": true,
		"amount": 60,
		"tax": {
			"total": 0
		},
		"assignable": true,
		"clearable": true,
		"has_integrity": true,
		"line_items": [
			{
				"uuid": "d56cb44e-db4b-4ecc-8db0-99554520e919",
				"id": 1,
				"entity_id": 1,
				"account_id": 2,
				"transaction_id": 1,
				"narration": "Line Item 1",
				"amount": "30.0000",
				"quantity": "2.0000",
				"tax_inclusive": false,
				"compound_tax": false,
				"entry_type": "DEBIT",
				"tax": {
					"total": 0
				},
				"discount": {
					"total": 0
				},
				"net_amount": 60,
				"has_withholding_tax": false,
				"has_gross_discount": false,
				"has_operations_discounts": false
			},
			{
				"uuid": "ccd00990-c9bc-499c-9d46-7a271e9163ee",
				"id": 2,
				"entity_id": 1,
				"account_id": 3,
				"transaction_id": 1,
				"narration": "Line Item 2",
				"amount": "10.0000",
				"quantity": "1.0000",
				"tax_inclusive": false,
				"compound_tax": false,
				"entry_type": "CREDIT",
				"tax": {
					"total": 0
				},
				"discount": {
					"total": 0
				},
				"net_amount": 10,
				"has_withholding_tax": false,
				"has_gross_discount": false,
				"has_operations_discounts": false
			}
		],
		"clearances": [],
		"assignments": []
    }
}

Operations #

Get Line Items #

The Line Items that have been recorded for a Transaction can be retrieved by calling this endpoint.

Request #

curl --location --request GET 'api.microbooks.io/books/v1/transaction/1/line-items'

import requests

url = "https://api.microbooks.io/books/v1/transaction/1/line-items"
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/transaction/1/line-items',
    '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 = '{}';
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/1/line-items', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/1/line-items");
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",
    "line_items": [
        {
            "uuid": "8427f78b-2bb3-48ef-aef1-41ab3ceeff54",
            "id": 1,
            "entity_id": 1,
            "account_id": 4,
            "transaction_id": 1,
            "narration": "Voluptas molestias alias pariatur.",
            "amount": "50.0000",
            "quantity": "1.0000",
            "tax_inclusive": false,
            "compound_tax": false,
            "entry_type": "DEBIT",
            "credited": false,
            "tax": {
                "total": 0
            },
            "discount": {
                "total": 0
            },
            "net_amount": 50,
            "has_withholding_tax": false,
            "has_gross_discount": false,
            "has_operations_discounts": false
        },
        {
            "uuid": "fd45fcfe-0cfe-4b11-a29e-08a6b8c011da",
            "id": 2,
            "entity_id": 1,
            "account_id": 6,
            "transaction_id": 1,
            "narration": "Tempora velit illo molestiae distinctio officiis id minus.",
            "amount": "50.0000",
            "quantity": "1.0000",
            "tax_inclusive": false,
            "compound_tax": false,
            "entry_type": "DEBIT",
            "credited": false,
            "tax": {
                "total": 0
            },
            "discount": {
                "total": 0
            },
            "net_amount": 50,
            "has_withholding_tax": false,
            "has_gross_discount": false,
            "has_operations_discounts": false
        }
    ]
}

Get Assignments #

For a Transaction that can be used to clear other Transactions a list of clearable Transactions that have been assigned to it retrieved by calling this endpoint.

Request #

curl --location --request GET 'api.microbooks.io/books/v1/transaction/1/assignments'

import requests

url = "https://api.microbooks.io/books/v1/transaction/1/assignments"
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/transaction/1/assignments',
    '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 = '{}';
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/1/assignments', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/1/assignments");
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",
    "assignments": [
        {
            "uuid": "1f3d4602-2728-4bd3-8a11-c1357e495958",
            "id": 1,
            "entity_id": 1,
            "transaction_id": 1,
            "forex_account_id": null,
            "assignment_date": "2022-10-24 18:36:17",
            "cleared_id": 2,
            "amount": "50.0000",
            "type": "Transaction"
        },
        {
            "uuid": "a7bb8810-e5a1-4e56-8827-1d071dc3c15d",
            "id": 2,
            "entity_id": 1,
            "transaction_id": 1,
            "forex_account_id": null,
            "assignment_date": "2022-10-24 18:36:17",
            "cleared_id": 3,
            "amount": "15.0000",
            "type": "Transaction"
        }
    ]
}

Get Clearances #

For a Transaction that can be cleared by other Transactions, a list of assignable Transactions to which it has been assigned for clearance can be retrieved by calling this endpoint.

Request #

curl --location --request GET 'api.microbooks.io/books/v1/transaction/1/clearances'

import requests

url = "https://api.microbooks.io/books/v1/transaction/1/clearances"
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/transaction/1/clearances',
    '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 = '{}';
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/1/clearances', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/1/clearances");
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",
    "clearances": [
        {
            "uuid": "01864875-d756-4b93-9484-7230f1d9157d",
            "id": 1,
            "entity_id": 1,
            "transaction_id": 2,
            "forex_account_id": null,
            "assignment_date": "2022-10-24 18:40:36",
            "cleared_id": 1,
            "amount": "50.0000",
            "type": "Transaction"
        },
        {
            "uuid": "107f55f8-ca4f-4adf-9ccd-af816bd53ec6",
            "id": 2,
            "entity_id": 1,
            "transaction_id": 3,
            "forex_account_id": null,
            "assignment_date": "2022-10-24 18:40:36",
            "cleared_id": 1,
            "amount": "15.0000",
            "type": "Transaction"
        }
    ]
}

Add Items #

Line Items can be added to an unposted Transaction by calling this endpoint with an array of thier ids. Therefore the Line Items to be added must already be existing in the system.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/transaction/add-items/1' \
--data-raw '
    "line_items": [1],
    "transaction_type": "JN"

import requests

url = "https://api.microbooks.io/books/v1/transaction/add-items/1"
body = {
    "line_items": [1],
    "transaction_type": "JN"
}
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/transaction/add-items/1',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "line_items": [1],
        "transaction_type": "JN"
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "line_items": [1],
    "transaction_type": "JN"
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction/add-items/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/add-items/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"line_items\": [1],
    \"transaction_type\": \"JN\"
}";
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": "Journal Entry: JN01/0001 for 50.00 Line Items added successfully",
    "resource": {
        "uuid": "30d79554-1c71-4262-918b-0b3466897baa",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "currency_id": 3,
        "exchange_rate_id": 2,
        "transaction_date": "2022-10-24T17:59:23.000000Z",
        "reference": "quibusdam",
        "transaction_no": "JN01/0001",
        "transaction_type": "JN",
        "narration": "Quo mollitia quis eos.",
        "credited": true,
        "compound": false,
        "main_account_amount": "0.0000",
        "transaction_name": "Journal Entry",
        "is_posted": false,
        "is_credited": true,
        "amount": 50,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": true,
        "has_integrity": true,
        "line_items": [
            {
                "uuid": "7097b010-b038-4f8d-8e5c-6ff383764f73",
                "id": 1,
                "entity_id": 1,
                "account_id": 4,
                "transaction_id": 1,
                "narration": "Est necessitatibus sed quia doloribus id minima sapiente.",
                "amount": "50.0000",
                "quantity": "1.0000",
                "tax_inclusive": false,
                "compound_tax": false,
                "entry_type": "DEBIT",
                "credited": false,
                "tax": {
                    "total": 0
                },
                "discount": {
                    "total": 0
                },
                "net_amount": 50,
                "has_withholding_tax": false,
                "has_gross_discount": false,
                "has_operations_discounts": false
            }
        ],
        "clearances": [],
        "assignments": []
    }
}

Remove Items #

Line Items can be removed from an unposted Transaction by calling this endpoint with an array of thier ids.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/transaction/remove-items/1' \
--data-raw '
    "line_items": [1, 2],
    "transaction_type": "JN"

import requests

url = "https://api.microbooks.io/books/v1/transaction/remove-items/1"
body = {
    "line_items": [1, 2],
    "transaction_type": "JN"
}
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/transaction/remove-items/1',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "line_items": [1, 2],
        "transaction_type": "JN"
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "line_items": [1, 2],
    "transaction_type": "JN"
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction/remove-items/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/remove-items/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"line_items\": [1, 2],
    \"transaction_type\": \"JN\"
}";
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": "Journal Entry: JN01/0001 for 0.00 LineItems removed successfully",
    "resource": {
        "uuid": "b101e406-3df1-4bfd-9f12-86f831e6e136",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "currency_id": 3,
        "exchange_rate_id": 2,
        "transaction_date": "2022-10-24T18:00:26.000000Z",
        "reference": "enim",
        "transaction_no": "JN01/0001",
        "transaction_type": "JN",
        "narration": "Qui temporibus aut ratione aliquam et sed tenetur.",
        "credited": true,
        "compound": false,
        "main_account_amount": "0.0000",
        "transaction_name": "Journal Entry",
        "is_posted": false,
        "is_credited": true,
        "amount": 0,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": true,
        "has_integrity": true,
        "line_items": [],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

When a Transaction is recorded it is kept in a Pending state, i.e. holding all the relevant information about the financial event it relates to but not yet committed to the ledger. During this stage, a Transaction may be edited and Line Items may be added/removed from it. Calling this endpoint commits the Transaction to the Ledger, which also makes it immutable.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/transaction/post/1'

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/1"
body = {}
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/transaction/post/1',
    '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 = '{}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction/post/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
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",
    "message": "Journal Entry: JN01/0001 for 100.00 posted successfully",
    "resource": {
        "uuid": "fc32e97d-094b-4752-876d-1d55f9f3dc08",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "currency_id": 3,
        "exchange_rate_id": 2,
        "transaction_date": "2022-10-24T17:58:18.000000Z",
        "reference": "veritatis",
        "transaction_no": "JN01/0001",
        "transaction_type": "JN",
        "narration": "Ut porro dicta aut laboriosam aperiam.",
        "credited": true,
        "compound": false,
        "main_account_amount": "0.0000",
        "transaction_name": "Journal Entry",
        "is_posted": true,
        "is_credited": true,
        "amount": 100,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": true,
        "has_integrity": true,
        "line_items": [
            {
                "uuid": "44947f70-6497-4a45-b14c-0215cc6ef156",
                "id": 1,
                "entity_id": 1,
                "account_id": 4,
                "transaction_id": 1,
                "narration": "Enim consequatur totam quasi explicabo dolorum.",
                "amount": "50.0000",
                "quantity": "2.0000",
                "tax_inclusive": false,
                "compound_tax": false,
                "entry_type": "DEBIT",
                "credited": false,
                "tax": {
                    "total": 0
                },
                "discount": {
                    "total": 0
                },
                "net_amount": 100,
                "has_withholding_tax": false,
                "has_gross_discount": false,
                "has_operations_discounts": false
            }
        ],
        "exchange_rate": {
            "uuid": "f97adf30-5aba-46f2-99f9-95e2c8b11037",
            "id": 2,
            "entity_id": 1,
            "currency_id": 1,
            "valid_from": "2022-10-24T17:58:18.000000Z",
            "valid_to": null,
            "rate": "1.0000"
        },
        "clearances": [],
        "assignments": []
    }
}

Errors #

Below are the Errors that are returned by the Transaction Resource.

Detail CodeNameDefinition
100Orphaned ItemsCannot recycle the Transaction Resource because it has dependent Resources
101Missing EntityThe Transaction Resource requires an existing Entity because it is the basis for posting the amounts that contitute the Financial Statements which are scoped to the Entity
102Missing Reporting PeriodA Transaction Resource requires a Reporting Period encompassing its Transaction Date to exist before it can be created
103Invalid CurrencyThe Transaction Resource Currency must be same that of the provided Account Resource
104Invalid Transaction TypeThe Transaction Type cannot be changed once a transaction is saved as the the Accounts of the Line Item Resources already allocated to it might be invalid according to the rules of Bookkeeping/IFRS
105Invalid Transaction DateThe Transaction cannot be created at the exact moment that the financial year begins. A Balance Resource should be used instead
106Adjusting Reporting PeriodOnly Transactions of type Journal Entry can be created for a Reporting Period in the ReportingPeriod::ADJUSTING status. This is so that auditors can pass entries to the books from their findings during the Audit
107Closed Reporting PeriodTransaction Resources cannot be created for a Reporting Period in the ReportingPeriod::CLOSED status as this would alter reports that have already been Audited and/or published
108Missing Line ItemA Transaction Resource must have at least one Line Item to be posted to satisfy the Double Entry Rule
109Unbalanced TransactionTransaction Resources of type Journal Entry, which allow arbitrary allocation of of amounts to either side of the Double Entry, the total amount allocated to the Debit side must equal that on the Credit side to satisfy the Double Entry Rule
110Posted TransactionTo maintain the integrity of the Ledger, a Transaction Resource can neither be modified nor deleted once it has been posted. One would have to cancel it via its reversing Transaction and then create a new one
111Redundant TransactionA Transaction that has the no effect on the balance of an Account by posting the same amounts on opposite sides of the Double Entry is meaningless
112Hanging ClearancesA Transaction Resource that has been used to clear other Transactions cannot be deleted as this would leave the clearances hanging
113Unposted AssignmentFor a Transaction Resource wither to be assigned to another or to have others assigned to it for Clearance it must first be posted, since assignment affects the balances of the Accounts involved, and unposted Transactions have no effect yet on the Ledger
114Main AccountThe Transaction Type and the Account Type of the Main Account selected for the the Transaction Resource are incompatible according to the rules of Bookkeeping/IFRS
115Line Item AccountThe Transaction Type and the Account Type of one of the Line Item Accounts selected for the Transaction Resource are incompatible according to the rules of Bookkeeping/IFRS
116Missing Main Account AccountTransaction Resources of type Journal Entry, which allow arbitrary allocation of of amounts to either side of the Double Entry, the Main Account of the Transaction needs to have an amount (the side of the double entry to post it is determined by the Transaction Type) so as to satisfy the Double Entry Rule
117Tax ChargeLine Items of the Transaction Resource of the selected Transaction Type cannot be charged Tax according to the
118Line ItemSome of the Line Items of the Transaction Resource have failed to be validated
404Resource Not FoundThe Transaction Resource could not be found

Transaction Types #

Cash Sale #

This Transaction represents the simplest sales fincancial event where some goods or services are exchanged for cash immediately. As such, the main account of the Transaction must be of type BANK while the accounts of each of its Line Items must be of type OPREATING_REVENUE. The Line Items may also have Taxes and/or Discounts. The total amount is posted to the Credit side of this Transaction’s main Account.

Client Invoice #

The other kind of Sales Transaction, a Client Invoice records a sale that is expected to be paid for at a later time, i.e. a Credit Sale. The main account of the Transaction must be of type RECEIVABLE and just like the Cash Sale, the accounts of each of its Line Items must be of type OPREATING_REVENUE. The Line Items may also have Taxes and/or Discounts. The total amount is posted to the Credit side of this Transaction’s main Account.

Credit Note #

This Transaction functions to reverse a Credit Sale, either fully or partially. Like the Client Invoice the main account of the Transaction must be of type RECEIVABLE and the accounts of each of its Line Items must be of type OPREATING_REVENUE. The Line Items may also have Taxes and/or Discounts. The total amount is posted to the Debit side of this Transaction’s main Account.

Client Receipt #

This Transaction records the arrival of Cash from a Client towards the clearance of sales made on credit. The main account of the Transaction must be of type BANK and each of its Line Items must be of type RECEIVABLE. The Line Items cannot have either Taxes or Discounts. The total amount is posted to the Debit side of this Transaction’s main Account.

Cash Purchase #

This Transaction represents the simplest purchase fincancial event where some goods or services are exchanged for cash immediately. As such, the main account of the Transaction must be of type BANK while the accounts of each of its Line Items must be one of type OPERATING_EXPENSE, DIRECT_EXPENSE, OVERHEAD_EXPENSE, OTHER_EXPENSE, NON_CURRENT_ASSET, CURRENT_ASSET, INVENTORY. The Line Items may also have Taxes and/or Discounts. The total amount is posted to the Credit side of this Transaction’s main Account.

Supplier Bill #

The other kind of Purchase Transaction, a Supplier Bill records a purchase that is expected to be paid for at a later time, i.e. a Credit Purchase. The main account of the Transaction must be of type PAYABLE and just like the Cash Purchase, the accounts of each of its Line Items must be one of type OPERATING_EXPENSE, DIRECT_EXPENSE, OVERHEAD_EXPENSE, OTHER_EXPENSE, NON_CURRENT_ASSET, CURRENT_ASSET, INVENTORY. The Line Items may also have Taxes and/or Discounts. The total amount is posted to the Credit side of this Transaction’s main Account.

Debit Note #

This Transaction functions to reverse a Credit Purchase, either fully or partially. Like the SUpplier Bill the main account of the Transaction must be of type PAYABLE and just like the Cash Purchase, the accounts of each of its Line Items must be one of type OPERATING_EXPENSE, DIRECT_EXPENSE, OVERHEAD_EXPENSE, OTHER_EXPENSE, NON_CURRENT_ASSET, CURRENT_ASSET, INVENTORY. The Line Items may also have Taxes and/or Discounts. The total amount is posted to the Debit side of this Transaction’s main Account.

Supplier Payment #

This Transaction records the transfer of Cash to a Supplier towards the clearance of purchases made on credit. The main account of the Transaction must be of type BANK and each of its Line Items must be of type PAYABLE. The Line Items cannot have either Taxes or Discounts. The total amount is posted to the Debit side of this Transaction’s main Account.

Contra Entry #

This Transaction records the movement of Cash between Bank accounts. Both the the main account of the Transaction and the accounts of each of its Line Items must be of type BANK. The Line Items cannot have either Taxes or Discounts. The total amount is posted to the Credit side of this Transaction’s main Account.

Journal Entry #

The most powerful Transaction type, A Journal Entry allows the recording of amounts to any Account in the General Ledger. As such, there are no restrictions on the type of Accounts on the Transaction itself and on any of its Line Items. The Line Items may have Taxes and/or Discounts, and additionally, the side of the Double entry to which the amounts for both the main and Line Item Accounts may be set arbitrarily, as long as the todal Debit and Credit Amounts balance.