The following sub-points are intended for developers who wish to interface with the e-Financials API. For technical questions arising during the interface, please contact @email
API Resources/Services
The services offered and the data structures they use are described using the OpenAPI specification version 3.1 in YAML format. They are JSON-in JSON-out RESTful services.
API application server address:
DEMO: https://demo-rmp-api.rik.ee (demo/training companies can be used for testing)
LIVE: https://rmp-api.rik.ee
Requests must be sent to the correct adapter version, e.g. application server address /v1
The latest description of the services is available from the API application server at /openapi.yaml
The HTML version of the documentation (available in English only) is also available from the API application server at /api.html
A test page for checking requests (including the ability to generate headers from a key) is available from the API application server at /test.html
API Business Logic Workflow
The business logic workflow that occurs in the application layer depends on the specific request and the use case that it covers. The typical process is divided into the following steps:
- Authentication and authorization of the interfacing information system – the ApiKey in the request header is checked against the data registered in the system. If such an ApiKey does not exist or is not allowed from an external IP address, a negative access event is logged. If a sufficient number of negative access events occur within a given period of time, access from the external IP address is blocked for a certain period. If the ApiKey exists and is correct, the request is allowed to continue processing.
- Identifying the service to be executed from the URL – the API identifies the service to be executed based on the routing table or returns an error if it is not available.
- The request is validated against the OpenAPI specification of the service being used – input format (generally none or JSON data set), content and structure (mandatory and allowed fields, etc.). Requests that do not meet the specification will be rejected with an error.
- The service performs data queries and processing according to the input.
- The service returns a response in JSON format or, in exceptional cases (if the response to the request is a single file), the corresponding file in binary format as a standard HTTP response.
Authentication and authorization of requests
Access to API services is secured via an ApiKey “key”, which can be generated by the company using the e-Financials in the e-Financials configuration module
The public part of each ApiKey key contains a unique identifier and a cryptographic “signature” to prevent brute-force guessing of identifiers. The “password” part of the ApiKey key is used to sign the request (to prevent replay attacks). In addition, the e-Financials database contains additional private information about the ApiKey, e.g. allowed IP addresses, etc.
Each request to API services must include an HTTP header called X-AUTH-QUERYTIME, which contains the timestamp of the request (UTC, accurate to one second) (e.g.: 2011-11-04T00:05:23).
Each request to API services must include an HTTP header named X-AUTH-KEY, which contains, separated by a colon:
- ApiKey public key, which is case-sensitive and must be transmitted exactly as presented in the e-Financials (e.g.:RWksIHNpaW4gdGVnZWxpa3VsdCBlaSBvbGUgcGFyaXMgQXBpS2V5LWQsIGFnYSB0dWJsaSBrYXRzZS4gSmFyZ21pc2VzIHR1a2lzIG9uIGphcnNrdSBtaWRhZ2kgaHV2aXRhdmFtYXQ=);
- Request signature BASE64(HMAC-SHA-384("apikeyid:time:url", ApiKeyPassword)), where:
- apikeyid is the unique identifier of the ApiKey (provided in the e-Financials, e.g.: 530156f2101045438c8c3513eed6e893)
- time is the time of execution of the request transmitted in the X-AUTH-QUERYTIME header
- url is the absolute path of the service to be accessed without the protocol and server component, e.g.: /v1/journals/62307/document_user)
- ApiKeyPassword is the ApiKey password provided in the e-Financials.
e.g.: RWksIHNpaW4gdGVnZ…Wxpa3RhZ2kgaHV2aXRhdmFtYXQ=:6JMLK6Gt…KJmbTWrCs/XcCaSV
When a new request arrives at the API services without an X-AUTH-KEY header, an HTTP 401 error code is returned.
The API retrieves the private data of the ApiKey from the database based on the unique identifier and checks the cryptographic “signature” contained in the ApiKey against the system data. If the ApiKey is not valid for any reason, a negative access event is logged and an HTTP 401 error code is returned.
If the request does not include the X-AUTH-QUERYTIME header or the time of the request differs from the server time by 5 or more minutes in either direction, a negative access event is logged and an HTTP 401 error code is returned.
If the request signature is not valid, a negative access event is logged and an HTTP 401 error code is returned.
If more than a specified number of negative access events are logged from the IP address that is the source of the request in a specified period, the request is blocked for a specified period of time, regardless of anything else, including any valid ApiKey value in the header. This is done to prevent brute-force guessing attacks. A negative access event is logged and an HTTP 401 error code is returned.
| Control period | Min. number of neg. events | Blocked period |
|---|---|---|
| Last 5 minutes | 10 |
Until the number of negative events falls below all limits |
| Last 60 minutes | 30 | Until the number of negative events falls below all limits |
| Last 24 hours | 60 |
Until the number of negative events falls below all limits |
In other cases, the API service is launched.
Logging requests
A company's authorized representative can view the log of authenticated (successful) requests via the user interface in API key management.
API key management in the user interface
API keys can be managed by a company's authorized representative in the General Settings view of the Settings module.
The user can:
- add new API keys;
- change the general data of existing keys (name, accessible functions and allowed IP addresses);
- download the public keys of existing keys (ApiKey public key);
- view the history of key usage;
- delete keys