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.

Incorrect response

In case of any error related to handling the request, the following error message is returned:

Detailed description of returned attributes:

• code – unique error code for automatic error handling,
• description – a description of the error that can be caught by a human,
• details – detailed description of the error (optional),

Error codes

Error code	Error message	Description
7	The VAT number is invalid	Incorrect Tax Identification Number provided (algorithm checksum does not match)
8	Invalid request format	Incorrect format of the submitted request
10	Invalid API path	In the library configuration, the wrong URL address for the API path was entered. The correct path to the production API is: https://nip24.pl/api/
11	Internal service error	Internal service error
20	NIP, REGON or KRS number was not provided	A required parameter was not sent in the request.
22	EU VAT number is invalid	The EU VAT number provided in the input parameter has an invalid format. See the table of valid EU VAT numbers
23	Failed to get data from VIES system	Error downloading data from VIES system
26	This feature is not available on the currently selected plan	The feature is not available in the currently selected plan. Use the free getAccountStatus feature to retrieve the current account status information
27	This function does not support this search mode	The function is not available in search mode
30	Searching by NIP number is not available in the currently selected plan	Searching by Tax Identification Number is not available in the currently selected plan
33	Querying the given data is not possible in the test mode	The request cannot be handled in test mode
35	No access query authorization required	Access denied. Sending the request requires correct authorization. Select one of the two possible authentication methods.
36	The service is temporarily unavailable due to scheduled technical work	Service unavailable due to maintenance work
43	The number of user queries for the current month could not be retrieved	Error while retrieving information about the number of currently used requests
54	Incorrect date or time on the user\s computer or system	Incorrect date or time on the system from which the request was sent. Please set the correct date and time.
55	Invalid MAC string value in header with query credentials	The MAC value sent in the header does not match the authentication data
57	Invalid key value in header with query credentials	Invalid API key in request header
58	The maximum number of concurrent queries for this Member State has been reached	VIES returned information that the tax system of the requested Member State has reached its capacity limit. Please try again in a moment
59	The application at the Member State is not replying or not available	The VIES system or the system of a specific Member State does not correspond
101	The connection IP number does not match the IP number assigned to the API key	The IP address from which the request was sent does not match the IP address in the account configuration.
102	API key is blocked	The API key used for authentication is blocked
103	Invalid API key	Invalid API key
104	The maximum number of queries available for the selected plan has been reached	The maximum number of queries performed in a given plan has been used. Log in to your account to purchase more queries
105	Account blocked or deleted	Account has been blocked or deleted. Please contact customer service.
106	Invalid account type	The error is most often returned in case of incorrectly entered identifier. Check the correctness of the identifier sent in the request.
107	The pre-paid account has not been paid	The user account has not been paid. Log in to your account to pay for services
108	Invalid API key ID	The key corresponding to the sent identifier was not found. Check the correctness of the identifier sent in the request.
201	Failed to connect to the VIES API service	Error connecting to VIES system
202	VIES API service response has invalid format	VIES returned an incorrect response
203	Invalid number type	Errors numeric type
204	NIP is invalid	Incorrect tax identification number
205	EU VAT ID is invalid	Incorrect EU VAT number
206	Function generated an exception	The function generated an exception. Please contact support for assistance: kontakt@nip24.pl
207	Date has an invalid format	Date format is invalid. Use format: YYYY-MM-DD HH:MM:SS
208	Invalid input parameter	Invalid input parameter