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)
Components
For the purposes of this documentation, three basic components were adopted that participate in business processes related to invoice handling within KSeF:
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.
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.
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.
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.
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.
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. 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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 bytes (base64
) 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.
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.
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
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
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
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
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
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 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 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
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.
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
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.
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 v1 : – First version of the schema v2 : – Second version of the scheme (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.
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.
Figure: 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.
Figure: 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.
Figure: Error messages - invoice
INVOICE_FORMAT – Incorrect format of the sent invoice
description = The invoice has an incorrect format code = 1203
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
Figure: 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