KSeF REST API

Documentation version: 1.1 (changelog)

Version date: 2024-04-19

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

Spis treści

Components

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

Calling system
REST API KSeF
KSeF system

KSeF REST API - komponenty Figure: Components

Calling system

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

National e-Invoice System (KSeF)

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

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 the handling of KSeF invoices: • Generating a KSeF invoice (structured) in accordance with the FA_v2 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 invoice). Individual steps of each process contain links to operations that must be invoked in order to implement a given step.

Generating a KSeF invoice (structured) in accordance with the FA_v2 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. Any call to an operation exposed on an interface REST API KSeF may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF, are described in detail in the chapter Error messages.

KSeF REST API - proces generowania faktury KSeF Figure: Generating a KSeF invoice

Description of the process:

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

2. Then REST API KSeF 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. Any call to an operation exposed on an interface REST API KSeF may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF, but also KSeF system are described in detail in the chapter Error messages.

KSeF REST API - proces wysyłki faktur do KSeF Figure: Sending invoices in an interactive session to KSeF and downloading UPO

Description of the process:

1. For each generated pose 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 ksefSessionOpen 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 (InvoiceStatus) has value accepted, this means that the invoice has been successfully saved in the KSeF system and we can save the invoice number generated by KSeF (ksefReferenceNumber) and acquisition date (acquisitionTimestamp), i.e. the exact date and time of saving KSeF system.

9. After downloading all KSeF numbers of outstanding invoices (ksefReferenceNumber) 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 may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF, but also KSeF system are described in detail in the chapter Error messages.

KSeF REST API - proces wyszukania i pobrania faktur z KSeF Figure: Searching and downloading invoices from KSeF (cost or sales)

Description of the process:

1. First, invoke the operation ksefSessionOpen to create an interactive session in which other operations will be performed. 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.

2. After correctly setting up the 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 subsequent operations.

3. Then prepare your search criteria appropriately (KsefInvoiceQueryStartRequest) and initiate the asynchronous fact lookup process by calling the operation ksefInvoiceQueryStart.

4. After successfully sending your inquiry, 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.

5. To check whether any invoices meet the defined search criteria and have been found, 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).

6. In order to download invoices that meet the defined search criteria, for each returned invoice package (QueryPartNumber) trigger the operation ksefInvoiceQueryResult.

7. After downloading all found invoices (all packages), close the session by triggering the operation ksefSessionClose.

8. Optional step. If the session was configured to encrypt transmitted data when it was created, all downloaded packages must be decrypted.

9. Then unpack each downloaded package (ZIP archive) and save it on the website Calling system.

10. In order to generate visualization for the downloaded invoice XML file from KSeF, call the operation for each invoice ksefInvoiceVisualize.

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

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 may cause an error to be generated. Possible errors resulting from the processing of the request by REST API KSeF, but also KSeF system are described in detail in the chapter Error messages.

KSeF REST API - pobranie pojedynczej faktury z KSeF Figure: Downloading a single invoice from KSeF (cost or sales)

Description of the process:

1. In the first step, call the operation ksefSessionOpen to create an interactive session in which other operations will be performed. 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. Optional step. We 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).

4. If in response to a method call ksefSessionStatus, we have received information about the active session status, we can start downloading the invoice by triggering the operation ksefInvoiceGet.

5. The downloaded invoice as an XML file should be saved on the website Calling system.

6. If we still have some KSeF invoice numbers for which we want to download invoices from KSeF, repeat the steps described in points 4-5. Otherwise, close the session by calling the operation ksefSessionClose.

7. Optional step. Depending on business needs, the last step of the process may be to generate an invoice visualization in PDF or HTML form. To do this, you need to invoke an operation ksefInvoiceVisualize and select the appropriate visualization parameters in the request.

Operations

The chapter contains a description of the methods provided within the KSeF REST API

KSeF REST API - interfejs Figure: KSeF API REST interface

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 (KsefSessionOpenRequest). The method does not require any parameter on the input, and on the output it returns a response consistent with KsefPublicKeyResponse.

KSeF REST API - pobranie klucza publicznego KSeF Figure: ksefPublicKey

Algorithm

Cryptographic key algorithms supported by KSeF RSA : – Supported cryptographic key 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 – 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 KsefSessionStatusResponse.

KSeF REST API - status sesji Figure: ksefSessionStatus

SessionId

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

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.

KsefSessionStatusResponse

A response containing the status of a given interactive session status : SessionStatus – One of two possible interactive session statuses defined in the enum SessionStatus

ksefSessionClose

ksefSessionClose(sessionId : SessionId): KsefSessionCloseResponse The method allows you to close a session connected to 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 KsefSessionCloseResponse.

KSeF REST API - zamknięcie sesji Figure: ksefSessionClose

SessionId

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

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 UPO.

KSeF REST API - pobranie upo Figure: ksefSessionUpo

SessionId

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

TextXmlContent

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

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 KsefInvoiceStatusResponse.

KSeF REST API - sprawdzenie statusu odebrania faktury przez KSeF Figure: ksefInvoiceStatus

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)

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.

KsefInvoiceStatusResponse

The class represents the response of the KSeF system in the context of the processing status of the invoice sent to KSeF. acquisitionTimestamp : string – Optional attribute, informs about the exact date and time of receipt of the invoice by KSeF. The attribute contains a value only if the status of the sent invoice has a value accepted. (Requirement: [0..1]) invoiceNumber : string – Optional attribute, returns information about the invoice number assigned by the entity issuing the invoice. The attribute contains a value only if the status of the sent invoice has a value accepted. (Requirement: [0..1]) ksefReferenceNumber : string – Optional attribute, returns information about the KSeF invoice number, which is assigned by KSeF and is unique within KSeF. An attribute refers to the same thing as a parameter InvoiceKsefNumber. The attribute contains a value only if the status of the sent invoice has a value accepted. (Requirement: [0..1]) status : InvoiceStatus – The attribute returns the current status of the submitted invoice. The value is consistent with the items in the enumeration InvoiceStatus.

ksefInvoiceGet

ksefInvoiceGet(sessionId : SessionId, invoiceKsefNumber : InvoiceKsefNumber): KsefInvoiceGetContent The method allows you to download a single invoice from KSeF, specifying: KSeF number of the invoice. Attention! Calling the method requires previously opening an interactive session using the operation ksefSessionOpen. The input method requires sending two parameters in the calling path (URL): InvoiceKsefNumber and SessionId, 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.

KSeF REST API - pobranie faktury z KseF Figure: ksefInvoiceGet

SessionId

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

InvoiceKsefNumber

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

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

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

ksefInvoiceQueryStatus

ksefInvoiceQueryStatus(sessionId : SessionId, queryId : QueryId): KsefInvoiceQueryStatusResponse The method allows you to obtain the search status of invoices in KSeF. Attention! Calling the method requires previously opening an interactive session using the operation ksefSessionOpen and calling the operation ksefInvoiceQueryStart in which the search ID is returned (QueryId) The input method requires sending two parameters in the calling path (URL): QueryId and SessionId, and on the output it returns an answer consistent with KsefInvoiceQueryStatusResponse.

KSeF REST API - sprawdzenie statusu wyszukiwania faktur Figure: ksefInvoiceQueryStatus

SessionId

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

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 items[] : 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(sessionId : SessionId, 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 the operation: ksefSessionOpen, which will return the session ID (SessionId) and ksefInvoiceQueryStart, which returns the search ID (QueryId). Attention! If session (ksefSessionOpen) was opened with encryption, the downloaded invoice packages in ZIP form (identified with QueryPartNumber), must be decrypted before unpacking. Each package must be decrypted using the symmetric AES256 key (encryptedKey), which was generated when creating the session (ksefSessionOpen). The input method requires sending three parameters in the calling path (URL): SessionId, QueryId and QueryPartNumber, and on the output it returns an answer consistent with ApplicationZipContent.

KSeF REST API - pobranie wyników wyszukiwania faktur KSeF Figure: ksefInvoiceQueryResult

SessionId

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

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

POST

HTTP POST methods.

ksefSessionOpen

ksefSessionOpen(invoice : KsefSessionOpenRequest): KsefSessionOpenResponse 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 KsefSessionOpenRequest, and on the output it returns an answer consistent with KsefSessionOpenResponse.

KSeF REST API - otwarcie sesji Figure: ksefSessionOpen

KsefSessionOpenRequest

The class represents a request to create an interactive session 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 ksefPublicKey. (Requirement: [0..1]) initVector : string – The 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: [0..1]) invoiceVersion : KsefInvoiceVersion – Indication of the schema version in which KSeF invoices will be sent within the established session.

KsefInvoiceVersion

Schema version for KSeF invoices v1 : – First version of the schema v2 : – Second version of the scheme (valid)

KsefSessionOpenResponse

Response in case of a correctly created session created : string – The attribute contains the date and time of the session creation in date-time format. 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.

ksefInvoiceGenerate

ksefInvoiceGenerate(ksefInvoiceGenerateRequest : KsefInvoiceGenerateRequest): KsefInvoiceGenerateResponse A method enabling the generation of a structured XML invoice compatible with the current (current) version of the schema used in KSeF.

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

KSeF REST API - generowanie faktury Figure: ksefInvoiceGenerate

KsefInvoiceGenerateRequest

The class represents input attributes describing the KSeF invoice

KsefInvoiceGenerateResponse

The class represents the response returned by the operation ksefInvoiceGenerate, which contains a generated KSeF invoice consistent with the scheme applicable in KSeF.

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 on what version of the schema the invoice is generated in and whether it is consistent with this structure.

KSeF REST API - walidacja faktury Figure: ksefInvoiceValidate

KsefInvoiceVersion

Schema version for KSeF invoices v1 : – First version of the schema v2 : – Second version of the scheme (valid)

TextXmlContent

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

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 two possible versions of the schema 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.

ksefInvoiceSend

ksefInvoiceSend(invoice : KsefInvoiceSendRequest): KsefInvoiceSendResponse The method allows you to send one invoice to the KSeF system as part of a set interactive session. 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 ksefSessionOpen 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.

KSeF REST API - wysłanie faktury do KSeF Figure: ksefInvoiceSend

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) that is used to send an encrypted invoice in a session created with encryption, i.e. the set parameters: encryptedKey and initVector when creating a session (KsefSessionOpenRequest). (Requirement: [0..1]) plain : KsefInvoicePlain – The attribute specifies the variant (choice) that is used to send unencrypted invoice XML in a session created with no encryption. (Requirement: [0..1]) sessionId : string – Session ID obtained when establishing an interactive session: ksefSessionOpen.

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

KsefInvoicePlain

The object represents the transmitted invoice in a public (unencrypted) form. invoice : string – Attribute containing the invoice XML file in unencrypted byte form with UTF-8 encoding, which is sent to KSeF.

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 The method allows you to define and send invoice search criteria to KSeF. Attention! Calling the method requires previously opening an interactive session using the operation ksefSessionOpen. The input method requires sending a request consistent with KsefInvoiceQueryStartRequest. The method returns an object compatible with KsefInvoiceQueryStartResponse, which contains search ID.

KSeF REST API - rozpoczęcie procesu wyszukania faktur w KSeF Figure: ksefInvoiceQueryStart

KsefInvoiceQueryStartRequest

The class represents a request that allows you to define search parameters range : KsefInvoiceQueryStartRange – Selecting the period for which invoices are to be searched (Requirement: [0..1]) sessionId : string – Active session ID subjectType : SubjectType – Specifying what type of invoice we are looking for:

sales (subject1),
cost (subject2),
third party (subject3),
authorized entity (subjectAuthorized)

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

KsefInvoiceQueryStartRange

The class represents the period for which invoices are to be searched from : string – Date from which invoices will be searched. this : string – Date up to which invoices will be searched.

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 PDF file.

KSeF REST API - wizualizacja faktury KSeF Figure: ksefInvoiceVisualize

KsefInvoiceVisualizeRequest

The class allows you to define parameters related to the visualization of a structured invoice (KSeF invoice) includeLogo : boolean – The attribute specifies whether a logo should be included in the visualization. includeQrCode : 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. invoiceData : string – The attribute transmits the XML file of the KSeF invoice for which the visualization is to be performed. 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. outputFormat : OutputFormat – The attribute can take one of two possible values defined in the enumeration OutputFormat:

html
pdf

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

pl
en
pl_en

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.

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

KSeF REST API - parametry Figure: 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

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

KsefInvoicePlain

The object represents the transmitted invoice in a transparent (unencrypted) form. invoice : string – Attribute containing the invoice XML file in unencrypted byte form with UTF-8 encoding, which is sent to KSeF.

KsefInvoiceQueryStartRange

The class represents the period for which invoices are to be searched. from : string – Date from which invoices will be searched. this : string – Date up to which invoices will be searched.

KsefInvoiceQueryStartRequest

The class represents a request that allows you to define search parameters range : KsefInvoiceQueryStartRange – Selecting the period for which invoices are to be searched (Requisite: [0..1]) sessionId : string – Active session ID subjectType : SubjectType – Specifying what type of invoice we are looking for:

sales (subject1),
cost (subject2),
third party (subject3),
authorized entity (subjectAuthorized)

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) that is used to send an encrypted invoice in a session created with encryption, i.e. the set parameters: encryptedKey and initVector when creating a session (KsefSessionOpenRequest). (Requirement: [0..1]) plain : KsefInvoicePlain – The attribute specifies the variant (choice) that is used to send unencrypted invoice XML in a session created with no encryption. (Requirement: [0..1]) sessionId : string – Session ID obtained when establishing an interactive session: ksefSessionOpen.

KsefSessionOpenRequest

KsefInvoiceVisualizeRequest

The class allows you to define parameters related to the visualization of a structured invoice (KSeF invoice). includeLogo : boolean – The attribute specifies whether a logo should be included in the visualization. includeQrCode : 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. invoiceData : string – The attribute transmits the XML file of the KSeF invoice for which the visualization is to be performed. 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. outputFormat : OutputFormat – The attribute can take one of two possible values defined in the enumeration OutputFormat:

html
pdf

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

pl
en
pl_en

Enumerations

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

KSeF REST API - Enumeracje Figure: 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.