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.

Automatic bulk assignment
Client Receipts (RC) and Supplier Payments (PY) are bulk assigned automatically when they are created, so you do not normally need to call this endpoint for them. Where the settling Transaction and the Transactions it clears have differing exchange rates, pass forex_account_id so the realized foreign exchange difference has somewhere to post.

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	HTTP Status	Name	Definition
101	400	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	400	Negative Amount	An Assignment cannot be made for negative amounts
103	400	Mixed Assignment	A Transaction has been Cleared cannot be Assigned and vide versa
104	400	Missing Forex Account	Forex Account Resource selected for the Transaction does not exist
105	400	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	400	Unclearable Transaction	Only Transactions of types Client Invoice, Supplier Bill and Journal Entry can be cleared
107	400	Unassignable Transaction	Only Transactions of types Client Receipt, Supplier Payment, Credit Note, Debit Note and Journal Entry can be assigned
108	400	Overclearance	A Transaction cannot be cleared beyond its total amount
109	400	Self Clearance	A Transaction clearing itself is meaningless
110	400	Insufficient Balance	The Assignment Transaction has an unassigned amount less than the Assignment amount
111	400	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	400	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	400	Unposted Assignment	A Transaction must be posted to be Assigned
114	400	Invalid Clearance Account	The Assignment and Cleared Transactions must have the same Main Account
115	400	Invalid Clearance Currency	The Assignment and Cleared Transactions must have the same Main Currency
116	400	Invalid Clearable	The Transaction or Balance Resource selected to be assigned does not exist
117	400	Invalid Transaction	Compound Transactions can neither be Assigned nor Cleared
null	400	Resource Not Found	The Transaction/Balance Resource could not be found
422	422	Validation	A field is missing, malformed or not recognised. The field is the key under `errors`

Errors use the standard error envelope, which also lists the request-level codes (401, 403, 404, 429 and others) that any endpoint can return.