REST API documentation

Introduction

The API we provide uses the standard HTTP protocol. All API functions use the HTTP GET method. Each function call requires query authorization. Data for query authorization is sent in the HTTP header.

Production service

Registration is required for the entity that wants to use the functionality of the nip24.pl system. To do this, please visit the website Registration and complete the appropriate form. A necessary condition for using the nip24.pl system is acceptance of the regulations. Complete the form correctly and click the button Register causes the creation of an account in the nip24.pl system and its automatic activation.

During the first login, an ID and the corresponding key are generated automatically. The identifier is public and does not require protection, while the key is private and should not be made available to third parties.

Production service address: https://www.nip24.pl/api

Test service

The full functionality of all shared libraries can be checked using the shared library Test API. Thanks to the test API, it is possible to check all functions offered in paid plans without having to create an account.

Production service address: https://www.nip24.pl/api-test

API definition

The detailed API definition is available in an OpenAPI-compatible format and can be downloaded as a YAML file here.

The API is also available in the form of a client interface Swagger UI.

Query execution

Example of a query to a test website:

GET /api-test/get/invoice/nip/7171642051 HTTP/1.1 Host: www.nip24.pl:443 Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value" User-Agent: NIP24Client/client_version platform_name/platform_version Accept: mime_type

Where:

  • api_key_id – API key identifier (in the production environment, the value of the identifier generated during registration, in the test environment, the value test_id),
  • unix_timestamp – current time in the form of the number of seconds since the so-called unix epoch,
  • random_str – random string, different for each query (min. 8 characters, max. 16 characters),
  • b64_calculated_mac_value – calculated HMAC (using the API key, in the test environment the value test_key),
  • client_version – API client version (in our libraries it is the version of our API library, e.g. 1.3.0),
  • platform_name – name of the API client platform (in our libraries it is the name of the library language, e.g. Java, PHP, .NET, Python),
  • platform_version – version of the API client platform (in our libraries it is the version of the library environment, e.g. 1.8.0 for Java, or 5.6.4 for PHP),
  • mime_type – type name MIME, in which the response is to be returned, two types are supported: application/xml and application/json, if the request does not contain a header, XML is returned by default.

Inquiry authorization

Authorization data must be prepared in accordance with HTTP Authentication: MAC Access Authentication and this is the recommended authentication method. It is also possible to use the method HTTP Authentication: Basic Authentication, but for security reasons, please use it only if for some reason the first method is not possible.
Each query to our website must be authenticated using one of two available methods.

Method 1 – Authentication using MAC Authentication

Specification of the authorization method used: HTTP Authentication: MAC Access Authentication. Preparing the authorization header for a query sent to our website using this method involves calculating HMAC SHA256 from an appropriately prepared string and sending the result in the HTTP header.

Example

The input string to the HMAC function is:

ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Where:

  • ts – current time in the form of the number of seconds since the so-called unix epoch, you should always provide the current query execution time (server tolerance +/- 10 min in relation to the current time),
  • nonce – random string, different for each query (min. 8 characters, max. 16 characters),
  • method – HTTP method name (always GET),
  • path – URL path of the query to be executed,
  • host – NIP24 server name (always www.nip24.pl),
  • port – NIP24 server port number (always 443),
  • '\n' – newline character (ASCII code 10 0x0A).

For a query about invoice data for NIP 7171642051 sent to the test service on 2019-11-25 00:00:00 UTC the input string to the HMAC function will look like this:

str = "1574640000\ndt831hs59s\nGET\n/api-test/get/invoice/nip/7171642051\nwww.nip24.pl\n443\n\n"

The downloadable input string file for this example here.

From the prepared string we calculate HMAC SHA256, as the HMAC password we provide the API key, i.e. in the case of the test API, the value test_key:

HMAC_SHA256(str, "test_key") = 0a35fa77fc29c30feb48c4b831929f2f85ed833f56b4617832a09facaca1bd55

The HMAC SHA256 function returns 32 binary bytes (shown as a hexadecimal string above for readability). File with binary value to download here.
The binary value of the calculated HMAC should be encoded with the algorithm Base64, we get:

CjX6d/wpww/rSMS4MZKfL4Xtgz9WtGF4MqCfrKyhvVU=

This value should be sent as the MAC value in the header with authorization data. Ultimately:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="CjX6d/wpww/rSMS4MZKfL4Xtgz9WtGF4MqCfrKyhvVU="

Method 2 – Authentication using Basic Authentication

Specification of the authorization method used: HTTP Authentication: Basic Authentication. Preparing the authorization header for a query sent to our website using this method involves encoding the appropriately prepared string with the Base64 function and sending the result in the HTTP header.

Example

The input string to the Base64 function is:

str = key_id + ':' + key

Where:

  • key_id – API key identifier (in the case of a test environment, string test_id),
  • key – API key (in the case of a test environment, string test_key).

For the test environment, the input string for the Base64 function will be:

str = "test_id:test_key"

After applying the Base64 function we get:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

This value should be sent as a Basic value in the header with authorization data. Ultimately:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Example

The following example shows a query that can be run in a test environment from a web browser. Just copy and paste it into your browser's address bar:

https://test_id:test_key@www.nip24.pl/api-test/get/vies/euvat/PL7171642051

Where:

  • test_id – key ID to be used only in the test environment. To authenticate in a production environment, the parameter should contain the correct key ID used for authorization,
  • test_key – key to be used only in a test environment. To authenticate in a production environment, the parameter should contain a valid value for the key used for authorization.

The key identifier and the key are generated by the user after logging in to his account on the nip24.pl portal (tab Klucze API).
View page documentationfor more information on generating IDs and keys.

en_GBEnglish (UK)
pl_PLPolski en_GBEnglish (UK)