Exchange Rates #

An Exchange Rate defines the value of a Foreign Currency in terms of of the Reporting Currency. Rates can either be used for Foreign Currency Transactions or for closing Foreign Currency denominated Accounts at the end of the Reporting Period. Each Exchange Rate must have an associated (Foreign) Currency Resource and a date from which it its valid (will be used in transactions). While the end date at which the Resource is no longer valid is not required, Exchange Rates periods for the same Currency Resource cannot overlap.

Properties #

Direct Properties #

Property	Type	Definition
Rate	Float	The value of the Foreign Currency in terms of the Reporting Currency
Valid From	Date	The date from which the Resource applies
Valid To	Date	The date after which the Resource is no longer valid

Indirect Properties #

Property	Type	Definition
Currency	Dictionary	The Foreign Currency Resource associated with the Exchange Rate

Basics #

To record an Exchange Rate, you need to provide the Foreign Currency Resource id, the rate and the valid from date.

Request #

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/exchange-rate' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "currency_id": 1,
        "valid_from": "2022-07-20",
        "rate": 1.5
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/exchange-rate"
body = {
    "currency_id": 1,
    "valid_from": "2022-07-20",
    "rate": 1.5
}
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/exchange-rate',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "currency_id": 1,
        "valid_from": "2022-07-20",
        "rate": 1.5
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '{
    "currency_id": 1,
    "valid_from": "2022-07-20",
    "rate": 1.5
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/exchange-rate', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/exchange-rate");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"currency_id\": \"1\",
    \"valid_from\": \"2022-07-20\",
    \"rate\": \"1.5\" 
}";
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": "ExchangeRate: 100.00 for Euro (EUR) from 2022-07-20 created successfully",
        "resource": {
        "valid_from": "2022-07-20T00:00:00.000000Z",
        "currency_id": 2,
        "rate": 100,
        "entity_id": 1,
        "id": 4,
        "currency": {
            "uuid": "7b87e7e9-0e23-44aa-9694-ba9ccfc0091b",
            "id": 2,
            "user_id": 1,
            "name": "Euro",
            "currency_code": "EUR"
        }
    }
}

Errors #

Below are the Errors that are returned by the Exchange Rate Resource.

Detail Code	Name	Definition
100	Orphaned Items	Cannot recycle the Exchange Rate Resource because it has dependent Resources
101	Missing Entity	The Exchange Rate Resource requires an existing Entity because it is used for calculating Forex differences between Transactions and these must be associated with an Entity Resource
102	Overlapping Exchange Rates	To eliminate ambiguity in reporting, only one Exchange Rate Resource can be valid at a given point in time such that all Transactions recorded for the currency during the period all have the same rate