Introduction
- fetching invoices from the system
- sending invoices to the system
- live notifications about changes (including notification about new invoices)
integration Integration creation (API)
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.
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
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.
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)
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="
}