REST API KSeF

Contents

Components

For the purposes of this documentation, 3 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

Drawing: Components

Calling system

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

National e-Invoice System (KSeF)

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

REST interface providing operations (methods) enabling comprehensive implementation business processes related to the handling 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) in accordance with the FA_v2 schema • Sending invoices in an interactive session to KSeF and downloading UPO • Searching for 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 the operations that must be called in order to complete a given step.

Generating a KSeF (structured) invoice compliant 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 to be taken to generate a structured KSeF invoice using the interface REST API KseF. Each call to an operation provided in the interface REST API KSeF may generate an error. Possible errors that may occur due to the handling 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 flow:

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 XML invoice file compliant with the current (up-to-date) 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 the KSeF invoice (or invoices) to National e-Invoice System as part of the created interactive session and downloading the Official Confirmation of Receipt from KSeF confirming the receipt of the sent invoices by KSeF system. The process describes a positive scenario and the steps to be taken to send a structured invoice to KSeF using the interface REST API KSeF. Each call to an operation provided in the interface REST API KSeF may generate an error. Possible errors that may occur due to the handling of the request by REST API KSeF, but also KSeF System were 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 flow:

1. For each generated pose REST API KSeF invoices we recommend calling the operation ksefInvoiceValidate to check the correctness of the invoice with the schema.
Attention! One of the reasons for rejection of an invoice by KSeF may be non-compliance with the applicable XSD schema.

2. After verifying the correctness of the generated invoices, the operation should be triggered ksefSessionOpen in order to create an interactive session within which the sending will be performed. Details describing the methods and types of sessions created, as well as the possibilities associated with them, are described in the chapter describing the given method.

3. After successfully establishing an interactive session, KSeF System returns session id (SessionId), which should be written on the side Calling system, because this identifier will be used to call other operations.

4. Next, before we start sending invoices, we need to check whether the session we created earlier is still active. This step is especially important if a few minutes have passed since the session was created or the quality of the network connection is poor. In order to verify the activity of the session, we need to call the operation ksefSessionStatus, and as a call parameter, specify the interactive session identifier (SessionId).

5. If in response to the method call ksefSessionStatus, we have received information about the active session status, we can proceed to iterative sending of all invoices by calling the operation as many times as necessary ksefInvoiceSend, how many invoices do we intend to send to KSeF. In response KSeF System should return in attribute id, technical invoice identifier (InvoiceId).

6. Returned technical invoice identifier (InvoiceId) should be written on the side 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 to KSeF [5] and saving their technical identifiers [6], you should check the receipt status of each of the sent invoices. To do this, you should call the 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, it means that the invoice has been correctly 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 recording in KSeF System.

9. After downloading all KSeF numbers of issued invoices (ksefReferenceNumber) you need to correctly end the interactive session by calling the operation ksefSessionClose with parameter SessionId (session ID returned when creating it in step 3).

10. Only after closing the interactive session is it possible to invoke the operation ksefSessionUpo, with parameter SessionId (session identifier returned during its creation in step 3) returning the Official Receipt Confirmation (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 performed to search and download found invoices that meet the defined search criteria. Within a single call, you can search either your cost invoices or your sales invoices. Each call of the operation made available in the interface REST API KSeF may generate an error. Possible errors that may occur due to the handling of the request by REST API KSeF, but also KSeF System were 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 flow:

1. First of all, you need to call the operation ksefSessionOpen in order to create an interactive session within which the remaining 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 the given method.

2. After the interactive session has been successfully set up, KSeF System returns session id (SessionId), which should be written on the side Calling system, because this identifier will be used to trigger subsequent operations.

3. Then you need to prepare your search criteria accordingly (KsefInvoiceQueryStartRequest) and initiate an asynchronous fact retrieval process by calling the operation ksefInvoiceQueryStart.

4. After successfully sending the query, KSeF System returns search id (QueryId), which should be written on the side Calling system, because this identifier will be used to trigger the operation of checking the search status (whether invoices were found) and to download found invoice batches.

5. To check if 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 packages with invoices found. Each package is identified by a package identifier (QueryPartNumber).

6. To download invoices that meet the defined search criteria, for each returned batch of invoices (QueryPartNumber) call the operation ksefInvoiceQueryResult.

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

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

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

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

11. 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 a positive scenario and the steps to be taken to download a single invoice for which the KSeF invoice number. Each call to an operation provided in the interface REST API KSeF may generate an error. Possible errors that may occur due to the handling of the request by REST API KSeF, but also KSeF System were 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 flow:

1. In the first step, you need to call the operation ksefSessionOpen in order to create an interactive session within which the remaining 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 the given method.

3. Optional step. We check if the session we created earlier is still active. This step is especially important if a few minutes have passed since the session was created or the quality of the network connection is poor. In order to verify the activity of the session, the operation should be called ksefSessionStatus, and as a call parameter, specify the interactive session identifier (SessionId).

4. If in response to the method call ksefSessionStatus, we have received information about the active session status, we can proceed to download the invoice by calling the operation ksefInvoiceGet.

5. The downloaded invoice in the form of an XML file should be saved on the page Calling system.

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

7. Optional step. Depending on your business needs, the last step of the process may be to generate a visualization of the invoice in PDF or HTML format. To do this, you need to call the operation ksefInvoiceVisualize and select the appropriate visualization parameters if requested.

Operations

The chapter contains a description of the methods provided by the KSeF REST API interface. KSeF REST API - interfejs

Figure: KSeF API REST Interface

GET

HTTP GET type 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 sent 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 at the input, and returns a response in accordance with the output. KsefPublicKeyResponse. KSeF REST API - pobranie klucza publicznego KSeF

Image: ksefPublicKey

Algorithm

Supported Cryptographic Key Algorithms 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 – Public key in the form of 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 key should be generated before creating a session with encryption, and then XML invoices sent to KSeF should be encrypted with this symmetric key.

ksefSessionStatus

ksefSessionStatus(sessionId : SessionId): KsefSessionStatusResponse The method allows you to retrieve the current session status. In the call path (URL) it takes a parameter SessionId. In response, it returns KsefSessionStatusResponse. KSeF REST API - status sesji

Figure: ksefSessionStatus

SessionId

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

SessionStatus

Enumeration defines what statuses an interactive session can have active : string – The attribute indicates an active session closed : string – The attribute indicates a 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 This method allows you to close a session established with KSeF. Attention! Correct closing of the interactive session is necessary to download UPO, i.e. the object confirming invoices received by KSeF. In the call path (URL) it takes the parameter SessionId. In response, it returns KsefSessionCloseResponse. KSeF REST API - zamknięcie sesji

Drawing: ksefSessionClose

SessionId

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

KsefSessionCloseResponse

A response containing information on whether the interactive session was successfully completed result : boolean – A value of True (1) indicates that the session was terminated successfully, while a value of False (0) indicates that the session could not be terminated successfully.

ksefSessionUpo

ksefSessionUpo(sessionId : SessionId): TextXmlContent The method enables downloading the Official Confirmation of Receipt (UPO) for all invoices that were sent within a given interactive session compared with KSeF. Attention! Before calling the ksefSessionUpo operation, you must first close the interactive session correctly using the operation ksefSessionClose. UPO can only be downloaded for a session in which at least one invoice was issued correctly. In the call path (URL) it takes the parameter SessionIdIn response, the operation returns an object TextXmlContent containing UPO. KSeF REST API - pobranie upo

Drawing: ksefSessionUpo

SessionId

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

TextXmlContent

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

ksefInvoiceStatus

ksefInvoiceStatus(invoiceId : InvoiceId): KsefInvoiceStatusResponse The method allows you to check the processing status of an invoice sent to KSeF. Attention!The method checks the processing status of an invoice sent to KSeF using the operation ksefInvoiceSend. The method requires a parameter to be sent in the call path (URL) on the input InvoiceId, and the output returns a response 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 then it can be used to check the invoice processing status by calling the operation ksefInvoiceStatus. invoiceId : string – Invoice ID (technical)

InvoiceStatus

Enumeration defining the possible statuses of the sent invoice returned by KsefInvoiceStatusResponse. processing : string – The status returned from KSeF means that the sent invoice is still being processed. You should wait a moment 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 error message details (Error), you should check what was the reason for rejection of the invoice.

KsefInvoiceStatusResponse

The class represents the response of the KSeF system in the context of the processing status of an 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 the value accepted. (Required: [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. (Required: [0..1]) ksefReferenceNumber : string – Optional attribute, returns information about the KSeF invoice number, which is assigned by KSeF and is unique within KSeF. The attribute refers to the same as the parameter InvoiceKsefNumber. The attribute contains a value only if the status of the sent invoice has a value accepted. (Required: [0..1]) status : InvoiceStatus – Attribute returns the current status of the sent invoice. Value 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 by specifying KSeF invoice number. Attention! Calling the method requires previously opening an interactive session using the operation ksefSessionOpen. The method requires two parameters to be sent in the call path (URL): InvoiceKsefNumber and SessionId, and the output returns a response consistent with TextXmlContent if the downloaded invoice 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 a session identifier generated by the KSEF system. sessionId : string – Unique session identifier

InvoiceKsefNumber

KSeF invoice number generated by KSeF. invoiceKsefNumber : string – Invoice ID generated by KSeF. Generation of this ID confirms saving the sent invoice in KSeF.

Content

A parent class describing the content from which other classes inherit. description : string – Description of the content 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 an Official Receipt Confirmation (UPO) in XML format description : string – = Invoice or UPO

ksefInvoiceQueryStatus

ksefInvoiceQueryStatus(sessionId : SessionId, queryId : QueryId): KsefInvoiceQueryStatusResponse The method allows you to obtain the invoice search status in KSeF. Attention! Calling the method requires previously opening an interactive session using the operation ksefSessionOpen and call operations ksefInvoiceQueryStart in response the search identifier is returned (QueryId) The input method requires sending two parameters in the call path (URL): QueryId and SessionId, and the output returns a response consistent with KsefInvoiceQueryStatusResponse. KSeF REST API - sprawdzenie statusu wyszukiwania faktur

Figure: ksefInvoiceQueryStatus

SessionId

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

QueryId

The class contains the search identifier that is generated by KSeF queryId : string – Search process identifier

KsefInvoiceQueryStatusResponse

The object represents the result of searching for invoices in KSeF items[] : string – The attribute contains an array of package identifiers (each package is a ZIP file) of found invoices (QueryPartNumber) that matched the search criteria defined in the class KsefInvoiceQueryStartRequest.

ksefInvoiceQueryResult

ksefInvoiceQueryResult(sessionId : SessionId, queryId : QueryId, queryPartNumber : QueryPartNumber): KsefInvoiceQueryResultZipContent This method allows you to download all invoices found in KSeF. Attention! Calling a method requires a prior call to the operation: ksefSessionOpenwhich will return the session id (SessionId) and ksefInvoiceQueryStart, which returns the search identifier (QueryId). Attention! If session (ksefSessionOpen) was opened with encryption, then the downloaded invoice packages in ZIP format (identified with QueryPartNumber), must be decrypted before unpacking. Each package must be decrypted using the symmetric AES256 key (encryptedKey), which was generated when the session was created (ksefSessionOpen). The method requires three parameters to be sent in the call path (URL): SessionId, QueryId and QueryPartNumber, and the output returns a response consistent with ApplicationZipContent. KSeF REST API - pobranie wyników wyszukiwania faktur KSeF

Figure: ksefInvoiceQueryResult

SessionId

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

QueryId

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

QueryPartNumber

The class represents the search pack number. partNumber : string – Fragment (package) identifier of the search result

ApplicationZipContent

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

POST

HTTP POST type methods.

ksefSessionOpen

ksefSessionOpen(invoice : KsefSessionOpenRequest): KsefSessionOpenResponse The method enables the establishment of 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 that complies with KsefSessionOpenRequest, and the output returns a response consistent with KsefSessionOpenResponse. KSeF REST API - otwarcie sesji

Drawing: ksefSessionOpen

KsefSessionOpenRequest

The class represents a request to create an interactive session encryptedKey : string – If encryption of transmitted data (invoices) is to be used within the interactive session, the attribute should contain a symmetric encryption key (AES256) generated before opening a new session and encrypted with the RSA public key of the KSeF platform obtained using the operation ksefPublicKey. (Required: [0..1]) initVector : string – The attribute describes the so-called initialization vector. The allowed AES symmetric key encryption algorithm is AES/CBC/PKCS5Padding (PKCS#7). The allowed symmetric key is AES with a length of 256 bits supported by a random initialization vector of length 16 bytes. (Required: [0..1]) invoiceVersion : KsefInvoiceVersion – Indication of the schema version in which KSeF invoices will be sent as part of the established session.

KsefInvoiceVersion

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

KsefSessionOpenResponse

Response in case of correctly created session created : string – The attribute contains the date and time of session creation in date-time format. id : string – The attribute contains the identifier of the created session. It should be saved on the calling system side, because it will be used in most of the remaining operations.

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.

Attention! A detailed description of the classes and input 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 compliant with the schema applicable in KSeF.

ksefInvoiceValidate

ksefInvoiceValidate(ksefInvoice : KsefInvoice): KsefInvoiceValidateResponse The method allows you to verify the KSeF invoice for compliance with the schema. The object should be sent as a parameter to call the operation TextXmlContent containing the generated KSeF invoice. An external tool or operation can be used to generate the invoice ksefInvoiceGenerateIn response, the operation returns an object KsefInvoiceValidateResponse with information about what schema version the invoice was generated in and whether it is compatible 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 schema (valid)

TextXmlContent

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

KsefInvoiceValidateResponse

A response containing information about the schema version in which the sent KSeF invoice was generated and whether it is compatible with this schema. invoiceVersion : KsefInvoiceVersion – One of two possible schema versions defined in the enum KsefInvoiceVersion. valid : boolean – The True value (1) means that the invoice sent for verification is compliant with the schema, however, if the invoice XML file is found to be incompatible with the schema, the HTTP code and the object are returned Error with the description of the first detected schema mismatch error in the attribute details.

ksefInvoiceSend

ksefInvoiceSend(invoice : KsefInvoiceSendRequest): KsefInvoiceSendResponse The method enables sending 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, you must first call the operation ksefSessionOpen in order to establish an interactive session. The input method requires the creation of a request in accordance with KsefInvoiceSendRequest, and the output returns a response 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: with or without 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 (KsefSessionOpenRequest). (Required: [0..1]) plain : KsefInvoicePlain – Attribute specifies the variant (choice) that is used to send unencrypted invoice XML in a session created with no encryption. (Required: [0..1]) sessionId : string – Session ID obtained when establishing an interactive session: ksefSessionOpen.

KsefInvoiceEncrypted

The object represents the invoice being sent 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 the initialization vector (attribute initVector Classes KsefSessionOpenRequest) and the symmetric key generated when creating the session. invoiceHash : string – The attribute contains the SHA256 hash value of the original (unencrypted) XML form of the invoice that is sent to KSeF. invoiceSize : int – Attribute containing the calculated invoice size (size in bytes of the original, unencrypted XML form of the invoice) that is sent to KSeF.

KsefInvoicePlain

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

KsefInvoiceSendResponse

The class represents the response obtained from KSeF in case of successful invoice sending. Attention! The response informs that the invoice has been correctly sent to KSeF, however, to be sure that the invoice has been correctly saved in KSeF, the operation should be called ksefInvoiceStatus, one of the input parameters of which is technical invoice identifier returned as 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 invoice identifier 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 that complies with KsefInvoiceQueryStartRequest. The method returns an object that complies 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 defining search parameters. range : KsefInvoiceQueryStartRange – Select the period for which invoices are to be searched (Required: [0..1]) sessionId : string – Active session ID subjectType : SubjectType – Specifies what type of invoice we are looking for:

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

SubjectType

Enumeration defines the possible types of entity subject1 : – The attribute indicates the entity issuing the invoice subject2 : – The attribute indicates the entity receiving the invoice subject3 : - The attribute denotes a third party SubjectAuthorized : – The attribute denotes an 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 until which invoices will be searched.

KsefInvoiceQueryStartResponse

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

ksefInvoiceVisualize

ksefInvoiceVisualize(KsefInvoiceVisualizeRequest : KsefInvoiceVisualizeRequest): KsefInvoiceVisualizeContent A method that allows you to generate a visualization of an XML structured invoice in one of the formats: HTML and PDF. The method requires the preparation of a request in accordance with the input KsefInvoiceVisualizeRequestand in response returns an object of type TextHtmlContent for HTML visualization or ApplicationPdfContent for visualization in a 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 determines whether a QR code should be attached to the visualization. This option may be used for invoices issued to foreign contractors who will not have access to KSeF anyway, and the method of transferring (delivering) the invoice will depend on the issuing entity. invoiceDate : string – The attribute passes the XML file of the KSeF invoice for which the visualization is to be performed. invoiceKsefNumber : string – The attribute contains a unique KSeF invoice number assigned by the National e-Invoice System when the invoice is correctly sent to the National e-Invoice System. 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:

en
en
pl_en

OutputFormat

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

Enumeration defines the language in which the invoice visualization is to be generated en : 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 a KSeF invoice in the form of a PDF file. description : string – = PDF Visualization

TextHtmlContent

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

Parameters

The chapter contains a list of all parameters divided by type:

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

KSeF REST API - parametry

Figure: Parameters

Path

The operation call parameters contained in the path.

SessionId

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

InvoiceId

InvoiceKsefNumber

KSeF invoice number generated by KSeF. invoiceKsefNumber : string – Invoice ID generated by KSeF. Generation of this ID confirms saving the sent invoice in KSeF.

QueryId

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

QueryPartNumber

The class represents the search pack number. partNumber : string – Fragment (package) identifier of the search result

RequestBody

Parameters of type requestBody.

KsefInvoiceEncrypted

KsefInvoicePlain

The object represents the invoice being sent in clear (unencrypted) form. invoice : string – Attribute containing the invoice XML file in unencrypted byte format 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 until which invoices will be searched.

KsefInvoiceQueryStartRequest

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

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

KsefInvoiceSendRequest

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 determines whether a QR code should be attached to the visualization. This option may be used for invoices issued to foreign contractors who will not have access to KSeF anyway, and the method of transferring (delivering) the invoice will depend on the issuing entity. invoiceDate : string – The attribute passes the XML file of the KSeF invoice for which the visualization is to be performed. invoiceKsefNumber : string – The attribute contains a unique KSeF invoice number assigned by the National e-Invoice System when the invoice is correctly sent to the National e-Invoice System. 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:

en
en
pl_en

Enumerations

This chapter contains a list of all enumerations that can be used in the interface. KSeF REST API - Enumeracje

Figure: Enumerations

InvoiceStatus

Enumeration defining the possible statuses of the sent invoice returned by KsefInvoiceStatusResponse processing : string – The status returned from KSeF means that the sent invoice is still being processed. You should wait a moment 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 error message details (Error), you should check what was the reason for rejection of the invoice.