Assignments #

Assignments relate Transactions that have opposite effects on the balance of the Account which they have in common. Assignable Transactions such as Client Receipts have Clearable Transactions such as Client Invoices assigned to them for clearance.

Properties #

Direct Properties #

Property	Type	Definition
Type	String	The type of the Resource that is cleared by this assignment, either Transaction or Balance

Indirect Properties #

Property	Type	Definition
Transaction	Dictionary	The Transaction being assigned
Cleared	Dictionary	The Transaction being cleared
Forex Account	Dictionary	In case the Transactions are in a foreign currency, and there is a difference between the Exchange Rate of the Transaction being cleared and being assigned, the gain or loss from this difference is posted to this Account

Basics #

The parameters required to create an Assignment are the Id of the Transaction being assigned, a list of Id’s of the Resources to be cleared, the amount to be cleared on each and the type of each (Transaction or Balance).

Request #

Curl

curl --location --request POST 'api.microbooks.io/books/v1/assignment/assign-transactions' \
--data-raw '{
	"transaction_id": 1,
    "cleared_ids": [4,1],
    "cleared_amounts": [25,15],
    "cleared_types": ["Transaction","Balance"]
}'

Python

import requests

url = "https://api.microbooks.io/books/v1/assignment/assign-transactions"
body = {
    "transaction_id": 1,
    "cleared_ids": [4,1],
    "cleared_amounts": [25,15],
    "cleared_types": ["Transaction","Balance"]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/assignment/assign-transactions',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "transaction_id": 1,
        "cleared_ids": [4,1],
        "cleared_amounts": [25,15],
        "cleared_types": ["Transaction","Balance"]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '{
    "transaction_id": 1,
    "cleared_ids": [4,1],
    "cleared_amounts": [25,15],
    "cleared_types": ["Transaction","Balance"]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/assignment/assign-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/assignment/assign-transactions");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"transaction_id\": 1,
    \"cleared_ids\": [4,1],
    \"cleared_amounts\": [25,15],
    \"cleared_types\": [\"Transaction\",\"Balance\"]
}";
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 Transactions assigned successfully"
    "assigned": [
        {
            "id": 4,
            "amount": 25,
            "type": "Transaction"
        },
        {
            "id": 1,
            "amount": 15,
            "type": "Balance"
        }
    ]
}

Variations #

Bulk Assignment #

When a settlement is made against the outanding balance on an Account without specifying which individual Transactions should be assigned to it, calling this endpoint will assign the amount on the settlling Transaction to the outstanding Transactions on the Account on a First in First out basis until its exhausted.

Request #

Curl

curl --location --request POST 'api.microbooks.io/books/v1/assignment/bulk-assign-outstanding' \
--data-raw '{
	"transaction_id": 1
}'

Python

import requests

url = "https://api.microbooks.io/books/v1/assignment/bulk-assign-outstanding"
body = {
    "transaction_id": 1,
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/assignment/bulk-assign-outstanding',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "transaction_id": 1,
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '{
    "transaction_id": 1,
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/assignment/bulk-assign-outstanding', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/assignment/bulk-assign-outstanding");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"transaction_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": "Journal Entry: JN01/0001 for 100.00 Transactions bulk assigned successfully",
    "assigned": [
        {
            "id": 4,
            "number": "JN01/0003",
            "amount": 75
        },
        {
            "id": 6,
            "number": "JN01/0005",
            "amount": 25
        }
    ]
}

Errors #

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

Detail Code	Name	Definition
101	Missing Entity	The Assignment Resource requires an existing Entity because it is applied to Transactions, for the purpose of preparing Financial Statements which are scoped to an Entity
102	Negative Amount	An Assignment cannot be made for negative amounts
103	Mixed Assignment	A Transaction has been Cleared cannot be Assigned and vide versa
104	Missing Forex Account	Forex Account Resource selected for the Transaction does not exist
105	Invalid Clearance Entry	A Transaction in an Assignment must have the opposite effect on the balance of the Account to that of the Transaction being cleared
106	Unclearable Transaction	Only Transactions of types Client Invoice, Supplier Bill and Journal Entry can be cleared
107	Unassignable Transaction	Only Transactions of types Client Receipt, Supplier Payment, Credit Note, Debit Note and Journal Entry can be cleared
108	Overclearance	A Transaction cannot be cleared beyond its total amount
109	Self Clearance	A Transaction clearing itself is meaningless
110	Insufficient Balance	The Assignment Transaction has an unassigned amount less than the Assignment amount
111	Missing Forex Account	The Assignment requires a Forex Account where the differences from the Exchange Rates of the Assigned and Cleared Transactions will be posted
112	Invalid Account Type	The Forex Account must be of type `Account::EQUITY` if the Transaction being cleared is from a previous Reporting Period (A Balance Resource) or of type `Account::NON_OPERATING_REVENUE` if from within the current Reporting Period
113	Unposted Assignment	A Transaction must be posted to be Assigned
114	Invalid Clearance Account	The Assignment and Cleared Transactions must have the same Main Account
115	Invalid Clearance Currency	The Assignment and Cleared Transactions must have the same Main Currency
116	Invalid Clearable	The Transaction or Balance Resource selected to be assigned does not exist
117	Invalid Transaction	Compound Transactions can neither be Assigned nor Cleared
null	Resource Not Found	The Transaction/Balance Resource could not be found