KSeF REST API – technical (integration) documentation
for the National e-Invoice System
Introduction
This documentation describes the REST API interface enabling comprehensive implementation of structured invoice handling in the KSeF system.
The detailed API definition is available in an OpenAPI-compatible format and can be downloaded as a file JSON.
The API is also available in the form of a client interface Swagger UI.
Registration and account creation
In order to test the capabilities of the REST KSEF API, it is necessary to complete the registration process, i.e. create a dedicated account on the website. To do this, please visit the website Registration and fill in the appropriate form. The necessary condition for using the service system is acceptance of the Regulations. Correct completion of the form and clicking the button Register creates an account in the system and automatically activates it.
During the first login, an ID and the corresponding key are generated automatically. The ID and key can be found after logging in to your account in the tab API keys. The identifier is public and does not require protection, while the key is private and should not be made available to third parties.
Attention! To use the operations provided in the REST KSEF API, you must save the access token generated for the KSeF production or test environment, respectively, and enable access to the given type of environment.
Environment
To facilitate integration for our clients in the area of KSeF invoices, we have prepared two identical environments: test and production, which are connected to the KSeF test and production environments.
Testing environment
Full functionality of all exposed operations in the REST KSEF API and libraries, you can check using the provided test environment.
Testing environment REST KSEF API is integrated with the environment test National e-Invoice System and is available at: https://ksefapi.pl/api-test/
All operations available within the KSEF API REST environment are also available from the shared level libraries.
Thanks to the REST KSEF API test environment, it is possible to check all operations offered in paid KSeF packages, without having to buy them.
Attention! To use the KSEF API REST operations in a test environment, simply save the access token generated in the KSeF test environment and activate access to this type of environment.
Production environment
The REST KSEF API production environment is integrated with the environment production National e-Invoice System and is available at: https://ksefapi.pl/api/
Attention! To use the KSEF API REST operation in a production environment, you must save the access token generated in the KSeF production environment, activate access to this type of environment and purchase any KSEF package.
Authentication and authorization of queries
The provided API interface uses the standard HTTP protocol. API operations (methods) use HTTP GET or POST methods. Each operation call requires query authorization. Authorization of executed queries is possible using Basic Authentication
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 + ':' + keyWhere:
key_id– API key ID, which can be found on the tab API keys.key– API key, the value of which can be found on the tab API keys.
If the key ID had a value test_id, and the key had a value test_key, then 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.ksefapi.pl/ksef/api-test/invoice/generateWhere:
test_id– example key ID value. To authenticate in a production or test environment, the parameter should contain the correct key ID used for authentication,test_key– example key value. To authenticate in a production or test environment, the parameter should contain a valid value for the key used for authentication.
The key identifier and the key are generated by the user after logging in to his account (tab API keys).