Ksefapi-cli Application Documentation
Client application ksefapi-cli.exe is a console tool (CLI) enabling quick and seamless integration with National e-Invoice System (KSeF) via the ksefapi.pl website. The program allows you to automate the processes of sending, downloading, and visualizing accounting documents directly from the command line.
General description and use of the application
The ksefapi-cli.exe program was designed for programmers, system administrators and IT departments who need a tool for mass or automated invoice processing in KSeF without the need to write dedicated API software.
Below are the most important functionalities of the application:
- Document shipment: Single or bulk (in batches) sending of invoices in XML format to the KSeF system.
- Data download: Searching and downloading structured invoices from KSeF (cost or sales) from a specific time period.
- Downloading invoice metadata: Super fast search and download of only basic metadata describing found invoices.
- Visualization: Generating readable PDF or HTML files from raw XML invoice data and Official Receipt Certificates (UPO).
- Automation (scripts): Possibility of easy embedding in task schedules (e.g. Windows Task Scheduler, bash/bat scripts) for cyclical data exchange with the National e-Invoice System.
Download the application
The application has been made available on our website in the section Download and is available in two versions:
After downloading the application, you need to unpack it (the file ZIP or TAR.GZ) in the target directory. After unpacking from the archive, the application is ready to use. It only requires entering the following parameters: key identifier and API key. To obtain both parameters, it is necessary to execute Registration and creating an account on the website.
Application configuration
App ksefapi-cli.exe It does not require complicated installation. For proper operation and authorization of queries on the ksefapi.pl website, you must have:
- API Key ID (
--key-id) - API key (
--key)
Authorization parameters and environment configuration (test/production) are passed directly during each program invocation using appropriate options. When operating within corporate networks, the application also supports connection configuration via a proxy server (–proxy).
Startup method
The application should be downloaded from our website – section Downloadand then run it from the terminal (Command Prompt) cmd or PowerShell). Running the application is also possible from the Linux operating system.
The basic call syntax is as follows:
ksefapi-cli.exe [options]
To check if the application is working correctly or to display quick help, execute the command:
ksefapi-cli.exe --help
Call syntax description
Each query to the system requires the definition of one main commands (Commands) and an optional set of parameters options (Options).
Commands (Commands)
Select one of the following commands to determine the program's behavior:
| Command | Description |
--help |
Displays help text describing the syntax. |
--version |
Displays the current program version. |
--upload-invoice |
Sends a single invoice to the KSeF system. |
--upload-batch |
Sends a package of invoices (ZIP file) to the KSeF system. |
--download-invoices |
Downloads invoices from the KSeF system based on criteria. |
--invoice-visualize |
Generates a visualization for the specified invoice. |
--upo-visualize |
Generates a visualization for a UPO (Official Receipt Confirmation) document. |
Options (Options)
Modifiers and additional parameters for commands:
| Option | Data description and format |
--env |
KSeF API environment. Available values: prod or test (default: prod). |
--key-id |
Your API key ID. |
--key |
The value of your API key. |
--proxy |
HTTP proxy server URL. Format: http[s]://user:password@hostname:port |
--ksef-number |
Unique invoice identification number in the KSeF system. |
--range-from |
Start date of the time range. Format: yyyy-mm-dd (year – month – day). Date range (from –this) cannot exceed 3 months. |
--range-to |
End date of the time range. Format: yyyy-mm-dd (year – month – day). Date range (from –this) cannot exceed 3 months. |
--format |
Output file format. Available values: csv, json, html, pdf, xml (default: xml). |
--csv-variant |
CSV file format (Excel, std, the default format is std, which complies with RFC 4180) |
--lang |
Output language of the document. Available values: en, pl (default: pl). |
--file-name |
Output file name template. Available:
|
--subject-type |
Invoice type to download. Available values: Subject1(sales invoices) Subject2(cost invoices) Subject3, SubjectAuthorized (default: Subject2). |
--in-file |
Path to input file. |
--out-file |
Path to output file. |
--out-dir |
Path to output directory. |
Examples of use
Below are practical examples of using the application for the most common scenarios (replace the abcdefgh and ijklmnop key values with your own).
Sending XML invoices and receiving UPOs
Sends a single XML invoice and saves the generated UPO certificate:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --upload-invoice --in-file invoice.xml --out-file upo.xml
Sending a package of invoices and receiving UPO
Uploads a ZIP archive containing multiple invoices and saves the generated UPO certificate:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --upload-batch --in-file invoices.zip --out-file upo.xml
Downloading invoices from a specific time range as XML files
Downloads invoices issued in the specified time period and saves them as XML files in the specified folder:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --download-invoices --range-from 2026-03-01\--range-to 2026-03-31 --subject-type Subject2 --out-dir invoices
Download invoices from a specific time range as PDF files
Downloads invoices from a given time period, automatically generates PDF files from them with a specific naming format and saves them in the specified folder:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --download-invoices --range-from 2026-03-01\--range-to 2026-03-31 --subject-type Subject2 --pdf format --file-name yyyy-mm-buyer-num --out-dir invoices
Generating invoice visualization
Generates a PDF file in English for the given invoice based on its KSeF number:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --invoice-visualize --in-file invoice.xml\--ksef-number 123456789 --pdf format --lang en --out-file invoice.pdf
Generating UPO visualizations
Creates a readable PDF document in English based on a raw XML file with a UPO receipt:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --upo-visualize --in-file upo.xml\--pdf format --lang en --out-file upo.pdf
Downloading metadata describing invoices from a specific time range in CSV or JSON format
Downloads the metadata of invoices issued during the specified time period and saves them as CSV files in the current folder:
ksefapi-cli --env prod --key-id abcdefgh --key ijklmnop --download-metadata --range-from 2026-03-01 \ --range-to 2026-03-31 --subject-type Subject2 --format csv --out-file invoices.csv
To get a file in the format JSON just use the option --json format and provide the output file name with the appropriate extension: --out-file invoices.json
Below is a description of the returned metadata describing the invoice:
| Column | Description |
issue_date |
Invoice issue date |
invoice_number |
Invoice number assigned by the Seller |
ksef_number |
KSeF number of the invoice |
invoice_type |
Invoice type |
seller_number |
Seller's Tax Identification Number |
seller_name |
Seller Name |
buyer_number |
Buyer's Tax Identification Number |
buyer_name |
Buyer's Name |
currency |
Currency |
net_amount |
Net amount |
vat_amount |
VAT value |
gross_amount |
Gross amount. |
invoicing_mode |
Invoice issuing mode |