Jedno wywołanie HTTP
Wyślij JSON, otrzymaj numer KSeF. Brama obsługuje XML FA(3), szyfrowanie AES-256, zarządzanie sesjami i odpytywanie statusu.
Open Source · AGPL-3.0 · Oficjalny SDK MF
Jedno wywołanie HTTP.
Jeden numer KSeF.
KSeF Gateway opakowuje oficjalny SDK e-Faktur Ministerstwa Finansów. Wysyłasz i odbierasz faktury jednym wywołaniem HTTP — bez znajomości numeru KSeF, XML FA(3), szyfrowania AES-256 czy zarządzania sesjami.
.NET 9 w DockerzeBez lokalnego .NET81 testów przechodziDarmowy tier na Render
Odpowiedź
Brama obsługuje XML FA(3) · szyfrowanie AES-256 · sesje KSeF · auto-refresh
Problem
Bezpośrednia integracja z KSeF jest bolesna
Oficjalne API KSeF jest potężne, ale złożone. Każda integracja wymaga tego samego kotłowni — i łatwo ją zepsuć.
Bez KSeF Gateway
- Budowanie XML FA(3) od zera — złożony schemat, polskie nazwy pól jak P_13_1
- Szyfrowanie faktury kluczem RSA KSeF przy użyciu AES-256-CBC
- Zarządzanie sesjami uwierzytelniającymi — challenge, podpis XAdES, JWT
- Otwarcie sesji → wysłanie zaszyfrowanej faktury → odpytywanie statusu
- Parsowanie kodów odpowiedzi KSeF i obsługa ponownych prób
- Auto-odświeżanie tokenów przed wygaśnięciem
- Zamknięcie sesji po każdej partii
Twoja aplikacja → XML → szyfruj → sesja → wyślij → odpytuj → parsuj → zamknij → błędy...
Z KSeF Gateway
# Wyślij fakturę
curl -X POST /ksef/invoice \
-d '{"sprzedawca":{...}, "nabywca":{...}, "pozycje":[...]}'
# Odpowiedź
"numerKSeF": "1234567890-20260326-..."
"status": "zaakceptowano"
- Brama automatycznie buduje XML FA(3)
- Szyfrowanie AES-256 przezroczyste dla Ciebie
- Zarządza sesjami, tokenami i auto-odświeżaniem
- Zwraca numer KSeF — nic więcej nie potrzebujesz
Funkcje
Wszystko obsłużone za Ciebie
KSeF Gateway to cienka, przezroczysta warstwa — cała złożoność KSeF jest w środku, a Twój kod widzi tylko HTTP.
Przyjazny JSON
{sprzedawca, nabywca, pozycje} — z automatycznym obliczaniem VAT. Bez znajomości schematu FA(3) i polskich nazw pól.
PDF z kodem QR
Pobierz zweryfikowany PDF faktury po numerze KSeF. QR zawiera hash SHA-256 do weryfikacji. Oficjalna biblioteka CIRFMF.
Odbieraj faktury bez znajomości numeru
Szukaj po dacie i roli nabywcy, nie po numerze KSeF. Endpoint do pollingu z checkpointem — podłącz pod cron i wiedz, gdy coś nowego wpadnie.
Oficjalny SDK MF w środku
Opakowanie CIRFMF/ksef-client-csharp — SDK utrzymywanego przez Ministerstwo Finansów. Nie reverse-engineering strony trzeciej.
60+ endpointów auto-odkrywanych
Wszystkie metody IKSeFClient wystawione jako REST via refleksja .NET. Aktualizacje SDK propagują automatycznie przy przebudowie.
Wdróż wszędzie
Docker Compose, Render jednym kliknięciem, AWS Lambda (SAM), Azure Container Apps (Bicep). Wszystkie konfiguracje w repo.
Odbieranie faktur
KSeF nie powie Ci, że dostałeś fakturę
Kontrahenci wystawiają faktury w KSeF i nie zawsze wysyłają je mailem. Bez powiadomień w samym systemie musisz sam sprawdzać, czy coś wpadło — albo znać numer KSeF z góry. Gateway odwraca ten problem: przeszukuje faktury po dacie i roli nabywcy, bez znajomości numeru.
Bez KSeF Gateway
- Ręczne logowanie się do KSeF codziennie, żeby sprawdzić, czy coś przyszło
- Zero powiadomień e-mail czy webhook przy nowej fakturze od kontrahenta
- Żeby cokolwiek pobrać, trzeba już znać numer KSeF
- Ręczne przeszukiwanie interfejsu MF po dacie i kontrahencie
Loguj się → szukaj ręcznie → miej nadzieję, że niczego nie przegapiłeś...
Z KSeF Gateway
# Sprawdź, co nowego przyszło od ostatniego razu
curl "/ksef/invoices/received/new?since=..."
# Odpowiedź
"faktury": [{ "sprzedawca": "Dostawca sp. z o.o." }]
"kolejnyCheckpoint": "2026-07-01T07:00:00Z"
- Szukaj faktur po dacie i roli nabywcy — bez znajomości numeru KSeF
- Pobierz PDF tym samym endpointem, co dla faktur wysłanych
- Checkpoint do pollingu — dostajesz tylko to, co naprawdę nowe
- Podłącz pod cron / n8n i miej powiadomienia mailem lub na Slacka
Szybki start
Gotowy w trzech krokach
Od zera do działającej integracji z KSeF w mniej niż pięć minut.
01
Wdróż bramę
Jedno polecenie — wszystko buduje się w Dockerze. Bez lokalnego .NET. Lub kliknij „Wdróż na Render" dla natychmiastowego startu w chmurze.
docker compose up --build
# API gotowe na http://localhost:8080
02
Wygeneruj token KSeF
Jedno polecenie tworzy token testowy (certyfikat self-signed, losowy NIP). Na produkcji: zaloguj się Profilem Zaufanym (JDG, za darmo) lub złóż ZAW-FA (spółki) — bez podpisu kwalifikowanego.
docker compose --profile tools run \
--rm token-generator
# wyświetla KSEF_TOKEN + KSEF_NIP
03
Wyślij pierwszą fakturę
POST JSON ze sprzedawcą, nabywcą i pozycjami. Odbierz numer KSeF. Gotowe.
curl -X POST http://localhost:8080/ksef/invoice \
-d '{"sprzedawca":{...},"nabywca":{...},"pozycje":[...]}'
# → {"numerKSeF":"1234567890-20260326-..."}
Produkcja, nie tylko test
KSeF przestał być opcjonalny
KSeF jest już obowiązkowy dla większości firm w Polsce — w obie strony: musisz umieć wystawiać faktury i je odbierać, niezależnie od wielkości firmy. Przejście z tokenu testowego na produkcyjny zajmuje kilka minut i w większości przypadków nic nie kosztuje.
Jednoosobowa działalność (JDG)
- Zaloguj się na ap.ksef.mf.gov.pl Profilem Zaufanym — masz go za darmo z bankowości, żadnych dodatkowych zgłoszeń
- Zakładka Tokeny → Generuj token → zaznacz „Wystawianie faktur" + „Przeglądanie faktur"
- Wklej token do .env, ustaw KSEF_ENV=PRODUCTION, zrestartuj bramę
Zero kodu. Zero opłat za podpis kwalifikowany.
Spółka (sp. z o.o., SA, fundacja)
- Złóż jednorazowo formularz ZAW-FA w urzędzie skarbowym — chyba że firma ma pieczęć kwalifikowaną przypisaną do NIP
- Osoba upoważniona (właściciel, zarząd) loguje się i generuje token — te same kroki co JDG
- Reszta identyczna: token do .env, KSEF_ENV=PRODUCTION, restart
Formalność jednorazowa — nie blokuje reszty zespołu.
Chcesz zobaczyć każdy krok?
Token czy certyfikat KSeF — oba wspierane. Pełny przewodnik po obu ścieżkach, uprawnieniach i konfiguracji multi-NIP — w dokumentacji.
Wdrożenie
Wdróż wszędzie
Docker, serverless czy zarządzana chmura — wszystkie konfiguracje są w repozytorium.
Docker Compose
Lokalnie / VPSDwa polecenia i brama działa. Bez konta w chmurze. Działa na każdym VPS.
docker compose up --build
Render
PolecaneWdrożenie jednym kliknięciem. Ustaw trzy zmienne środowiskowe. Darmowy tier. Oba kontenery (API + PDF) wdrażają się automatycznie.
# Kliknij przycisk poniżej
AWS Lambda
ServerlessDeploy jako Lambda z Function URL. SAM CLI obsługuje build. Bliskie zeru koszty przy małym ruchu.
sam deploy --guided
Azure Container Apps
CloudZarządzane kontenery odzwierciedlające Docker Compose. Szablon Bicep w zestawie, zero zmian w kodzie.
az deployment group create \
--template-file deploy/azure/main.bicep
Używasz StackPilot?
Wdróż na dowolny VPS jednym poleceniem z terminala.
./local/deploy.sh ksef-gateway --ssh=vps
Integracje
Działa z każdą platformą
KSeF Gateway to samodzielna usługa HTTP. Bez pluginów, bez SDK, bez zmian w Twojej platformie — tylko wywołanie HTTP.
n8n (middleware bez kodu)
Zalecane — zero zmian w Twojej platformie
Gotowe workflow do wysyłania i odbierania faktur — zero kodu po Twojej stronie. Wysyłka: webhook platformy → transformacja → POST /ksef/invoice. Odbiór: cykliczny poll → pobranie PDF.
Węzeł WebhookTransformacjaPOST /ksef/invoice
Sellf → KSeF (workflow w zestawie)
WooCommerce → KSeF (workflow w zestawie)
Odbieranie faktur + PDF co 20 min (workflow w zestawie)
Każda platforma obsługująca webhooks
Bezpośrednia integracja HTTP
Dowolny język, dowolny framework
Dodaj jedno wywołanie HTTP w obsłudze udanej płatności. Działa z PHP, Python, Node.js, Go — wszystkim co potrafi wykonać request HTTP.
// Po udanej płatności
await fetch("https://twoja-brama/ksef/invoice", {
method: "POST",
body: JSON.stringify({ sprzedawca, nabywca, pozycje }),
});
await fetch("https://twoja-brama/ksef/invoice", {
method: "POST",
body: JSON.stringify({ sprzedawca, nabywca, pozycje }),
});
Hooki płatności e-commerce
Integracja z systemami ERP
Automatyzacja oprogramowania księgowego
Obsługa wielu NIP-ów
Obsługuj faktury dla wielu firm z jednej instancji bramy. Zamontuj contexts.json z tokenami per NIP. Auto-routing po NIP sprzedawcy lub nagłówku X-KSeF-NIP.
Zacznij dziś
Jedno wywołanie HTTP.
Twój numer KSeF.
Open source, self-hosted, zero vendor lock-in. Docker Compose lub jednym kliknięciem na Render. Dokumentacja i kolekcja Bruno w zestawie.
Licencja AGPL-3.0·Oficjalny SDK CIRFMF·Bez vendor lock-in·Pełny kod źródłowy na GitHub
Pytania
Najczęstsze pytania
To, co zwykle pada w pierwszej rozmowie o wdrożeniu.
Czy muszę mieć podpis kwalifikowany?
Nie. Do wygenerowania tokenu produkcyjnego wystarczy Profil Zaufany — darmowy, masz go zwykle z bankowości. Spółki dodatkowo składają jednorazowo formularz ZAW-FA w urzędzie skarbowym (chyba że mają pieczęć kwalifikowaną).
Gdzie trzyma się mój token KSeF? Czy to bezpieczne?
Wyłącznie na Twoim serwerze, w zmiennej środowiskowej. Gateway nie ma bazy danych ani zewnętrznego serwisu pośredniczącego — token nigdzie nie wypływa poza oficjalne API KSeF, do którego się nim uwierzytelnia.
Czy ktokolwiek, kto znajdzie mój URL, może wysłać fakturę w moim imieniu?
Nie — każde zapytanie (poza /health) wymaga nagłówka X-Api-Key z Twoim własnym kluczem gatewaya. Bez niego dostajesz 401, a jeśli klucz w ogóle nie jest ustawiony, gateway odrzuca wszystko (fail-closed), zamiast po cichu zostać otwarty.
Ile to kosztuje?
Sam gateway jest open source (AGPL-3.0) i darmowy. Płacisz jedynie za hosting — własny serwer, darmowy tier Render albo pay-as-you-go Lambda/Azure. Samo KSeF jest bezpłatne.
Czy przejście z testu na produkcję wymaga zmian w kodzie?
Nie. Podmieniasz KSEF_TOKEN, KSEF_NIP i ustawiasz KSEF_ENV=PRODUCTION w konfiguracji, restartujesz bramę. Endpointy, format JSON i cała reszta integracji zostają identyczne.
Co się stanie, jeśli przekroczę limit zapytań KSeF?
Gateway pilnuje oficjalnych limitów po swojej stronie i odda Ci 429 z nagłówkiem Retry-After, zanim jeszcze uderzy w limit KSeF — nie musisz sam implementować throttlingu.
Obsługuję kilka firm/NIP-ów — da się to zrobić z jednej instancji?
Tak, przez tryb multi-NIP: plik contexts.json z tokenem per firma, auto-routing po nagłówku X-KSeF-NIP albo NIP sprzedawcy z faktury.