Documentation version: 2.0 (changelog)

Version date: 2025-12-30

REST API Integration Documentation
for the National e-Invoice System (KSeF 2.0)

Components

For the purposes of this documentation, three basic components have been adopted that participate in business processes related to invoice handling within KSeF 2.0:

• Calling system
• REST API KSeF 2.0
• KSeF 2.0 System

Diagram: Components 

Calling system

The client's IT system that communicates with the KSeF System via the KSEF REST API.

National e-Invoice System (KSeF 2.0)

National e-Invoice System is a central repository of structured electronic invoices that is managed and maintained by the Ministry of Finance.

REST API KSeF 2.0

REST interface providing operations (methods) enabling comprehensive implementation business processes related to the processing of KSeF structured invoices

KSeF invoice handling processes

The chapter describes in detail the four main processes related to handling KSeF invoices:

• Generating a KSeF invoice (structured) according to the FA_v3 schema
• Sending invoices in an interactive session to KSeF and downloading UPO
• Searching and downloading invoices from KSeF (cost or sales)
• Downloading a single invoice from KSeF (cost or sales)

The individual steps of each process contain links to operations that must be called to complete a given step.

Generating a KSeF (structured) invoice
compliant with the FA_v3 schema

The purpose of the described process is to enable the generation of a KSeF invoice, the format and structure of which will be consistent with the latest, currently applicable scheme. The process describes a positive scenario and the steps that need to be taken to generate a KSeF structured invoice using the interface REST API KseF 2.0. Any call to an operation exposed on an interface REST API KSeF 2.0 may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF 2.0, are described in detail in the chapter Error messages.

Diagram: Generating a KSeF structured invoice

Description of the process:

1. Calling system prepares the request accordingly KsefInvoiceGenerateRequest and calls the method ksefInvoiceGenerate.

2. Then REST API KSeF 2.0 based on the data contained in the request, it generates an invoice XML file consistent with the current (current) version of the schema.

3. The generated invoice XML file is returned to calling system, which saves the invoice XML file on its side.

Sending invoices in an interactive session to KSeF and downloading UPO

The purpose of the described process is to send an invoice (or invoices) to KSeF, to National e-Invoice System as part of the created interactive session and downloading the Official Confirmation of Receipt from KSeF confirming the acceptance of the sent invoices by KSeF system. The process describes a positive scenario and the steps that need to be taken to send a structured invoice to KSeF using the interface REST API KSeF 2.0. Any call to an operation exposed on an interface REST API KSeF 2.0 may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF 2.0, but also KSeF system are described in detail in the chapter Error messages.

Diagram: Sending invoices in an interactive session to KSeF and downloading UPO

Description of the process:

1. For each generated apart from REST API KSeF invoices, we recommend triggering the operation ksefInvoiceValidate in order to check the correctness of the invoice with the schedule.
Attention! One of the reasons for rejection of an invoice by KSeF may be non-compliance with the applicable XSD scheme.

2. After verifying the correctness of the generated invoices, call the operation ksefSessionOpenOnline in order to create an interactive session within which the shipment will be carried out. Details describing the methods and types of session creation, as well as the possibilities associated with them, are described in the chapter describing a given method.

3. After successfully establishing an interactive session, KSeF system returns the session id (SessionId), which should be saved on the page Calling system, because this ID will be used to trigger other operations.

4. Then - before we start sending invoices - check whether the session we previously created is still active. This step is especially important when several minutes have passed since the session was created or the quality of the network connection is poor. To verify session activity, an operation must be invoked ksefSessionStatus, and as a call parameter provide the interactive session ID (SessionId).

5. If in response to a method call ksefSessionStatus, we have received information about the active status of the session, we can start iteratively sending all invoices by calling the operation this many times ksefInvoiceSend, how many invoices we intend to send to KSeF. In answer KSeF system should return in attribute id, technical identifier of the invoice (InvoiceId).

6. The returned technical identifier of the invoice (InvoiceId) should be written on the page Calling system, because this identifier will be used to trigger the operation checking the invoice receipt status (ksefInvoiceStatus) sent to KSeF system.

7. After sending all invoices [5] to KSeF and saving their technical identifiers [6], check the receipt status of each of the sent invoices. To do this, you need to trigger an operation for each sent invoice ksefInvoiceStatus with parameter InvoiceId, containing the technical identifier of the invoice.

8. If in response (KsefInvoiceStatusResponse) status of a given invoice (StatusInfo.code) has a value 200, this means that the invoice has been successfully saved in the KSeF system and we can save the invoice number generated by KSeF (invoiceKsefNumber) and the acquisition date (acquisitionDat), i.e. the exact date and time of saving KSeF system.

9. After downloading all KSeF numbers of outstanding invoices (invoiceKsefNumber) you must correctly end the interactive session by calling the operation ksefSessionClose with parameter SessionId (the session ID returned when it was created in step 3).

10. Only after closing the interactive session is it possible to trigger the operation ksefSessionUpo, with parameter SessionId (session identifier returned when creating it in step 3) returning the Official Confirmation of Receipt (UPO). UPO is returned as an object TextXmlContent.

11. The last step of the process is to save the downloaded UPO (TextXmlContent) on the side Calling system.

Searching and downloading invoices from KSeF (cost or sales)

The purpose of the described process is to asynchronously search and download found invoices (cost or sales) in National e-Invoice System. Individual operations are performed within the created interactive session. The process describes a positive scenario and the steps to be taken to search and download found invoices that meet the defined search criteria. In one call you can search for either your cost invoices or your sales invoices. Any call to an operation exposed on an interface REST API KSeF 2.0 may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF 2.0, but also KSeF system are described in detail in the chapter Error messages.

Diagram: Searching and downloading invoices from KSeF (cost or sales).

Description of the process:

1. First of all, you need to prepare the search criteria accordingly (KsefInvoiceQueryStartRequest) and initiate the asynchronous fact lookup process by calling the operation ksefInvoiceQueryStart.

2. After successfully sending your query, KSeF system returns the search ID (QueryId), which should be saved on the page Calling system, because this identifier will be used to trigger the operation to check the search status (whether invoices were found) and to download the found invoice packages.

3. To check whether any invoices meet the defined search criteria and have been found, you need to call the operation ksefInvoiceQueryStatus. In the returned response KsefInvoiceQueryStatusResponse, attribute content items[] informs about the number of parcels with found invoices. Each package is identified by a package ID (QueryPartNumber).

4. In order to retrieve invoices that meet the defined search criteria, for each returned batch of invoices (QueryPartNumber) trigger the operation ksefInvoiceQueryResult.

5. After downloading all found invoices (all packages), you need to decrypt all downloaded packages.

6. Then you need to unpack each downloaded package (ZIP archive) and save it on the site Calling system.

7. In order to generate a visualization for the downloaded invoice XML file from KSeF, the following operation should be called for each invoice: ksefInvoiceVisualize.

8. The last step of the process is to save the downloaded file (PDF or HTML) containing the KSeF invoice visualization.

Downloading a single invoice from KSeF (cost or sales)

The purpose of the described process is to download a specific invoice (cost or sales) in National e-Invoice System. Individual operations are performed within the created interactive session. The process describes the positive scenario and the steps needed to collect a single invoice for which it is known KSeF invoice number. Any call to an operation exposed on an interface REST API KSeF 2.0 may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF 2.0, but also KSeF system are described in detail in the chapter Error messages.

Diagram: Downloading a single invoice from KSeF (cost or sales).

Description of the process:

1. In the first step, call the operation ksefInvoiceGet, one of the parameters of which is the invoice number assigned by KSeF (InvoiceKsefNumber) .

2. The downloaded invoice in the form of an XML file should be saved on the page Calling systemIf we still have any KSeF invoice numbers for which we want to download invoices from KSeF, repeat the steps described in points 1-2.

3. Optional step. Depending on your business needs, the final step of the process may be to generate a visualization of the invoice in PDF or HTML format. To do this, you must invoke the operation ksefInvoiceVisualize and select the appropriate visualization parameters in the request.

4. Finally, all that remains is to save the returned invoice visualization on the side Calling system. 

Operations

This chapter describes the methods provided by the KSeF 2.0 REST API.

Figure: KSeF 2.0 REST API.

GET

HTTP GET methods.

ksefPublicKey

ksefPublicKey(): KsefPublicKeyResponse The method allows you to download the KSeF public key, which is used to encrypt the AES256 symmetric key used to encrypt transmitted XML invoices using the operation ksefInvoiceSend in session encryption mode - i.e. the set parameters: encryptedKey and initVector when creating a session (KsefSessionOpenOnlineRequest). The method does not require any parameter on the input, and on the output it returns a response consistent with KsefPublicKeyResponse. 

Diagram: ksefPublicKey Operation

Algorithm

Supported cryptographic key algorithms by KSeF. The enumeration is described in the chapter Algorithm. 

KsefPublicKeyResponse

The class contains the public key of the KSeF system and information about the algorithm according to which it was created.

algorithm : Algorithm – The algorithm according to which the public key was generated

publicKey : string – The public key in the form of the DER encoding of the ASN.1 SubjectPublicKeyInfo object in the form of a base64 string. The KSeF public key is used to encrypt a symmetric key (AES256), which should be generated before creating an encryption session, and then XML invoices sent to KSeF should be encrypted with this symmetric key.

ksefSessionStatus

ksefSessionStatus(sessionId : SessionId): KsefSessionStatusResponse The method retrieves the current session status. It takes a parameter in the call path (URL). SessionId. However, it returns in response KsefSessionStatusResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefSessionStatus Operation

SessionId

The parameter is described in the chapter SessionId. 

KsefSessionStatusResponse

A response containing the status of a given interactive or batch session

sessionInfo : SessionInfo – One of two possible interactive session statuses defined in the SessionInfo class.

SessionInfo

The class returns information about the current session status.

status : StatusInfo – A complex attribute that returns detailed information about the current session status.

batch : boolean – Value true attribute means that the given session is a batch session, enabling the sending of invoices in batch mode.

invoiceCount : int – The attribute specifies the number of invoices received within the session.

successfulInvoiceCount : int – The attribute specifies the number of invoices successfully processed within the session.

failedInvoiceCount : int – The attribute specifies the number of invoices processed within the session with an error.

ksefSessionClose

ksefSessionClose(sessionId : SessionId): KsefSessionCloseResponse The method allows you to close an interactive (online) or batch session set up with KSeF.
Attention! Correct closing of the interactive session is necessary to download the UPO, i.e. an object confirming the invoices received by KSeF. It takes a parameter in the call path (URL). SessionId. However, it returns in response KsefSessionCloseResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefSessionClose Operation

SessionId

The parameter is described in the chapter SessionId. 

KsefSessionCloseResponse

A response containing information about whether the interactive session was successfully completed

result : boolean – A value of True (1) means that the session ended successfully, while a value of False (0) indicates that the session failed to end successfully.

ksefSessionUpo

ksefSessionUpo(sessionId : SessionId): TextXmlContent The method allows you to download the Official Confirmation of Receipt (UPO) for all invoices that were sent as part of a given interactive session combined with KSeF.
Attention! Before calling the ksefSessionUpo operation, you must properly close the interactive session using the operation ksefSessionClose. UPO can only be downloaded for a session in which at least one invoice was issued correctly. It takes a parameter in the call path (URL). SessionId. In response, the operation returns an object TextXmlContent containing the UPO. Click on the name of the operation to go to Swagger UI.

Diagram: ksefSessionUpo Operation

SessionId

The parameter is described in the chapter SessionId. 

TextXmlContent

The class is described in the chapter TextXmlContent.

ksefInvoiceStatus

ksefInvoiceStatus(invoiceId : InvoiceId): KsefInvoiceStatusResponse The method allows you to check the processing status of the invoice sent to KSeF.
Attention! The method checks the processing status of the invoice sent to KSeF using the operation ksefInvoiceSend. The input method requires sending a parameter in the call path (URL). InvoiceId, and on the output it returns an answer consistent with KsefInvoiceStatusResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefInvoiceStatus Operation

InvoiceId

The class represents the technical identifier of the invoice, which is returned as an attribute id classes KsefInvoiceSendResponse, and can then be used to check the invoice processing status by triggering an operation ksefInvoiceStatus.

invoiceId : string – Invoice ID (technical)

KsefInvoiceStatusResponse

The class represents the response of the KSeF system in the context of the processing status of the invoice sent to KSeF.

invoices[] : InvoiceInfo – The attribute contains tables with information describing the status of sent invoices.

ksefInvoiceGet

ksefInvoiceGet(invoiceKsefNumber : InvoiceKsefNumber): KsefInvoiceGetContent The method allows you to download a single invoice from KSeF, specifying: KSeF number of the invoice.
The method requires a parameter to be sent in the call path (URL) on the input InvoiceKsefNumber, and on the output it returns an answer consistent with TextXmlContent if the invoice being downloaded is not encrypted or ApplicationOctetStreamContent when downloading an invoice in encrypted form. Click on the name of the operation to go to Swagger UI.

Diagram: ksefInvoiceGet Operation

InvoiceKsefNumber

The parameter is described in the chapter InvoiceKsefNumber.

Content

The class is described in the chapter Content.

ApplicationOctetStreamContent

The class is described in the chapter ApplicationOctetStreamContent.

TextXmlContent

The class is described in the chapter TextXmlContent.

ksefInvoiceQueryStatus

ksefInvoiceQueryStatus(queryId : QueryId): KsefInvoiceQueryStatusResponse The method allows you to obtain the search status of invoices in KSeF.
The input method requires sending a parameter in the call path (URL): QueryId, and on the output it returns an answer consistent with KsefInvoiceQueryStatusResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefInvoiceQueryStatus Operation

QueryId

The class contains a search ID that is generated by KSeF
queryId : string – Search process ID

KsefInvoiceQueryStatusResponse

The object represents the result of searching for invoices in KSeF

numberOfInvoices : int – Total number of returned invoices in the batch.

packageSize : int – The size of the packet in bytes to check whether the total sum of all parts is correct after receiving them.

isTruncated : boolean – Value true attribute indicates that the maximum allowable range of query results (10,000) has been reached.

partNumbers[]: string – The attribute contains an array with package IDs (each package is a ZIP file) of found invoices (QueryPartNumber) that met the search criteria defined in the class KsefInvoiceQueryStartRequest.

ksefInvoiceQueryResult

ksefInvoiceQueryResult(queryId : QueryId, queryPartNumber : QueryPartNumber): KsefInvoiceQueryResultZipContent The method allows you to download all invoices found in KSeF.
Attention! Calling a method requires a prior call to an operation ksefInvoiceQueryStart, which returns the search ID (QueryId).
Attention! Downloaded invoice packages in ZIP format (identified by QueryPartNumber), must be decrypted before unpacking. Each package must be decrypted using the symmetric AES256 key (encryptedKey), which was generated when creating the session (ksefSessionOpenOnline). The input method requires two parameters to be sent in the call path (URL): QueryId and QueryPartNumber, and on the output it returns an answer consistent with ApplicationZipContentClick on the name of the operation to go to Swagger UI.

Diagram: ksefInvoiceQueryResult Operation

QueryId

The class contains a search ID that is generated by KSeF.
queryId : string – Search process ID

QueryPartNumber

The class represents the search package number.

partNumber : string – Identifier of the fragment (package) of the search result

ApplicationZipContent

The class represents a ZIP archive with KSeF invoices in XML form
description : string – = ZIP archive with XML invoices

ksefSessionInvoices

ksefSessionInvoices(sessionId : SessionId): KsefSessionInvoicesResponse The method allows you to check the processing status of all invoices sent to KSeF.
Attention!The method checks the processing status of invoices sent to KSeF using the operation ksefSessionOpenBatch. The input method requires sending a parameter in the call path (URL). SessionId, and on the output it returns an answer consistent with KsefSessionInvoicesResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefSessionInvoices Operation

KsefSessionInvoicesResponse

invoices[] : InvoiceInfo – The attribute contains tables with information describing the status of sent invoices.

InvoiceInfo

The class represents an object containing information about the status of sent invoices.

status : StatusInfo – The attribute contains complete information describing the invoice status.

ordinal : string – The attribute contains the invoice sequence number within the session.

invoiceNumber : string – The attribute contains the invoice number.

ksefNumber : string – The attribute contains the assigned KSeF number.

acquisitionDate : string – This attribute specifies the exact time the invoice was accepted by the KSeF system (the KSeF number was assigned). The format returned is consistent with date-time.

permanentStorageDate : string – Date of permanent storage of the invoice in the KSeF repository. Value completed asynchronously at the time of permanent storage; always later than acquisitionDate. While checking the status, it may not be available yet. Returned format compatible with date-time.

StatusInfo

The class contains detailed information regarding the status of submitted invoices.

code : int – Invoice status code

description : string – Verbal description of the invoice status

details : string – Additional status details

extensions[ ] : StatusInfoAttribute – A collection of additional information related to invoice status, stored as key-value pairs. This allows the model to be extended with case-specific data.

The table below contains information on invoice statuses that can be provided by KSeF:

Code	Description	Details	Extensions
100	Invoice accepted for further processing	–	–
150	Processing in progress	–	–
200	Success	–	–
405	Processing canceled due to session error	–	–
410	Incorrect scope of permissions	–	–
415	It is not possible to send an invoice with an attachment	–	–
430	Invoice file verification error	–	–
435	File decryption error	–	–
440	Duplicate invoice	–	'originalSessionReferenceNumber', 'originalKsefNumber'
450	Invoice document semantics verification error	–	–
500	Unknown error ({statusCode})	–	–
550	The operation was canceled by the system	Processing was interrupted due to internal system issues. Please try again.	–

StatusInfoAttribute

The class represents additional information regarding the status of submitted invoices in a key-value format.

key : string – The attribute contains the name (key).

value : string – The attribute contains the value corresponding to the given key (attribute key).

 

POST

HTTP POST methods.

ksefSessionOpenOnline

ksefSessionOpenOnline(invoice : KsefSessionOpenOnlineRequest): KsefSessionOpenOnlineResponse The method allows you to set up an interactive session with the KSeF system, thanks to which it will be possible to send invoices to KSeF using the operation ksefInvoiceSend. The input method requires the creation of a request consistent with KsefSessionOpenOnlineRequest, and on the output it returns an answer consistent with KsefSessionOpenOnlineResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefSessionOpenOnline Operation

KsefSessionOpenOnlineRequest

The class is described in the chapter KsefSessionOpenOnlineRequest.

EncryptionInfo

The class is described in the chapter EncryptionInfo.

KsefInvoiceVersion

The class is described in the chapter KsefInvoiceVersion.

KsefSessionOpenOnlineResponse

The response in the case of a correctly created session contains the following attributes:

id : string – The attribute contains the ID of the created session. This must be written to the calling system as it will be used in most other operations.

created : string – The attribute contains the date and time of the session creation in date-time format.

ksefSessionOpenBatch

ksefSessionOpenBatch(invoice : KsefSessionOpenBatchRequest): KsefSessionOpenBatchResponse This method allows you to set up a batch session with the KSeF system, which will allow you to send multiple invoices to KSeF in one batch. The input method requires creating a request consistent with KsefSessionOpenBatchRequest, and on the output it returns an answer consistent with KsefSessionOpenBatchResponseClick on the name of the operation to go to Swagger UI.

Diagram: ksefSessionOpenBatch Operation

KsefSessionOpenBatchRequest

The class represents input attributes for batch session opening operations.

invoiceVersion : KsefInvoiceVersion – One of two possible versions of the schema defined in the enum KsefInvoiceVersionDue date: [1]

encryptionInfo : EncryptionInfo – The type is described in the chapter EncryptionInfoDue date: [1]

offline : boolean – This attribute specifies whether the invoices sent are issued offline24. Required: [1]

batchInfo : BatchInfo – The type is described in the chapter BatchInfoDue date: [1]

BatchInfo

The class represents information describing a batch of invoices being sent.

batchSize : int – Attribute specifying the size of the entire package. Package file size in bytes. Required: [1]. Maximum package size is 5GB. Range: [1 .. 5000000000]

batchHash : string – An attribute containing the hash (hash function) of the entire package, encoded in Base64 format. Required: [1]

batchParts: BatchPartInfo – An array type attribute containing information about specific parts of the package. The type is described in the chapter BatchPartInfo. Required: [1]. Maximum number of parts is 50. Scope: [1 .. 50]. The maximum allowed part size before encryption is 100MB.

BatchPartInfo

A class represents a given part of a package.

ordinal: int – An ordinal attribute indicating the next part number of the package. Required: [1]

partSize: int – An attribute specifying the size of a parcel part. Required: [1]

partHash: string – An attribute containing the hash (hash function) of a given part of the package, encoded in Base64 format. Required: [1]

KsefSessionOpenBatchResponse

The class represents the response returned after a successful batch session setup. 

PartUploadInfo

ordinal : int – Ordering attribute, specifies part of the package file.

method : string – HTTP method to use when sending part of the package file.

url : string – Address to which part of the package file should be sent.

headers : PartUploadHeader – The array type attribute, which was described in the chapter PartUploadHeader.

PartUploadHeader

The class represents the header to be used when sending part of the package file.

name : string – Header name

value : string – Header value

ksefInvoiceGenerate

ksefInvoiceGenerate(ksefInvoiceGenerateRequest : KsefInvoiceGenerateRequest): KsefInvoiceGenerateResponse A method that allows you to generate an XML structured invoice that is compliant with the current (up-to-date) version of the schema used in KSeF. Click on the operation name to go to Swagger UI.

Attention! A detailed description of the input classes and attributes for the operation is available on a dedicated subpage: REST API – generating KSeF 2.0 invoices.

Diagram: ksefInvoiceGenerate operation

KsefInvoiceGenerateRequest

The class represents input attributes describing the KSeF invoice. The class is described in detail in the chapter KsefInvoiceGenerateRequest.

KsefInvoiceGenerateResponse

The class represents the response returned by the operation ksefInvoiceGenerate, which contains a generated KSeF invoice compliant with the KSeF schema. The class is described in detail in the chapter KsefInvoiceGenerateResponse.

ksefInvoiceValidate

ksefInvoiceValidate(ksefInvoice : KsefInvoice): KsefInvoiceValidateResponse The method enables verification of the KSeF invoice for compliance with the scheme. An object must be sent as a parameter for calling the operation TextXmlContent containing the generated KSeF invoice. An external tool or operation can be used to generate an invoice ksefInvoiceGenerate. In response, the operation returns an object KsefInvoiceValidateResponse with information about the schema version in which the invoice was generated and whether it is compatible with this structure. Click on the name of the operation to go to Swagger UI.

Diagram: ksefInvoiceValidate Operation

TextXmlContent

The class is described in the chapter TextXmlContent.

KsefInvoiceValidateResponse

A response containing information about the version of the schema in which the sent KSeF invoice was generated and whether it is compatible with this schema.
invoiceVersion : KsefInvoiceVersion – One of the supported schema versions defined in the enum KsefInvoiceVersion.

valid : boolean – The value True (1) means that the invoice sent for verification complies with the schema, and if inconsistency of the invoice XML file with the schema is detected, the Http code and the object are returned Error with a description of the first detected schema non-compliance error in the attribute details.

canonicalForm : string – This attribute contains the canonical form of the invoice submitted for validation. The value is encoded using Base64.

ksefInvoiceSend

ksefInvoiceSend(invoice : KsefInvoiceSendRequest): KsefInvoiceSendResponse This method allows you to send a single invoice to the KSeF system as part of a set interactive session. Click on the operation name to go to Swagger UI.
Attention! The method can be called any number of times within a set session and thus send more invoices to KSeF.
Attention! To send invoices to KSeF using this method, the operation must be triggered first ksefSessionOpenOnline in order to set up an interactive session. The input method requires the creation of a request consistent with KsefInvoiceSendRequest, and on the output it returns an answer consistent with KsefInvoiceSendResponse. 

Diagram: ksefInvoiceSend Operation

KsefInvoiceSendRequest

The class is described in the chapter KsefInvoiceSendRequest.

KsefInvoiceEncrypted

The class is described in the chapter KsefInvoiceEncrypted.

KsefInvoiceSendResponse

The class represents the response received from KSeF in the event of a successful invoice submission.
Attention! The response informs that the invoice has been successfully sent to KSeF, but to make sure that the invoice has been correctly saved in KSeF, the operation must be called ksefInvoiceStatus, one of the input parameters is technical identifier of the invoice returned as an attribute value id.
created : string – The attribute contains information about the exact date and time of sending the invoice to KSeF
id :string – Attribute contains technical identifier of the invoice sent to KSeF

ksefInvoiceQueryStart

ksefInvoiceQueryStart (KsefInvoiceQueryStartRequest : KsefInvoiceQueryStartRequest): KsefInvoiceQueryStartResponse This method allows you to define and send invoice search criteria to KSeF. Click on the operation name to go to Swagger UI.
Attention! Calling the method requires previously opening an interactive session using the operation ksefSessionOpenOnline. The input method requires sending a request consistent with KsefInvoiceQueryStartRequest. The method returns an object compatible with KsefInvoiceQueryStartResponse, which contains search ID.

Diagram: ksefInvoiceQueryStart operation

KsefInvoiceQueryStartRequest

The class is described in the chapter KsefInvoiceQueryStartRequest.

SubjectType

The enumeration is described in the chapter SubjectType. 

KsefInvoiceQueryStartRange

The class is described in the chapter KsefInvoiceQueryStartRange.

KsefInvoiceQueryStartResponse

The object represents a response from the KSeF system containing search ID, which search was run asynchronously on the KSeF side.
queryId :string – Attribute specifies search ID, which is generated by KSeF.

ksefInvoiceVisualize

ksefInvoiceVisualize(KsefInvoiceVisualizeRequest : KsefInvoiceVisualizeRequest): KsefInvoiceVisualizeContent A method that allows you to generate an XML structured invoice visualization in one of the following formats: HTML and PDF. The input method requires preparation of the request according to KsefInvoiceVisualizeRequest, and returns an object of type in response TextHtmlContent for HTML visualization either ApplicationPdfContent for visualization in a PDF file. Click on the name of the operation to go to Swagger UI.

Diagram: ksefInvoiceVisualize Operation

KsefInvoiceVisualizeRequest

The class is described in the chapter KsefInvoiceVisualizeRequest.

OutputFormat

The enumeration is described in the chapter OutputFormat.

OutputLanguage

The enumeration is described in the chapter OutputLanguage.

Content

The class is described in the chapter Content.

ApplicationPdfContent

The class represents the generated visualization of the KSeF invoice in the form of a PDF file.
description : string – = PDF visualization

TextHtmlContent

The class represents the generated visualization of the KSeF invoice in the form of an HTML file.
description : string – = HTML visualization

Parameters

The chapter contains a summary of all parameters by type:

• path – parameter passed in the URL path
• requestBody – parameter passed in the request body

 Diagram: Parameters

Path

Parameters for calling the operation included in the path.

SessionId

The class represents the session ID generated by the KSEF system
sessionId : string – Unique session identifier

InvoiceId

The class represents the technical identifier of the invoice, which is returned as an attribute id classes KsefInvoiceSendResponse, and can then be used to check the invoice processing status by triggering an operation ksefInvoiceStatus.
invoiceId : string – Invoice ID (technical)

InvoiceKsefNumber

KSeF invoice number generated by KSeF.
invoiceKsefNumber : string – Generated by KSeF Invoice ID. Generating this identifier confirms saving the sent invoice in KSeF.

QueryId

The class contains a search ID that is generated by KSeF.
queryId : string – Search process ID

QueryPartNumber

The class represents the search package number.
partNumber : string – Identifier of the fragment (package) of the search result

RequestBody

Parameters of type requestBody.

KsefInvoiceEncrypted

The object represents the transmitted invoice in encrypted form.
encryptedInvoice : string – Attribute containing the invoice XML file in encrypted form, which is sent to KSeF. The invoice XML file is encrypted with the AES256 algorithm using an initialization vector (attribute initVector classes KsefSessionOpenOnlineRequest) and the symmetric key generated when creating the session.
invoiceHash : string – The attribute contains the hash value from the SHA256 function from the original (unencrypted) XML form of the invoice, which is sent to KSeF.
invoiceSize : int – Attribute containing the calculated size of the invoice (size in bytes of the original, unencrypted XML form of the invoice), which is sent to KSeF.

KsefInvoiceQueryStartRange

The class represents the period for which invoices are to be searched. Dates from and to, specify the date PermanentStorage, i.e. the date of permanent recording of the invoice in the KSeF system repository. For incremental invoice downloading, it is necessary to use the date type PermanentStorage, which ensures data reliability. It marks the moment of permanent record materialization, is resistant to asynchronous delays in the data reception process, and allows for the safe definition of incremental windows.
from : string – Date from which invoices will be searched.
to : string – Date up to which invoices will be searched.

KsefInvoiceQueryStartRequest

The class represents a request that allows you to define search parameters.

range : KsefInvoiceQueryStartRange – Select the period for which invoices should be searched. Required: [1].
encryptionInfo : EncryptionInfo – The type is described in the chapter EncryptionInfo. Due date: [1].
subjectType : SubjectType – Specify what type of invoice we are searching for. Required: [1]:

• sales (Subject1),
• cost (Subject2),
• third party (Subject3),
• Subject Authorized

SubjectType

The enumeration specifies the possible types of the entity
Subject1 : – The attribute denotes the entity issuing the invoice
Subject2 : – The attribute denotes the entity receiving the invoice
Subject3 : – The attribute denotes a third party
SubjectAuthorized : – The attribute denotes the authorized entity

KsefInvoiceSendRequest

The class represents a request to send an invoice in two modes: encryption or non-encryption of invoices
encrypted : KsefInvoiceEncrypted – The attribute specifies the variant (choice) used to send an encrypted invoice in a session created with encryption, i.e. the set parameters: encryptedKey and initVector when creating a session (KsefSessionOpenOnlineRequest). Due date: [1]

sessionId : string – Session ID obtained when establishing an interactive session: ksefSessionOpenOnlineDue date: [1]

KsefSessionOpenOnlineRequest

The class represents a request to create an interactive session.

invoiceVersion : KsefInvoiceVersion – Indicate the schema version in which KSeF invoices will be sent within the established session. Required: [1]

encryptionInfo : EncryptionInfo – The type is described in the chapter EncryptionInfoDue date: [1]

EncryptionInfo

encryptedKey : string – If encryption of transmitted data (invoices) is to be used as part of an interactive session, the attribute should include a symmetric encryption key (AES256) generated before opening a new session and encrypted with the KSeF platform RSA public key downloaded using the operation ksefPublicKeyDue date: [1]

initVector : string – This attribute describes the so-called initialization vector. The acceptable AES symmetric key encryption algorithm is AES/CBC/PKCS5Padding (PKCS#7). The acceptable symmetric key is AES with a length of 256 bits supported by a random initialization vector of 16 bytes. Requirement: [1]

KsefInvoiceVisualizeRequest

The class allows you to define parameters related to the visualization of a structured invoice (KSeF invoice)
templateName: string – The attribute defines the name of the template to be used to visualize the invoice.

offline: boolean – The attribute specifies whether a QR code is to be attached to the visualization. The option may apply to invoices issued to foreign contractors who will not have access to KSeF anyway, and the method of transmitting (delivering) the invoice will depend on the issuing entity.

invoiceKsefNumber: string – Attribute contains unique KSeF number of the invoice assigned by the National e-Invoice System when the invoice is successfully sent to KSeF. 

invoiceData: string – The attribute transmits the XML file of the KSeF invoice for which the visualization is to be performed.

outputFormat: OutputFormat – The attribute can take one of two possible values defined in the enumeration OutputFormat.

outputLanguage : OutputLanguage – The attribute can take one of the three possible values defined in the enumeration OutputLanguage.

 

Enumerations

The chapter contains a list of all enumerations that can be used in the interface.

Diagram: Enumerations

InvoiceStatus

An enumeration specifying the possible status of the submitted invoice returned by KsefInvoiceStatusResponse
processing : string – The status returned from KSeF means that the sent invoice is still being processed. Please wait a while and check the invoice status again.
accepted : string – The status returned from KSeF means that the sent invoice has been received correctly and a unique KSeF number has been assigned to it (InvoiceKsefNumber).
rejected : string – The status returned from KSeF means that the sent invoice was rejected by KSeF. In the details of the error message (Error), you should check what was the reason for rejecting the invoice.

Algorithm

Cryptographic key algorithms supported by KSeF
RSA : – Supported cryptographic key algorithm

KsefInvoiceVersion

Schema version for KSeF invoices  
v2 : – Second version of the schema
v3 : – Third version of the schema (valid).

OutputFormat

The enumeration defines the format in which the invoice visualization is to be generated
html : string – The value specifies that the invoice visualization should be returned in HTML format.
pdf : string – The value specifies that the invoice visualization should be returned in PDF format.

OutputLanguage

The enumeration defines the language in which the invoice visualization is to be generated
pl : string – The value specifies that the invoice visualization should be in Polish.
en : string – The value specifies that the invoice visualization should be in English.
pl_en : string – The value specifies that the invoice visualization should be in Polish and English.

SessionStatus

The enumeration defines what statuses an interactive session can have
active : string – The attribute indicates an active session
closed : string – Attribute indicates an ended session.

SubjectType

The enumeration specifies the possible types of the entity
subject1 : – The attribute denotes the entity issuing the invoice
subject2 : – The attribute denotes the entity receiving the invoice
subject3 : – The attribute denotes a third party
subjectAuthorized : – The attribute denotes the authorized entity

Content replies

The chapter identifies and groups classes related to specific content that may occur when exchanging information with KSeF.

Diagram: Content Responses

Content

A parent class that describes the content from which other classes inherit
description : string – Content description for a given class
format : binary – Content format – always BINARY
type : string – Content type – always STRING

ApplicationZipContent

The class represents a ZIP archive with KSeF invoices in XML form
description : string – ZIP archive with XML invoices

ApplicationOctetStreamContent

The class represents data in one of two possible forms: a) an encrypted single KSeF invoice (XML), b) an encrypted ZIP archive with multiple KSeF invoices (XML)
description : string – Encrypted single XML invoice or encrypted ZIP archive with XML invoices

TextXmlContent

The class represents a KSeF Invoice or Official Confirmation of Receipt (UPO) in XML form
description : string – Invoice or UPO

ApplicationPdfContent

The class represents the generated visualization of the KSeF invoice in the form of a PDF file
description : string – = PDF visualization

TextHtmlContent

The class represents the generated visualization of the KSeF invoice in the form of an HTML file
description : string – = HTML visualization

Error messages

The chapter contains a description of the class responsible for handling error messages.

Error

The class represents the structure of returned errors
code : string – Unique error code
description : string – Description of the error
details : string – Detailed description of the error. Attribute used in particular when generating an invoice XML file (ksefInvoiceGenerate) in case of a schema incompatibility error. Information about the first error encountered is always returned. (Requirement: [0..1]). Errors occurring in the area of generating invoices are described in detail in the chapter Error messages – Invoice.

Authorization and encryption

A set of errors related to the area of authorization and encryption.

Diagram: Error Messages - Authorization and Encryption

AES_IV_LENGTH – Invalid initialization vector length

code = 1002
description = The initialization vector has an invalid length

AES_KEY_LENGTH – Incorrect length of the symmetric key used for data encryption

code = 1003
description = The symmetric key has an invalid length

AUTH_CHALLENGE – Error getting authorization challenge

code = 1001
description = Failed to download the authorization challenge from the KSeF system

B64_DECODE – Incorrectly encoded value using base64

code = 1005
description = Invalid base64 encoding of values

KSEF_PUBLIC_KEY – Error retrieving KSeF public key

code = 1004
description = Failed to retrieve the KSeF public key

Session

A set of errors related to managing an interactive session.

Diagram: Error Messages - Session

SESSION_ACCESS – Session access error

code = 1110
description = The user does not have access to the specified session

SESSION_CLOSE – Error when trying to close an interactive session

code = 1106
description = Failed to close the session in the KSeF system

SESSION_INIT – Error initiating an interactive session with the KSeF system

code = 1102
description = Failed to initialize a new session in the KSeF system

SESSION_NO_UPO – The UPO object has not been generated yet

code = 1111
description = No UPO

SESSION_OPEN – Error creating a new interactive session with KSeF

code = 1103
description = Failed to create a new session in the KSeF system

SESSION_REF_NUM – Invalid KSeF interactive session ID

code = 1104
description = Missing new KSeF session ID

SESSION_SAVE – Session update error

code = 1108
description = Failed to update KSeF session data

SESSION_STATUS – Error getting the status of an interactive session in KSeF

code = 1105
description = Failed to retrieve the current session status from the KSeF system

SESSION_TOKEN – Error preparing authorization challenge

code = 1101
description = Failed to prepare a response to the authorization challenge for the KSeF system

SESSION_UNKNOWN – Invalid session ID

code = 1109
description = Unknown KSeF session ID

SESSION_UPO – Error downloading UPO

code = 1107
description = Failed to download UPO from the KSeF system

Invoice

A set of errors related to generating, sending, downloading and visualizing invoices.

Diagram: Error Messages - Invoice

INVOICE_FORMAT – Incorrect format of the sent invoice

code = 1203
description = The invoice has an incorrect format

INVOICE_INPUT – Required metadata describing the invoice is missing

code = 1208
description = Missing required invoice metadata

INVOICE_SAVE – An error occurred while updating the invoice data

code = 1206
description = Failed to update invoice details

INVOICE_SEND – An error occurred while sending the invoice to KSeF

code = 1204
description = Failed to send the invoice to the KSeF system

INVOICE_SIZE – Invoice size too large

code = 1202
description = The invoice is of an unacceptable size

INVOICE_STATUS – An error occurred while retrieving the invoice status

code = 1205
description = Failed to download the current invoice status from the KSeF system

INVOICE_UNKNOWN – Invalid invoice ID

code = 1207
description = Unknown invoice ID

INVOICE_VERSION – Incorrect version of the invoice schema

code = 1201
description = Incorrect invoice format version

INVOICE_VISUALIZE – An error occurred while generating the invoice visualization

code = 1209
description = Failed to generate invoice visualization

Search

A collection of errors related to entering invoices in KSeF

Diagram: Error Messages - Search

QUERY_INVOICE_INIT – An error occurred while initiating the invoice search process

code = 1302
description = Failed to start the invoice search process

QUERY_INVOICE_PARAMS – Invalid search criteria

code = 1301
description = Incorrect or incomplete invoice search criteria

QUERY_INVOICE_RESULT – An error occurred while retrieving invoice search results

code = 1304
description = Failed to retrieve invoice search result

QUERY_INVOICE_STATUS – An error occurred while checking the invoice search status

code = 1303
description = Failed to retrieve the status of the invoice search process