KSeF REST API – technical (integration) documentation
for the National e-Invoice System

KSeF API logo

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 i wypełnić odpowiedni formularz. Warunkiem koniecznym do korzystania z systemu serwisu jest akceptacja Regulaminu. Poprawne wypełnienie formularza i kliknięcie przycisku 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

Udostępniony interfejs API wykorzystuje standardowy protokół HTTP. Operacje (metody) API wykorzystują metody HTTP GET lub POST. Każde wywołanie operacji wymaga autoryzacji zapytania. Autoryzacja wykonywanych zapytań możliwa jest z wykorzystaniem Basic Authentication

Uwierzytelnienie 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 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/generate

Where:

  • 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).

Click here to see the rest of the KSeF REST API documentation which is available on a dedicated website