KSeF.Dev

Contact

Api

Explore our guides and examples

Contact Sales

API docs

API documentation can be found under:

It describes available endpoints and communication model classes.

Table of Contents

Introduction

ksef.dev is an application aimed at facilitating communication with polish National System of e-Invoices (Krajowy System e-Faktur, https://www.podatki.gov.pl/ksef/). It’s main features consist of:
  • fetching invoices from the system
  • sending invoices to the system
  • live notifications about changes (including notification about new invoices)
All kind of operations can only be done in a context of a particular company, identified by polish tax number (NIP). Such context is called integration

Integration creation (API)

Integrations can only be created for authorized ksef.dev user. It’s done in following steps:
1. For authorized user call POST /integrations endpoint. Specify tax number and name for the integration. You can specify integration starting date (if not specified, default is current time). You can specify webhook url for notification delivery (if not specified, notifications can be obtained from POST /notifications/receive endpoint)

Exemplary call:

				
					curl -X 'POST' \
  'https://api.ksef.dev/integrations' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "taxNo": "1111111111",
  "name": "exemplary name",
  "startingDateTime": "2023-01-01T00:00:00",
  "webhook": {
    "url": "https://exemplary.delivery-endpoint.pl/tax-no/1111111111"
  }
}'

The call returns id of created integration.

2. Provide necessary information to complete the integration. It can be either KSeF token or signed challenge file.

a. For challenge file path, download the challenge file from ksef.dev via POST /integrations/<id>/auth/signature/create-file-to-sign endpoint. You must specify to which KSeF environment you want to connect. You can choose only from officially supported environments: Test, Demo or Prod

Exemplary call:

				
					curl -X 'POST' \
  'https://api.ksef.dev/integrations/<INTEGRATION ID>/auth/signature/create-file-to-sign' \
  -H 'accept: application/xml' \
  -H 'Content-Type: application/json' \
  -d '{
  "environment": "Prod"
}'

The call returns content of XML file to sign.

b. Sign the file. You can use government official Signer application: https://moj.gov.pl/nforms/signer/upload?xFormsAppName=SIGNER&xadesPdf=true

c. Upload signed file to ksef.dev via POST /integrations/<id>/auth/signature/upload-signed-file endpoint.

Exemplary call:

				
					curl -X 'POST' \
  'https://api.ksef.dev/integrations/<INTEGRATION ID>/auth/signature/upload-signed-file' \
  -H 'accept: */*' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@response_1698086003508.xml'

This operations completes the integration creation.

3. Alternatively you can choose to complete the integration with token id. It’s NOT recommended since it requires to acquire authorization token in plain text from end users which is considered to be a security risk. However if you choose to use that option, you can complete the integration via POST /integations/<INTEGRATION ID>/auth/token endpoint. You must specify KSeF environment you want to connect to.

Exemplary call:

				
					curl -X 'POST' \
  'https://api.ksef.dev/integrations/<INTEGRATION ID>/auth/token' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "insertYourTokenHere",
  "environment": "Prod"
}'

This operation is followed up by token asynchronous token verification. After it’s completed, the integration is active. ksef.dev sends notification after verification is completed via chosen notification channel (webhook or notifications endpoint).

Integration creation (widget)

Alternatively users can use our widget created to guide them through the integration creation process.

1. First step is creation of the integration the same way as in the API way, since this operations requires users credentials.

Exemplary call:

				
					curl -X 'POST' \
  'https://api.ksef.dev/integrations' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "taxNo": "1111111111",
  "name": "exemplary name",
  "startingDateTime": "2023-01-01T00:00:00",
  "webhook": {
    "url": "https://exemplary.delivery-endpoint.pl/tax-no/1111111111"
  }
}'

The call returns id of created integration.

2. For such integration id, you can start our widget:

https://widget.ksef.dev/?integration-id=<YOUR INTEGRATION ID>

Alternatively you can also start widget without specifying the integration id and provide at the first step of the widget

3. Choose authorization option and environment:

a. For signature option, choose either your option (profil zaufany or podpis kwalifikowany) and follow the instructions: download the file, sign it and upload again

b. For token option follow the instructions: generate token in KSeF web application and paste the token to the widget:

4. After submition verification process begins. The widget can be closed, the verification process runs in background

5. After successful verification, the widget informs about the outcome

User creation

In order to obtain user credentials contact our sales team.

Invoice issuing (API)

After creation of integration through either API or widget, you can issue e-Invoice by sending XML to KSeF.

1. Prepare XML payload which complies with the specified XSD schema. Refer to the KSeF documentation for the required XML structure.

Exemplary call:

				
					<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns:etd="http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/">
	<Naglowek>
		<KodFormularza kodSystemowy="FA (2)" wersjaSchemy="1-0E">FA</KodFormularza>
		<WariantFormularza>2</WariantFormularza>
		<DataWytworzeniaFa>2022-01-01T00:00:00Z</DataWytworzeniaFa>
		<SystemInfo>SamploFaktur</SystemInfo>
	</Naglowek>
	<Podmiot1>
		<DaneIdentyfikacyjne>
			<NIP>9999999999</NIP>
			<Nazwa>ABC AGD sp. z o. o.</Nazwa>
		</DaneIdentyfikacyjne>
		<Adres>
			<KodKraju>PL</KodKraju>
			<AdresL1>ul. Kwiatowa 1 m. 2</AdresL1>
			<AdresL2>00-001 Warszawa</AdresL2>
		</Adres>
		<DaneKontaktowe>
			<Email>abc@abc.pl</Email>
			<Telefon>667444555</Telefon>
		</DaneKontaktowe>
	</Podmiot1>
	<Podmiot2>
		<DaneIdentyfikacyjne>
			<NIP>1111111111</NIP>
			<Nazwa>F.H.U. Jan Kowalski</Nazwa>
		</DaneIdentyfikacyjne>
		<Adres>
			<KodKraju>PL</KodKraju>
			<AdresL1>ul. Polna 1</AdresL1>
			<AdresL2>00-001 Warszawa</AdresL2>
		</Adres>
		<DaneKontaktowe>
			<Email>jan@kowalski.pl</Email>
			<Telefon>555777999</Telefon>
		</DaneKontaktowe>
		<NrKlienta>fdfd778343</NrKlienta>
	</Podmiot2>
	<Fa>
		<KodWaluty>PLN</KodWaluty>
		<P_1>2022-02-15</P_1>
		<P_1M>Warszawa</P_1M>
		<P_2>FV2022/02/150</P_2>
		<P_6>2022-01-27</P_6>
		<P_13_1>1666.66</P_13_1>
		<P_14_1>383.33</P_14_1>
		<P_13_3>0.95</P_13_3>
		<P_14_3>0.05</P_14_3>
		<P_15>2051</P_15>
		<Adnotacje>
			<P_16>2</P_16>
			<P_17>2</P_17>
			<P_18>2</P_18>
			<P_18A>2</P_18A>
			<Zwolnienie>
				<P_19N>1</P_19N>
			</Zwolnienie>
			<NoweSrodkiTransportu>
				<P_22N>1</P_22N>
			</NoweSrodkiTransportu>
			<P_23>2</P_23>
			<PMarzy>
				<P_PMarzyN>1</P_PMarzyN>
			</PMarzy>
		</Adnotacje>
		<RodzajFaktury>VAT</RodzajFaktury>
		<FP>1</FP>
		<DodatkowyOpis>
			<Klucz>preferowane godziny dowozu</Klucz>
			<Wartosc>dni robocze 17:00 - 20:00</Wartosc>
		</DodatkowyOpis>
		<FaWiersz>
			<NrWierszaFa>1</NrWierszaFa>
			<UU_ID>aaaa111133339990</UU_ID>
			<P_7>lodówka Zimnotech mk1</P_7>
			<P_8A>szt.</P_8A>
			<P_8B>1</P_8B>
			<P_9A>1626.01</P_9A>
			<P_11>1626.01</P_11>
			<P_12>23</P_12>
		</FaWiersz>
		<FaWiersz>
			<NrWierszaFa>2</NrWierszaFa>
			<UU_ID>aaaa111133339991</UU_ID>
			<P_7>wniesienie sprzętu</P_7>
			<P_8A>szt.</P_8A>
			<P_8B>1</P_8B>
			<P_9A>40.65</P_9A>
			<P_11>40.65</P_11>
			<P_12>23</P_12>
		</FaWiersz>
		<FaWiersz>
			<NrWierszaFa>3</NrWierszaFa>
			<UU_ID>aaaa111133339992</UU_ID>
			<P_7>promocja lodówka pełna mleka</P_7>
			<P_8A>szt.</P_8A>
			<P_8B>1</P_8B>
			<P_9A>0.95</P_9A>
			<P_11>0.95</P_11>
			<P_12>5</P_12>
		</FaWiersz>
		<Platnosc>
			<Zaplacono>1</Zaplacono>
			<DataZaplaty>2022-01-27</DataZaplaty>
			<FormaPlatnosci>6</FormaPlatnosci>
		</Platnosc>
		<WarunkiTransakcji>
			<Zamowienia>
				<DataZamowienia>2022-01-26</DataZamowienia>
				<NrZamowienia>4354343</NrZamowienia>
			</Zamowienia>
		</WarunkiTransakcji>
	</Fa>
	<Stopka>
		<Informacje>
			<StopkaFaktury>Kapiał zakładowy 5 000 000</StopkaFaktury>
		</Informacje>
		<Rejestry>
			<KRS>0000099999</KRS>
			<REGON>999999999</REGON>
			<BDO>000099999</BDO>
		</Rejestry>
	</Stopka>
</Faktura>

2. Dispatch invoice

Exemplary call:

				
					curl -X 'POST' \
  'https://api.ksef.dev/integrations/{YOUR_INTEGRATION_ID}/invoice-dispatches/single' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR API-KEY>' \
  -H 'Content-Type: application/xml' \
	-d '<?xml version="1.0" encoding="UTF-8"?>
  <Faktura>
      <!-- Invoice details -->
  </Faktura>'

The call returns

				
					{
    integrationId: <YOUR_INTEGRATION_ID>,
		environment: "Demo",
    hash: "nIuRQWP6z68cpEeNzB21bBad6irm32VndruhfYDmca8="
}
That response is worth preserving in order to monitor the status or troubleshooting. After it’s completed, ksef.dev sends notification via chosen notification channel (webhook or notifications endpoint).

KSeF.dev short description

For Clients

API

Pricing

Formal

Contact Us

Privacy Policy