Ksef plugin
Integration with new API version of Krajowy Systeme-Faktur
Official documentation of KSef API 2.0
https://api.ksef.mf.gov.pl/docs/v2/index.html
Official github repository of CIRFMF
Contains implementation of clients in Java and C#
Configuration (ksef/config.js)
Structure of the configuration is expected in form of JSON object. It is possible to have multiple configuration prepared. Every single is accessable in TAS calculations under the name of the attribute (more detail in function initSessionToken).
Example setup of configuration myAwesomeCompany is included in the plugin.
environment: option to connecto to production or test version of KSeF API
token: generated token to connect with - (it is not possible to reuse old token from version 1.0)
nip: identifier of taxpayer
identifier: type of identifier, all supported types are listed in official API documentation
encryptionKey a initializationVector: values are used in encrypted communitation with API. Mainly in processes of exporting multiple invoices and downloading them as ZIP archive (it is possible to reuse value from example configuration myAwesomeCompany)
TAS Calculation library
Plugin functions are available under alias ksef. Simple example of usage in TAS calculation is shown at the end of this block.
New version of API has implemented rate limiter on accessing all endpoints. Below each function description is max limit per second, minute and hour respectively. Listed values are to date 2026-01-15.
Exceeding the limit can result in temporary or permanent banning of the access token.
initSessionToken(configurationName string)
login with given configuration.
On success an access token is returned.
If the configuration is not present in the config file an error is thrown.
Limits on the number of requests 60 - - -
queryInvoices(accessToken: string, queryCriteria: any, pageSize?: number, pageOffset?: number)
Access token is expected tha same that is returned from initSessionToken.
Retrieve metadata of invoices based on provided filter and pagination.
Full list of available options in queryCritieria is described here
Limits on the number of requests 80 160 200 invoiceMetadata
downloadInvoice(accessToken: string, ksefReferenceNumber: string, filePath: string)
Access token is expected tha same that is returned from initSessionToken.
Download xml of the invoice indentified by ksefReferenceNumber.
The file is saved in provided filePath. Path have to be in allowedExternalSources
Limits on the number of requests 80 160 640 invoiceDownload
invoiceToDms(accessToken: string, ksefReferenceNumber: string, fileName: string)
Access token is expected tha same that is returned from initSessionToken.
Download xml of the invoice indentified by ksefReferenceNumber.
Saving the file as an attachment to current process under the provided file name
Limits on the number of requests 80 160 640 invoiceDownload
initiateExport(accessToken: string, filter: Filter)
Access token is expected tha same that is returned from initSessionToken.
Start the export process of selected invoice with given filter.
On successful initiation a reference number is returned. This number is later used to download the prepared ZIP archive with function downloadExport.
The export process is asynchronous, where KSeF server is starting to prepare the files in background.
Export has limitation of 10000 invoices and 1GB.
Detail information about filter and specifics of the export process are described here
Limits on the number of requests 40 80 200 invoiceExport
downloadExport(accessToken: string, referenceNumber: string, errorOnMultipart: boolean = true)
Access token is expected tha same that is returned from initSessionToken.
Reference number of the previously initiated export process with initiateExport.
If the export is not ready an error will be thrown. Both for IN_PROGRESS an ERROR status. It is needed to handle it in calculation itself.
If the export is ready to be downloaded. plugin will retrieved needed data, download the ZIP archive and attach it to current process.
If the export is bigger in size it will be available in multipart archive. On default it is handled by TAS as an Error. Currently there are no functions to work with multipart archives.
It is possible to download the multipart archive via TAS plugin and attach it to process by setting parameter errorOnMultipart to false.
Detail description of export status endpoint
Limits on the number of requests 100 600 6000 invoiceExportStatus
Example calcution retrieving export:
const token = ksef.initSessionToken("myAwesomeCompany");
vars['token'].setValue(token);
const filter = {
"subjectType": "Subject3",
"dateRange": {
"dateType": "PermanentStorage",
"from": "2025-11-18T09:22:13.388+00:00",
"to": "2025-11-28T09:22:13.388+00:00"
},
"amount": {
"type": "Brutto",
"from": 1000.5,
// "to": 250
},
};
const refNum = ksef.initiateExport(token, filter);
vars['referenceNumber'].setValue(refNum);
debug.sleep(10); // for simplicity, better to handle it with scheduled task because the export process can take seconds or minutes
const referenceNumber = vars['referenceNumber'].getValue();
const exportIds = ksef.downloadExport(token, referenceNumber);
zip.unzipDmsFile(exportIds[0])
