Documentation – KSeF Service (API + PowerShell client)

0. Quick start

Requirements

• Windows + PowerShell 5.1+
• Internet access
• Access credentials: clientId, login, password

Running the PowerShell client

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch

On first run, the script will ask for configuration (login/password/directories), save it in the registry (HKCU), and automatically load it on subsequent runs.

1. Interactive sending of FA(3) invoice (XML)

This endpoint is used for interactive submission of a single FA(3) invoice to KSeF. You send one XML file and receive session/status data and (if available) the UPO in response.

Endpoint:

POST https://ksefservice.pl/api/v1/invoices/send

Example usage (curl)

curl -X POST https://ksefservice.pl/api/v1/invoices/send \
  -H "Accept: application/json" \
  -F "clientId=3c996a3f-7504-424e-851b-eaec2258777b" \
  -F "login=biuro@bsd-net.pl" \
  -F "password=PANEL_PASSWORD" \
  -F "api_env=TEST" \
  -F "file=@invoice_FA3.xml;type=application/xml"

Example usage (curl) – without XSD validation

curl -X POST https://ksefservice.pl/api/v1/invoices/send \
  -H "Accept: application/json" \
  -F "clientId=3c996a3f-7504-424e-851b-eaec2258777b" \
  -F "login=biuro@bsd-net.pl" \
  -F "password=PANEL_PASSWORD" \
  -F "api_env=TEST" \
  -F "validate_xsd=0" \
  -F "file=@invoice_FA3.xml;type=application/xml"

Sample response – success

{
  "success": true,
  "stage": "ksef_ok",
  "message": "FA(3) invoice was successfully sent to KSeF.",
  "data": {
    "nip": "5771876968",
    "sessionReference": "20251223-INT-XXXX",
    "invoiceReference": "20251223-INV-XXXX",
    "ksefNumber": "5771876968-20251223-010080XXXXXX-XX",
    "processingCode": 200,
    "upo_xml": "<?xml version='1.0' encoding='UTF-8'?>..."
  }
}

Note: depending on the KSeF response, the status may be e.g. 100 / 150 (processing), and the KSeF number may appear later.

2. Batch sending of FA(3) invoices (ZIP / batch)

This endpoint is used to send a ZIP package containing one or more .xml FA(3) files. The server extracts the ZIP, optionally validates XSD, and then sends the batch to KSeF.

Endpoint:

POST https://ksefservice.pl/api/v1/invoices/send-batch

Example usage (curl)

curl -L -X POST "https://ksefservice.pl/api/v1/invoices/send-batch" \
  -H "Accept: application/json" \
  -F "clientId=3c996a3f-7504-424e-851b-eaec2258777b" \
  -F "login=biuro@bsd-net.pl" \
  -F "password=PANEL_PASSWORD" \
  -F "api_env=TEST" \
  -F "wait=0" \
  -F "validate_xsd=1" \
  -F "zip=@fa3_package.zip;type=application/zip"

Example usage (curl) – without XSD validation

curl -L -X POST "https://ksefservice.pl/api/v1/invoices/send-batch" \
  -H "Accept: application/json" \
  -F "clientId=3c996a3f-7504-424e-851b-eaec2258777b" \
  -F "login=biuro@bsd-net.pl" \
  -F "password=PANEL_PASSWORD" \
  -F "api_env=TEST" \
  -F "wait=0" \
  -F "validate_xsd=0" \
  -F "zip=@fa3_package.zip;type=application/zip"

Sample response – success

{
  "success": true,
  "stage": "ksef_ok",
  "message": "FA(3) batch was sent to KSeF.",
  "data": {
    "referenceNumber": "20251223-SB-2C32928000-AAADD850F8-B5",
    "send_meta": { "invoiceCount": 1 },
    "status_initial": {
      "status": { "code": 150, "description": "Processing" }
    },
    "status_final": null,
    "invoices": []
  }
}

Note: to retrieve the list of processed invoices in the batch, set wait=1.

3. Downloading invoices from KSeF (API)

3.1 Download metadata (list) from KSeF

Endpoint:

POST https://ksefservice.pl/api/v1/invoices/search

curl -X POST https://ksefservice.pl/api/v1/invoices/search \
  -F "clientId=3c996a3f-7504-424e-851b-eaec2258777b" \
  -F "login=biuro@bsd-net.pl" \
  -F "password=PANEL_PASSWORD" \
  -F "api_env=TEST" \
  -F "invoice_type=all" \
  -F "date_from=2025-12-01" \
  -F "date_to=2025-12-23" \
  -F "pageSize=50" \
  -F "pageOffset=0"

invoice_type: sale (Subject1), purchase (Subject2), all (Subject1+Subject2). The response includes e.g. the ksefNumber field.

3.2 Download XML by KSeF number

Endpoint:

POST https://ksefservice.pl/api/v1/invoices/download

curl -s -X POST https://ksefservice.pl/api/v1/invoices/download \
  -F "clientId=3c996a3f-7504-424e-851b-eaec2258777b" \
  -F "login=biuro@bsd-net.pl" \
  -F "password=PANEL_PASSWORD" \
  -F "api_env=TEST" \
  -F "search_by=ksef" \
  -F "ksefNumber=5771876968-20251216-010080E15E2C-BB"

The /invoices/download endpoint supports modes: search_by=ksef and search_by=invoice.

4. KSeF QR code generation (PNG)

Endpoint:

POST https://ksefservice.pl/api/invoices/qr-code/invoice

Note: the parameter name is ulr_api (typo preserved 1:1).

5. API errors

PowerShell script (client): http://ksefservice.pl/files/KSeFService.ps1

6. PowerShell client (KSeFService.ps1) – how it works

6.1 Configuration (first run only)

The script detects configuration in the user registry and, if missing, starts the configuration wizard.

Where is the configuration stored?

HKCU:\Software\KSeFServicePS

What is stored?

• ClientId, Login, ApiEnv
• PasswordEnc – password encrypted with DPAPI (CurrentUser)
• InputDir – input directory (XML/ZIP to send)
• OutputDir – output directory (logs/UPO/archive)
• WaitFinal – wait parameter for batch (0/1)
• ValidateXsd – validate_xsd parameter (0/1) – informational if forced to 0 in code

6.2 Operating modes

Interactive

• The script looks for *.xml files in InputDir
• For each file, it sends a request to /api/v1/invoices/send
• Saves the JSON response to OutputDir
• If upo_xml is present, saves the UPO XML file

Batch

• The script looks for *.zip and *.xml in InputDir
• *.zip files are sent unchanged to /api/v1/invoices/send-batch
• *.xml files are packed into a temporary ZIP and sent as a batch
• Saves the JSON response to OutputDir
• Optionally (depending on API and wait=1) may save UPO per invoice

6.3 Input file archiving

After processing a file (success/error), the script moves the input file to the archive:

OutputDir\archive\sent\   (when success=true)
OutputDir\archive\error\  (on error or success=false)

The archived file name gets a timestamp suffix (to avoid overwriting files).

6.4 Task Scheduler

The script can create and remove a Task Scheduler task for Interactive or Batch mode. The task runs the script with parameters and allows cyclic execution.

Install task (interactive – script will ask for frequency):

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -InstallTask

Remove task:

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -UninstallTask

Note: configuration is stored in HKCU (current user), so the task should run under the same account that performed the initial configuration.

6A. All possible KSeFService.ps1 invocations

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1"

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Interactive

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -EnvOverride TEST

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -EnvOverride PROD

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -Reconfigure

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -InstallTask

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Path\KSeFService.ps1" -Mode Batch -UninstallTask

7. Linux client (KSeFService.sh)

KSeFService.sh is a Bash client for Linux systems (e.g. Debian / Ubuntu), enabling automatic submission of FA(3) invoices to the KSeF Service API, logging, optional UPO retrieval, and file archiving.

Download the script

The script can be downloaded from: https://ksefservice.pl/files/KSeFService.sh

7.1 Requirements

• Linux (Debian/Ubuntu)
• Bash
• curl, zip
• Optional: jq (UPO handling)
• Optional: libsecret (secret-tool) – secure password storage

7.2 First run

chmod +x KSeFService.sh
./KSeFService.sh

Configuration file:

~/.config/ksefservice/config.env

7.3 Operating modes

Interactive (XML)

./KSeFService.sh --mode interactive

Batch (ZIP / XML → ZIP)

./KSeFService.sh --mode batch

7.4 Enterprise mode (interactive)

--enterprise

./KSeFService.sh --mode interactive --enterprise

--enterprise-resend

./KSeFService.sh --mode interactive --enterprise-resend

7.5 Other options

7.6 Logs and archiving

• JSON logs are saved in the output directory
• Processed files go to archive/sent or archive/error

7.7 Automation (cron)

0 22 * * * cd /root && /root/KSeFService.sh --mode batch >> /root/ksef_cron.log 2>&1