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.

Wdróż na Render GitHub
.NET 9 w Dockerze Bez lokalnego .NET 81 testów przechodzi Darmowy tier na Render
faktura.sh
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.

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.

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.

Pełna instrukcja krok po kroku
Wdrożenie

Wdróż wszędzie

Docker, serverless czy zarządzana chmura — wszystkie konfiguracje są w repozytorium.

Docker Compose

Lokalnie / VPS

Dwa polecenia i brama działa. Bez konta w chmurze. Działa na każdym VPS.

docker compose up --build
Dokumentacja

Render

Polecane

Wdrożenie jednym kliknięciem. Ustaw trzy zmienne środowiskowe. Darmowy tier. Oba kontenery (API + PDF) wdrażają się automatycznie.

# Kliknij przycisk poniżej
Wdróż na Render

AWS Lambda

Serverless

Deploy jako Lambda z Function URL. SAM CLI obsługuje build. Bliskie zeru koszty przy małym ruchu.

sam deploy --guided
Konfiguracja SAM

Azure Container Apps

Cloud

Zarządzane kontenery odzwierciedlające Docker Compose. Szablon Bicep w zestawie, zero zmian w kodzie.

az deployment group create \ --template-file deploy/azure/main.bicep
Szablon 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ł Webhook Transformacja POST /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
Zobacz workflow n8n

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.

platnosc_sukces.js
// Po udanej płatności
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.

Wdróż na Render Daj gwiazdkę na GitHub
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.