API usage examples

import { Component } from '@angular/core';
import { HttpEventType, HttpErrorResponse } from '@angular/common/http';
import { KsefEnv, KsefInvoicesService } from '../../services/ksef-invoices.service';

@Component({
  selector: 'app-ksef-invoice-upload',
  templateUrl: './ksef-invoice-upload.component.html',
})
export class KsefInvoiceUploadComponent {
  clientId = '3c996a3f-7504-424e-851b-eaec2258777b';
  login = 'biuro@bsd-net.pl';
  password = '';
  api_env: KsefEnv = 'TEST';

  file: File | null = null;
  uploading = false;
  progress = 0;
  successMsg = '';
  errorMsg = '';
  responseBody: any = null;

  constructor(private ksef: KsefInvoicesService) {}

  onFileChange(evt: Event) {
    this.errorMsg = '';
    this.successMsg = '';
    this.responseBody = null;

    const input = evt.target as HTMLInputElement;
    const f = input.files?.[0] ?? null;

    if (!f) {
      this.file = null;
      return;
    }

    const isXmlByType = f.type === 'application/xml' || f.type === 'text/xml' || f.type === '';
    const isXmlByName = f.name.toLowerCase().endsWith('.xml');

    if (!isXmlByType && !isXmlByName) {
      this.file = null;
      this.errorMsg = 'Select an XML file (e.g. invoice_FA3.xml).';
      input.value = '';
      return;
    }

    this.file = f;
  }

  submit() {
    this.errorMsg = '';
    this.successMsg = '';
    this.responseBody = null;
    this.progress = 0;

    if (!this.clientId || !this.login || !this.password || !this.api_env) {
      this.errorMsg = 'Fill in clientId, login, password, and environment.';
      return;
    }

    if (!this.file) {
      this.errorMsg = 'Select the invoice XML file.';
      return;
    }

    this.uploading = true;

    this.ksef.createInvoice({
      clientId: this.clientId,
      login: this.login,
      password: this.password,
      api_env: this.api_env,
      file: this.file
    }).subscribe({
      next: (event) => {
        if (event.type === HttpEventType.UploadProgress) {
          const total = event.total ?? 0;
          this.progress = total > 0 ? Math.round((event.loaded / total) * 100) : 0;
        }

        if (event.type === HttpEventType.Response) {
          this.uploading = false;
          this.progress = 100;
          this.responseBody = event.body;
          this.successMsg = 'The invoice has been sent.';
        }
      },
      error: (err: HttpErrorResponse) => {
        this.uploading = false;
        this.progress = 0;

        const serverMsg =
          (typeof err.error === 'string' ? err.error : (err.error?.message ?? '')) ||
          err.message;

        this.errorMsg = `Upload error (${err.status}): ${serverMsg}`;
        this.responseBody = err.error ?? null;
      }
    });
  }
}

<div class="container py-4">
  <div class="row justify-content-center">
    <div class="col-12 col-lg-8">

      <div class="card shadow-sm">
        <div class="card-body">
          <h5 class="card-title mb-3">Send FA(3) invoice to KSeF Service</h5>

          <div *ngIf="successMsg" class="alert alert-success">{{ successMsg }}</div>
          <div *ngIf="errorMsg" class="alert alert-danger">{{ errorMsg }}</div>

          <div class="mb-3">
            <label class="form-label">clientId</label>
            <input class="form-control" [(ngModel)]="clientId" placeholder="Client UUID" />
          </div>

          <div class="mb-3">
            <label class="form-label">login</label>
            <input class="form-control" [(ngModel)]="login" placeholder="e.g. biuro@bsd-net.pl" />
          </div>

          <div class="mb-3">
            <label class="form-label">password</label>
            <input class="form-control" type="password" [(ngModel)]="password" placeholder="PANEL_PASSWORD" />
          </div>

          <div class="mb-3">
            <label class="form-label">api_env</label>
            <select class="form-select" [(ngModel)]="api_env">
              <option value="TEST">TEST</option>
              <option value="DEMO">DEMO</option>
              <option value="PROD">PROD</option>
            </select>
          </div>

          <div class="mb-3">
            <label class="form-label">XML file</label>
            <input class="form-control" type="file" accept=".xml,application/xml,text/xml" (change)="onFileChange($event)" />
            <div class="form-text" *ngIf="file">Selected: <b>{{ file.name }}</b> ({{ file.size }} B)</div>
          </div>

          <div *ngIf="uploading" class="mb-3">
            <div class="progress">
              <div class="progress-bar" role="progressbar"
                   [style.width.%]="progress"
                   [attr.aria-valuenow]="progress"
                   aria-valuemin="0" aria-valuemax="100">
                {{ progress }}%
              </div>
            </div>
          </div>

          <button class="btn btn-primary"
                  [disabled]="uploading"
                  (click)="submit()">
            {{ uploading ? 'Uploading...' : 'Send' }}
          </button>
        </div>
      </div>

      <div *ngIf="responseBody" class="card mt-3">
        <div class="card-body">
          <h6 class="mb-2">API response</h6>
          <pre class="mb-0">{{ responseBody | json }}</pre>
        </div>
      </div>

    </div>
  </div>
</div>

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { FormsModule } from '@angular/forms';

import { AppComponent } from './app.component';
import { KsefInvoiceUploadComponent } from './components/ksef-invoice-upload/ksef-invoice-upload.component';

@NgModule({
  declarations: [AppComponent, KsefInvoiceUploadComponent],
  imports: [BrowserModule, HttpClientModule, FormsModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

<!-- app.component.html -->
<app-ksef-invoice-upload></app-ksef-invoice-upload>

using System.Net.Http.Headers;

public class KsefService
{
    private readonly HttpClient _httpClient;

    public KsefService(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<string> SendInvoiceAsync(SendInvoiceRequest req)
    {
        using var form = new MultipartFormDataContent();

        form.Add(new StringContent(req.ClientId.ToString()), "clientId");
        form.Add(new StringContent(req.Login), "login");
        form.Add(new StringContent(req.Password), "password");
        form.Add(new StringContent(req.Api_Env), "api_env");

        using var stream = req.File.OpenReadStream();
        using var fileContent = new StreamContent(stream);
        fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/xml");

        form.Add(fileContent, "file", req.File.FileName);

        using var response = await _httpClient.PostAsync(
            "https://ksefservice.pl/api/v1/invoices/send",
            form
        );

        var body = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
            throw new ApplicationException($"API error: {response.StatusCode} - {body}");

        return body;
    }
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient<KsefService>(client => {
    client.Timeout = TimeSpan.FromSeconds(60);
});

var app = builder.Build();
app.Run();

using Microsoft.AspNetCore.Http;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient<KsefService>(client => {
    client.Timeout = TimeSpan.FromSeconds(60);
});

var app = builder.Build();

app.MapPost("/send-example", async (KsefService ksefService) => {
    var path = "invoice_FA3.xml";

    if (!File.Exists(path))
        return Results.BadRequest("File invoice_FA3.xml not found");

    await using var stream = File.OpenRead(path);

    IFormFile formFile = new FormFile(stream, 0, stream.Length, "file", "invoice_FA3.xml")
    {
        Headers = new HeaderDictionary(),
        ContentType = "application/xml"
    };

    var request = new SendInvoiceRequest
    {
        ClientId = Guid.Parse("3c996a3f-7504-424e-851b-eaec2258777b"),
        Login = "biuro@bsd-net.pl",
        Password = "PANEL_PASSWORD",
        Api_Env = "TEST",
        File = formFile
    };

    var result = await ksefService.SendInvoiceAsync(request);
    return Results.Content(result, "application/json");
});

app.Run();

javac KsefSendInvoiceExample.java
java KsefSendInvoiceExample

The API returns JSON, for example information about successful submission, the KSeF number, processing status, or a validation error.

{
  "success": true,
  "stage": "ksef_ok",
  "message": "The FA(3) invoice was successfully sent to KSeF.",
  "data": {
    "ksefNumber": "5771876968-20251209-0100805B192F-B3",
    "sessionReference": "20251209-SO-178C9DF000-9498D48B5B-BB",
    "invoiceReference": "20251209-EE-178CA6F000-554110E66B-16"
  }
}

// e.g. in FormCreate
IdHTTP1->IOHandler = IdSSLIOHandlerSocketOpenSSL1;

IdSSLIOHandlerSocketOpenSSL1->SSLOptions->Method = sslvTLSv1_2;
IdSSLIOHandlerSocketOpenSSL1->SSLOptions->Mode   = sslmClient;

IdHTTP1->HandleRedirects = true;
IdHTTP1->ReadTimeout = 60000;

void __fastcall TForm1::BtnSendClick(TObject *Sender) {
    if (!OpenDialog1->Execute())
        return;

    SendInvoice(
        "https://ksefservice.pl/api/v1/invoices/send",
        "3c996a3f-7504-424e-851b-eaec2258777b",
        "biuro@bsd-net.pl",
        "PANEL_PASSWORD",
        "TEST", // TEST | DEMO | PROD
        OpenDialog1->FileName
    );
}

#include <IdHTTP.hpp>
#include <IdMultipartFormData.hpp>
#include <IdSSLOpenSSL.hpp>
#include <memory>

void __fastcall TForm1::SendInvoice(
    const String& url,
    const String& clientId,
    const String& login,
    const String& password,
    const String& apiEnv,
    const String& xmlPath
) {
    if (!xmlPath.LowerCase().EndsWith(".xml"))
    {
        MemoLog->Lines->Add("Error: select an XML file (.xml).");
        return;
    }

    std::unique_ptr<TIdMultiPartFormDataStream> form(new TIdMultiPartFormDataStream());

    try
    {
        form->AddFormField("clientId", clientId);
        form->AddFormField("login", login);
        form->AddFormField("password", password);
        form->AddFormField("api_env", apiEnv);

        form->AddFile("file", xmlPath, "application/xml");

        IdHTTP1->Request->Accept = "application/json";
        IdHTTP1->Request->ContentType = form->RequestContentType;

        MemoLog->Lines->Add("Sending invoice...");

        String response = IdHTTP1->Post(url, form.get());

        MemoLog->Lines->Add("OK:");
        MemoLog->Lines->Add(response);
    }
    catch (const EIdHTTPProtocolException &e)
    {
        MemoLog->Lines->Add("HTTP ERROR:");
        MemoLog->Lines->Add(e.ErrorMessage);
        MemoLog->Lines->Add(e.ErrorText);
    }
    catch (const Exception &e)
    {
        MemoLog->Lines->Add("ERROR:");
        MemoLog->Lines->Add(e.Message);
    }
}

void __fastcall TForm1::Button1Click(TObject *Sender) {
    String output;

    bool ok = RunCurlInvoices(
        L"curl",
        L"C:\\temp\\invoice_FA3.xml",
        L"3c996a3f-7504-424e-851b-eaec2258777b",
        L"biuro@bsd-net.pl",
        L"PANEL_PASSWORD",
        L"TEST", // TEST | DEMO | PROD
        output,
        60000
    );

    Memo1->Lines->Text = output;

    if (!ok) {
        ShowMessage(L"Failed to start curl (check PATH or the path to curl.exe).");
    }
}

Interactive mode is used for sending single XML files.

.\KSeFService.ps1 -Mode Interactive

Batch mode is used for sending ZIP packages and XML files, which the script will automatically compress into ZIP.

.\KSeFService.ps1 -Mode Batch

If you want to set clientId, login, password, api_env, and the input/output directories again, use the -Reconfigure parameter.

.\KSeFService.ps1 -Reconfigure

.\KSeFService.ps1 -Mode Batch -Reconfigure

You can override the environment only for the current run using the -EnvOverride parameter.

Available values:

• TEST
• PROD
• DEMO

Examples:

.\KSeFService.ps1 -Mode Interactive -EnvOverride DEMO

.\KSeFService.ps1 -Mode Batch -EnvOverride TEST

To install a task for Interactive mode:

.\KSeFService.ps1 -Mode Interactive -InstallTask

To install a task for Batch mode:

.\KSeFService.ps1 -Mode Batch -InstallTask

To remove a task for Interactive mode:

.\KSeFService.ps1 -Mode Interactive -UninstallTask

To remove a task for Batch mode:

.\KSeFService.ps1 -Mode Batch -UninstallTask

If PowerShell blocks the script, use:

powershell.exe -ExecutionPolicy Bypass -File .\KSeFService.ps1 -Mode Interactive

powershell.exe -ExecutionPolicy Bypass -File .\KSeFService.ps1 -Mode Batch

On the first run, the script will ask for:

• clientId
• login
• password
• api_env (TEST / PROD / DEMO)
• input directory
• output directory
• validate_xsd option
• waitFinal option

The configuration will be saved in the Windows registry under the key:

HKCU\Software\KSeFServicePS

Interactive mode:

• searches for XML files in the input directory,
• sends each file separately,
• saves JSON responses,
• saves UPO if returned by the API,
• archives input files to archive\sent or archive\error.

Batch mode:

• searches for ZIP and XML files in the input directory,
• automatically compresses XML files into ZIP,
• sends packages to the batch endpoint,
• saves JSON responses,
• optionally saves UPO for documents returned by the API,
• archives input files to archive\sent or archive\error.

Interactive mode:

powershell.exe -ExecutionPolicy Bypass -File .\KSeFService.ps1 -Mode Interactive

Batch mode:

powershell.exe -ExecutionPolicy Bypass -File .\KSeFService.ps1 -Mode Batch

Batch mode in DEMO environment:

powershell.exe -ExecutionPolicy Bypass -File .\KSeFService.ps1 -Mode Batch -EnvOverride DEMO

Reconfiguration:

powershell.exe -ExecutionPolicy Bypass -File .\KSeFService.ps1 -Reconfigure

• The script requires PowerShell 5.1 or newer.
• Running PowerShell as administrator may be required to install scheduled tasks.
• The user password is stored in the registry in encrypted form for the current Windows user.
• The DEMO, TEST, or PROD environment can be set during configuration or once with the -EnvOverride parameter.

First, grant execute permission to the file:

chmod +x KSeFService.sh

Then run the script:

./KSeFService.sh --mode interactive

On the first run, the script will ask for:

• clientId
• login
• password
• api_env (TEST / PROD / DEMO)
• input directory
• output directory
• validate_xsd for batch mode
• wait for batch mode

The configuration is saved in the file:

~/.config/ksefservice/config.env

The password can be stored in libsecret or in the configuration file as a fallback. The configuration file has 600 permissions.

Mode interactive:

• searches for all *.xml files in the input directory,
• sends each file separately to the interactive endpoint,
• saves the JSON response log,
• saves UPO if the API returns upo_xml,
• archives the file to archive/sent or archive/error.

Mode batch:

• searches for *.zip and *.xml files,
• automatically compresses XML files into ZIP,
• sends packages to the batch endpoint,
• passes wait and validate_xsd from configuration,
• saves the JSON log,
• saves UPO for documents returned by the API, if available,
• archives the source file to archive/sent or archive/error.

Interactive mode:

./KSeFService.sh --mode interactive

Batch mode:

./KSeFService.sh --mode batch

One-time DEMO environment override:

./KSeFService.sh --mode batch --env DEMO

Reconfiguration:

./KSeFService.sh --reconfigure

Place files to be sent in the input directory:

• *.xml for interactive,
• *.zip or *.xml for batch.

The script saves the following in the output directory:

• API response logs,
• UPO files,
• .error.txt error files.

Input file archiving works to the following directories:

OUTPUT/archive/sent
OUTPUT/archive/error

Available environments:

• TEST
• PROD
• DEMO

You can set the environment during configuration or one time with:

--env TEST
--env PROD
--env DEMO

The script can add an automatic task to crontab.

Install a task for batch mode:

./KSeFService.sh --mode batch --install-task

Install a task for interactive mode:

./KSeFService.sh --mode interactive --install-task

Remove a task:

./KSeFService.sh --mode batch --uninstall-task

Example output files:

• interactive_name_20260319_210000.json
• batch_name_20260319_210000.json
• interactive_name_20260319_210000.error.txt
• batch_name_20260319_210000.error.txt
• UPO_name_20260319_210000.xml
• UPO_batch_name_1_20260319_210000.xml

Thanks to archiving, input files are moved after processing and are not sent again on the next run.

• The script is intended for Linux Debian.
• A working cron is required for proper automation.
• If you do not have secret-tool, the password will be stored in the configuration file as a fallback.
• batch mode automatically compresses XML into ZIP.
• You can set the TEST, PROD, or DEMO environment in the configuration or one time with the --env parameter.