Integracja z API KSeF w dowolnym języku – PHP, Node.js, .NET, Java, React, Angular, C++

Jedno z pytań, które najczęściej pada przy wyborze sposobu integracji z KSeF, brzmi: „a czy to zadziała z moim systemem?". Odpowiedź jest prosta — API KSeF Service to zwykły endpoint HTTP przyjmujący dane w formacie multipart/form-data, więc da się go wywołać z dowolnego języka i technologii, które potrafią wysłać żądanie POST. Poniżej pokazujemy, jak wygląda wysyłka faktury FA(3) w praktyce — w kilku najczęściej używanych środowiskach.

Jeden endpoint, wiele języków

Niezależnie od technologii, wysyłka faktury do KSeF Service sprowadza się do jednego wywołania:

POST https://ksefservice.pl/api/v1/invoices/send
Content-Type: multipart/form-data

clientId, login, password, api_env, file (XML FA(3))

Pełną specyfikację, w tym wszystkie dostępne endpointy, znajdziesz w dokumentacji Swagger pod adresem /docs/swagger/. Poniżej — konkretne przykłady użycia.

PHP (cURL)

Klasyczne podejście z CURLFile i curl_setopt_array. Warto zwrócić uwagę, że nagłówka Content-Type nie ustawia się ręcznie — cURL sam dodaje poprawny boundary dla multipart/form-data:

$file = new CURLFile($xmlPath, 'application/xml', basename($xmlPath));
$postFields = [
    'clientId' => $clientId,
    'login'    => $login,
    'password' => $password,
    'api_env'  => $apiEnv, // TEST | DEMO | PROD
    'file'     => $file,
];
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $postFields,
    CURLOPT_RETURNTRANSFER => true,
]);

Node.js (fetch + FormData)

Przykład dla Node.js 18+, wykorzystujący wbudowane fetch i FormData — bez dodatkowych zależności. Po wysyłce skrypt zapisuje pełną odpowiedź, wyodrębnia numer KSeF oraz zapisuje zwrócone UPO do osobnego pliku XML.

const form = new FormData();
form.append("clientId", clientId);
form.append("login", login);
form.append("password", password);
form.append("api_env", "TEST");
form.append("file", fileBlob, "invoice_FA3.xml");

const response = await fetch(
  "https://ksefservice.pl/api/v1/invoices/send",
  { method: "POST", body: form }
);

.NET (ASP.NET Core)

Integracja przez MultipartFormDataContent i HttpClient — typowy wzorzec dla aplikacji w C#/.NET, z osobnym DTO na dane wejściowe i osobnym serwisem odpowiedzialnym za komunikację z API.

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");
form.Add(fileContent, "file", req.File.FileName);

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

Java (HttpClient, Java 11+)

Bez zewnętrznych bibliotek — samodzielnie budowany request multipart/form-data przy użyciu wbudowanego java.net.http.HttpClient. Odpowiedź API zawiera m.in. numer KSeF i status przetworzenia:

{
  "success": true,
  "stage": "ksef_ok",
  "data": {
    "ksefNumber": "5771876968-20251209-0100805B192F-B3",
    "sessionReference": "20251209-SO-178C9DF000-9498D48B5B-BB"
  }
}

React i Angular (formularz w przeglądarce)

Dla aplikacji frontendowych dostępne są gotowe komponenty — formularz z walidacją pliku XML, paskiem postępu wysyłki i obsługą odpowiedzi API, zarówno jako komponent React (fetch + FormData), jak i serwis Angular oparty o HttpClient z obserwowalnym postępem uploadu (reportProgress).

C++ Builder (VCL/FMX)

Dla aplikacji desktopowych pisanych w C++ Builderze dostępne są dwa warianty: natywna integracja przez komponenty Indy (TIdHTTP + TIdMultiPartFormDataStream, z obsługą TLS przez OpenSSL) oraz wariant uruchamiający curl.exe jako podproces i przechwytujący jego wynik — przydatny, gdy wdrożenie pełnego stosu Indy/OpenSSL nie wchodzi w grę.

Gotowe skrypty — bez pisania kodu integracyjnego

Jeśli nie chcesz pisać własnej integracji, dostępne są gotowe skrypty do uruchomienia „z palca":

• PowerShell (KSeFService.ps1) — dla Windows, z trybem interaktywnym (pojedyncze pliki) i wsadowym (automatyczne pakowanie do ZIP), instalacją zadania w Harmonogramie zadań jedną komendą (-InstallTask) oraz bezpiecznym zapisem hasła w rejestrze.
• Bash (KSeFService.sh) — dla Linux Debian, z analogicznymi trybami interactive i batch, automatyzacją przez cron (--install-task) oraz opcjonalnym bezpiecznym przechowywaniem hasła przez secret-tool.

Oba skrypty przy pierwszym uruchomieniu proszą o dane konfiguracyjne (clientId, login, hasło, środowisko, katalogi wejścia/wyjścia), zapisują je lokalnie i od tego momentu działają automatycznie — archiwizując przetworzone pliki i zapisując UPO bez dalszej ingerencji.

Środowiska testowe

Każdy z powyższych przykładów obsługuje parametr api_env ze trzema wartościami: TEST, DEMO i PROD — co pozwala bezpiecznie rozwijać i testować integrację przed przełączeniem jej na środowisko produkcyjne KSeF.

Podsumowanie

Wybór technologii nie jest barierą przy integracji z KSeF Service — endpoint API jest neutralny względem stosu technologicznego, a gotowe przykłady pokrywają większość popularnych języków i frameworków używanych w polskich firmach: od backendu (PHP, Node.js, .NET, Java) przez frontend (React, Angular), po aplikacje desktopowe (C++ Builder) i automatyzację bez kodu (PowerShell, Bash).

Pełne przykłady kodu, gotowe do skopiowania, znajdziesz w dokumentacji API — sekcja przykłady użycia. Masz pytanie o integrację w innej technologii? Skontaktuj się z nami.