Krajowy System e-Faktur (KSeF) to kluczowy element cyfrowej transformacji polskiego systemu podatkowego, wymagający od przedsiębiorców i programistów integracji z centralnym repozytorium e-faktur. W tym artykule omawiamy implementację KSeF w PHP – najpopularniejszym języku po stronie serwerowej w Polsce – wraz z przykładami dla frameworków Laravel i Symfony, natywnego PHP oraz gotowych bibliotek.
Czym jest KSeF i dlaczego integracja w PHP jest kluczowa?
KSeF, zarządzany przez Ministerstwo Finansów, przetwarza e-faktury w formacie XML (struktura logiczna FA(3)), umożliwiając ich generowanie, wysyłanie, pobieranie i wyszukiwanie poprzez API (wersja 2.0). Od 2026 roku pełna obligo dla większości firm oznacza, że systemy księgowe, ERP i SaaS muszą wspierać KSeF, by uniknąć kar.
PHP dominuje w polskim webdevelopmencie dzięki prostocie, bibliotekom HTTP (Guzzle) i XML (DOMDocument), oraz narzędziom jak OpenSSL do podpisywania. Integracja jest możliwa w każdym języku obsługującym HTTP i XML, ale PHP wyróżnia się dostępnością gotowych bibliotek REST API, które przyspieszają rozwój.
Oficjalna dokumentacja i SDK Ministerstwa Finansów
Ministerstwo Finansów publikuje dokumentację API KSeF 2.0 z bibliotekami SDK dla Java i .NET, podręcznikami i przykładami endpointów. Brak natywnego SDK dla PHP nie jest przeszkodą – deweloperzy korzystają z proxy, REST API pośredników lub własnych implementacji, co czyni PHP elastycznym i praktycznym wyborem.
Popularne biblioteki PHP do integracji z KSeF
Na rynku dostępne są biblioteki, które upraszczają generowanie e-faktur, autoryzację, wysyłanie i pobieranie. Oto najważniejsze rozwiązania:
- Biblioteka NIP24.pl – integracja z ich REST API KSeF (generowanie, wysyłanie, odbieranie faktur); pobierz z https://nip24.pl/download/ksef-php/, paczka zawiera
example.phpz formularzem testowym wszystkich operacji; - KSeF API (ksefapi.pl) – wersja 2.0.2 – zaktualizowana biblioteka kliencka do KSeF 2.0; dostępna na GitHub (https://github.com/ksefapi/ksefapi-php-client) i Packagist (
composer require ksefapi/client); obsługuje wyszukiwanie i wizualizację e-faktur; - Inne rozwiązania – biblioteki dla PHP/Java/C# z bezpośrednim REST API oraz komercyjne moduły do systemów ERP/SaaS.
Poniżej porównanie funkcji i sposobów instalacji:
| Biblioteka | Wersja | Kluczowe funkcje | Instalacja | Źródło |
|---|---|---|---|---|
| NIP24 KSeF PHP | Aktualna | Generowanie, wysyłka, odbiór faktur | Pobierz ZIP | https://nip24.pl/download/ksef-php/ |
| KSeF API PHP | 2.0.2 | Pełna integracja KSeF 2.0, wyszukiwanie | Composer / GitHub | https://github.com/ksefapi/ksefapi-php-client |
| VIES API KSeF | Bieżąca | REST API + biblioteka PHP | Strona projektu | — |
Te narzędzia znacząco redukują boilerplate, przejmując autoryzację (tokeny, certyfikaty) oraz walidację XML.
Implementacja krok po kroku w natywnym PHP
Zacznij od instalacji i konfiguracji podstawowych zależności:
- Guzzle – klient HTTP do komunikacji z API;
- DOMDocument – przetwarzanie i walidacja XML (FA(3));
- OpenSSL – podpisy i obsługa certyfikatów.
Przykładowy skrypt do wysyłania e-faktury przez REST API pośrednika (np. NIP24):
'1234567890',
'faktura_xml' => file_get_contents('faktura.xml'), // walidowany XML FA(3)
];
try {
$response = $client->post('https://api.nip24.pl/ksef/wyslij', [
'headers' => ['Authorization' => 'Bearer ' . $apiKey],
'json' => $data
]);
$body = json_decode((string)$response->getBody(), true);
echo 'Faktura wysłana. ID: ' . ($body['idKsef'] ?? 'brak');
} catch (\Throwable $e) {
echo 'Błąd: ' . $e->getMessage();
}
W integracji bezpośredniej z KSeF dodaj autoryzację sesyjną poprzez endpoint /sesja-1 i obsłuż token sesji w kolejnych wywołaniach.
Automatyzacja pobierania faktur: skonfiguruj zadanie cron (bot/worker), które cyklicznie pobiera faktury po NIP i zakresie dat – to oszczędza godziny ręcznej pracy i minimalizuje błędy.
Integracja z frameworkami – Laravel i Symfony
Laravel (Guzzle + dedykowany serwis)
Dodaj zależność w composer.json i utwórz serwis App\Services\KSeFService.php:
client = new Client();
$this->apiKey = config('ksef.api_key');
}
public function wyslijFakture(string $xml) {
return $this->client->post(config('ksef.endpoint') . '/wyslij', [
'headers' => ['Authorization' => 'Bearer ' . $this->apiKey],
'json' => ['faktura_xml' => $xml],
'timeout' => 30
]);
}
}
Skonfiguruj config/ksef.php i użyj w kontrolerze ($ksef = app(\App\Services\KSeFService::class); $ksef->wyslijFakture($xml);). Do masowego przetwarzania użyj kolejek Laravel (Jobs/Queues) i retry/backoff.
Symfony (HttpClient + Dependency Injection)
Zainstaluj symfony/http-client i skonfiguruj usługę w src/Service/KSeFService.php:
client = $client;
}
public function pobierzFaktury(string $nip, string $dataOd): array {
$response = $this->client->request('GET', '/ksef/pobierz', {
'auth_bearer' => $_ENV['KSEF_TOKEN'],
'query' => ['nip' => $nip, 'dataOd' => $dataOd],
});
return $response->toArray(false);
}
}
Zarejestruj w services.yaml, a do wsadowego pobierania użyj komend konsolowych (Symfony Console) i harmonogramu (np. cron). Symfony wyróżnia się silnym typowaniem, DI i testami jednostkowymi/funkcjonalnymi.
Autoryzacja i bezpieczeństwo w KSeF w PHP
KSeF wymaga autoryzacji z użyciem certyfikatu kwalifikowanego lub Profilu Zaufanego do utworzenia sesji (/sesja-1). Przykładowa idea podpisu (XAdES-BES realizuj przez dedykowane biblioteki; poniżej uproszczenie):
load('faktura.xml');
// Uwaga: do XAdES użyj biblioteki obsługującej XMLDSig/XAdES.
// Poniższe to koncepcja, niepełna implementacja:
$canonical = $xmlDoc->C14N();
// $pkey = openssl_pkey_get_private('file://sciezka/do/klucza.pem', 'HASLO');
// openssl_sign($canonical, $signature, $pkey, OPENSSL_ALGO_SHA256);
Przechowuj tokeny i klucze w bezpiecznych magazynach (np. Redis/Vault), rotuj co 24 h i stosuj zasadę najmniejszych uprawnień. Wiele bibliotek (np. ksefapi) automatyzuje podpisy i walidację.
Najczęstsze błędy i dobre praktyki
- Błędy XML – zawsze waliduj strukturę FA(3) against XSD z MF przed wysyłką;
- Limity API – respektuj limity (np. 1000 żądań/godz.), stosuj kolejki i backoff;
- Testy – używaj środowiska testowego KSeF (test.ksef.mf.gov.pl) do weryfikacji scenariuszy;
- Skalowalność – uruchamiaj workerów w kontenerach (np. Docker) i poziomo skaluj przetwarzanie;
- Monitoring – loguj (Monolog), dodaj alerty na błędy 429/5xx i śledź metryki opóźnień.
Dla software house’ów: konsultacje i gotowe proxy znacząco przyspieszają czas wdrożenia.
Przyszłość i komercyjne rozwiązania
W 2026 KSeF 2.0 staje się rynkowym standardem, a biblioteki PHP dynamicznie dojrzewają (równolegle rozwijane są rozwiązania dla Java/.NET). Komercyjne moduły PHP dla ERP/SaaS oferują pełne wsparcie procesów i skracają czas wdrożenia.
Uwaga: zawsze sprawdzaj bieżącą dokumentację i komunikaty Ministerstwa Finansów przed wdrożeniem produkcyjnym.
