Open source · Oficjalny SDK Ministerstwa Finansów

KSeF podłączony w 5 minut.
Faktury robią się same.

KSeF Gateway to gotowa usługa do rządowego systemu e-Faktur. Podłączasz ją raz — do sklepu, systemu księgowego albo automatyzacji n8n — i od tej pory wystawianie oraz odbieranie faktur dzieje się automatycznie. Cała techniczna złożoność KSeF zostaje w środku.

Wypróbuj live demoWdróż na RenderGitHub
Działa w 5 minutBez abonamentu — open sourceDane zostają na Twoim serwerzeGotowe workflow n8n
faktura.sh
Odpowiedź
Formaty, szyfrowanie i sesje KSeF usługa bierze na siebie — Ty widzisz tylko odpowiedź
Live demo · środowisko TEST

Nie wierz na słowo — odpal na naszej żywej instancji

Wybierz, co chcesz zrobić w KSeF. Dane poniżej są przykładowe (środowisko testowe, nie prawdziwe faktury) — u siebie wpiszesz własne. Przeklikaj kolejne kroki i przekonaj się, że cała obsługa KSeF sprowadza się do kilku linijek.

Wskazujesz, gdzie stoi Twoja usługa

Poniżej są nasze wartości demo — u siebie wpiszesz własny adres i klucz. Usługa stoi na Twoim serwerze, klucz zna tylko Twój kod. Ten jest jawny naumyślnie, bo to tylko środowisko testowe (nie prawdziwe faktury).

krok 1 · Klucz
# ↓ wartości demo — u siebie wpiszesz swoje
DEMO="https://ksef-demo.techskills.academy"
KEY="0679d36400bfdedcaf1f7d1f5774d0d94ffae5a9f6bc7596cbf24de94d42a8ee"
krok 1 z 4

Klucz powyżej jest publiczny i celowo współdzielony (środowisko TEST, jednorazowy NIP). Pełny opis wREADME.

Problem

Integracja z KSeF na własną rękę to projekt na tygodnie

Rządowe API jest potężne, ale wymaga od Ciebie rzeczy, którymi nie powinieneś musieć się zajmować. Każdy, kto się z nim integruje, przechodzi dokładnie tę samą drogę — i na każdym kroku łatwo o błąd.

Bez KSeF Gateway
  • Tygodnie przedzierania się przez dokumentację i schemat faktury z polami typu P_13_1
  • Samodzielne szyfrowanie każdej faktury, zanim KSeF w ogóle ją przyjmie
  • Sesje, klucze i podpisy — plus pilnowanie, żeby nic nie wygasło w środku nocy
  • Po każdej wysyłce: odpytywanie o status i obsługa błędów, które trzeba umieć czytać
  • A gdy Ministerstwo coś zmieni — cała zabawa od nowa
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"
  • Ty wysyłasz prosty JSON — resztą zajmuje się usługa
  • Numer KSeF wraca od razu — dowód, że faktura jest w systemie
  • Sesje, szyfrowanie i uwierzytelnianie obsłużone automatycznie
  • Zmiany po stronie KSeF? Aktualizujesz usługę jednym poleceniem
Funkcje

KSeF, którego nie musisz się uczyć

Schemat faktury, szyfrowanie, sesje, statusy błędów — cała ta maszyneria zostaje w środku. Ty wysyłasz proste dane i dostajesz wynik.

Faktura trafia do systemu od razu

Wysyłasz dane faktury zwykłym żądaniem, a wraca urzędowy numer KSeF — dowód, że jest już w rejestrze. Formaty, szyfrowanie, sesje i statusy zostają po stronie usługi.

Piszesz po ludzku, nie po urzędowemu

Sprzedawca, nabywca, pozycje — tyle wystarczy. VAT liczy się sam. Nie musisz znać schematu faktury ani pól typu P_13_1.

PDF gotowy do wysłania klientowi

Jedno żądanie i masz PDF faktury z kodem QR, który każdy może zweryfikować w KSeF. Generowany oficjalną biblioteką Ministerstwa.

Wiesz, gdy ktoś wystawi Ci fakturę

KSeF nie wysyła powiadomień — usługa tak. Cyklicznie sprawdza nowe faktury i gotowa jest do podpięcia pod maila, Slacka albo n8n.

Oficjalne fundamenty, nie zgadywanie

W środku pracuje SDK utrzymywane przez Ministerstwo Finansów. Gdy KSeF się zmienia, zmiany przychodzą oficjalnym kanałem — nie odwrotną inżynierią.

Niczego Ci nie zabraknie

Poza prostymi operacjami masz dostęp do pełnego API KSeF — ponad 60 operacji, od wysyłki wsadowej po zarządzanie uprawnieniami. Na zapas.

Postawisz tam, gdzie Ci wygodnie

Własny serwer, darmowy hosting w chmurze, AWS albo Azure — gotowe konfiguracje na każdą opcję. Bez uzależnienia od jednego dostawcy.

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. Usługa robi to za Ciebie: sama znajduje nowe 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"
  • Szukasz faktur po dacie — bez znajomości numeru KSeF
  • PDF pobierasz dokładnie tak samo, jak przy fakturach wysłanych
  • Przy każdym sprawdzeniu dostajesz tylko to, co naprawdę nowe
  • Podłącz pod n8n i miej powiadomienia mailem lub na Slacku

Działa, kiedy śpisz

Gotowy workflow n8n co 20 minut pyta usługę o nowe faktury i wysyła każdą na Twój adres — z PDF-em w załączniku. Zero sprawdzania ręcznie.

Szybki start

Gotowy w trzech krokach

Od zera do działającej integracji z KSeF w mniej niż pięć minut.

01

Uruchom usługę

Jedno polecenie na dowolnym komputerze z Dockerem — niczego więcej nie instalujesz. Wolisz bez terminala? Kliknij „Wdróż na Render" — usługa stawia się sama w chmurze.

docker compose up --build # API gotowe na http://localhost:8080
02

Zdobądź certyfikat KSeF

Do testów: jedno polecenie i masz gotowy certyfikat na środowisku testowym KSeF. Na produkcji: logujesz się Profilem Zaufanym (masz go z bankowości, za darmo) na ap.ksef.mf.gov.pl i wyklikujesz certyfikat w kilka chwil — bez podpisu kwalifikowanego.

docker compose --profile tools run \ --rm cert-generator # zapisuje certyfikat, klucz i NIP do ./output
03

Wyślij pierwszą fakturę

Dane sprzedawcy, nabywcy i pozycje — w odpowiedzi dostajesz numer KSeF. Twoja pierwsza faktura właśnie jest w systemie.

curl -X POST http://localhost:8080/ksef/invoice \ -d '{"sprzedawca":{...},"nabywca":{...},"pozycje":[...]}' # → {"numerKSeF":"1234567890-20260326-..."}
Produkcja, nie tylko test

KSeF przestał być opcjonalny

KSeF staje się w Polsce obowiązkowy — wchodzi etapami i obejmuje zarówno wystawianie, jak i odbieranie faktur. Zamiast wdrażać integrację na ostatnią chwilę, lepiej mieć ją gotową wcześniej. Przejście z testu na produkcję to kilka kliknięć w rządowym portalu, a certyfikat wygenerujesz Profilem Zaufanym za darmo.

Jednoosobowa działalność (JDG)
  • Potrzebujesz tylko Profilu Zaufanego — tego samego, którym logujesz się do banku czy mObywatela
  • Certyfikat KSeF wyklikujesz w rządowej aplikacji w kilka minut — bez wniosków papierowych i bez opłat
  • Wskazujesz certyfikat w konfiguracji i gotowe — od tej chwili wystawiasz prawdziwe faktury
Zero kodu. Zero opłat za podpis kwalifikowany.
Spółka (sp. z o.o., SA, fundacja)
  • Dochodzi jedna jednorazowa formalność: wskazanie osoby upoważnionej do KSeF w firmie
  • Upoważniona osoba (właściciel, członek zarządu) przechodzi potem tę samą prostą ścieżkę co JDG
  • Aktualne szczegóły krok po kroku znajdziesz w dokumentacji — prowadzi za rękę
Formalność jednorazowa — nie blokuje reszty zespołu.

Chcesz zobaczyć każdy krok?

Uwierzytelnianie w produkcji opiera się na certyfikacie KSeF. Pełny przewodnik po certyfikatach, uprawnieniach i konfiguracji multi-NIP — znajdziesz w dokumentacji.

Pełna instrukcja krok po kroku
Biura rachunkowe, agencje, grupy kapitałowe

Jedna firma — za darmo, zawsze.Więcej — jedna opłata, na zawsze.

Obsługujesz faktury dla więcej niż jednego NIP-u (klienci biura rachunkowego, spółki w grupie)? Jedna usługa, dowolna liczba firm — każda ze swoim certyfikatem.

1 NIP
Za darmo

Bez limitu czasowego, bez karty kredytowej — pełna moc usługi dla jednej firmy.

To domyślny tryb: uruchamiasz u siebie i od razu wystawiasz faktury. Bez kont, bez haczyków.

Wdróż na RenderJak to wdrożyć
Nielimitowane NIP-y
Jednorazowa opłata

Jedna płatność, licencja bezterminowa na tej instalacji. Weryfikacja w pełni offline — klucz licencji nigdy nie opuszcza Twojego serwera. Aktualna cena poniżej.

albo zobacz stronę produktu bezpośrednio →

Jak to skonfigurować?

Plik contexts.json, certyfikat per firma, wiele certyfikatów na Render (Secret Files) — pełna instrukcja w dokumentacji.

Tryb multi-NIP w dokumentacji
Wdrożenie

Wdróż wszędzie

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

Docker Compose

Lokalnie / VPS

Dwa polecenia i usługa 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

Postaw jedną komendą — na Mikrusie lub dowolnym VPS

Klucz API i pozostałe sekrety generują się same. Nie masz serwera?Mikrusod ~5 zł/mies. w zupełności wystarcza.

curl -fsSL stackpilot.techskills.academy/ksef-gateway | bash
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
Zobacz kod źródłowy na GitHub

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://twoj-serwer/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 — wszystkie wpisujesz do jednego pliku konfiguracyjnego, każda ze swoim certyfikatem. Usługa sama rozpoznaje po fakturze, w imieniu której firmy działa.

Zacznij dziś

KSeF odhaczony.Dziś, nie za miesiąc.

Open source, na Twoim serwerze, bez abonamentu i bez uzależnienia od dostawcy. Jedno kliknięcie w chmurze albo dwa polecenia u siebie — dokumentacja prowadzi krok po kroku.

Wdróż na RenderDaj 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.

Nie jestem programistą — czy sobie poradzę?

Tak, jeśli nie boisz się skopiować kilku poleceń. Gotowe workflow n8n obsługują całość bez pisania kodu, wdrożenie na Render to jedno kliknięcie, a publiczne demo możesz przetestować od razu, bez instalowania czegokolwiek. Instrukcje prowadzą krok po kroku.

Czy muszę mieć podpis kwalifikowany?

Nie. Do wygenerowania certyfikatu KSeF wystarczy Profil Zaufany — darmowy, masz go zwykle z bankowości. Logujesz się na ap.ksef.mf.gov.pl i wyklikujesz certyfikat w kilka chwil. Spółki dodatkowo składają jednorazowo formularz ZAW-FA w urzędzie skarbowym (chyba że mają pieczęć kwalifikowaną).

Gdzie trzyma się mój certyfikat KSeF? Czy to bezpieczne?

Wyłącznie na Twoim serwerze. Gateway nie ma bazy danych ani zewnętrznego serwisu pośredniczącego — certyfikat i klucz nigdzie nie wypływają poza oficjalne API KSeF, do którego usługa się nimi uwierzytelnia. Klucz może leżeć zaszyfrowany na dysku i jest odszyfrowywany dopiero w pamięci; nigdy nie trafia do repozytorium ani do obrazu Dockera.

Czy hostowanie w chmurze (np. na Render) jest bezpieczne, skoro trafia tam mój certyfikat?

Tak, z jednym zastrzeżeniem, które warto rozumieć. Każdy host — chmura czy własny VPS — technicznie ma dostęp do sekretów usługi w czasie działania, bo dostawca kontroluje warstwę pod spodem (hypervisor). Własny serwer tego nie eliminuje — zmienia tylko, komu ufasz, a zatłoczona maszyna z wieloma usługami bywa mniej bezpieczna niż izolowana instancja u reputowanego dostawcy. Realnie chroni Cię nie to, gdzie leży certyfikat, tylko mocny X-Api-Key, ograniczenie kto może wołać usługę (allowlista IP) oraz to, że certyfikat KSeF w każdej chwili wygenerujesz od nowa, a stary przestaje działać.

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.

Jak dołożyć dodatkową warstwę zabezpieczeń poza kluczem API?

Ustaw allowlistę IP przed usługą. Konkretnie: przepuść domenę przez Cloudflare (rekord DNS z włączonym proxy), sprawdź publiczny egress IP swojego callera — osobno IPv4 i IPv6 — i dodaj w Cloudflare regułę WAF, która blokuje wszystko poza tymi adresami. Wtedy nawet gdyby klucz API wyciekł, użyje go wyłącznie zaufany adres. Działa to najlepiej, gdy caller ma stałe IP; adresy domowe/mobilne bywają zmienne, a wewnętrzne adresy VPN (np. Tailscale) nie są widoczne dla publicznej usługi — w takim wypadku kieruj ruch przez stały host i to jego IP allowlistuj. Pełna instrukcja krok po kroku — łącznie z domknięciem obejścia przez publiczny origin — jest w README projektu.

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 certyfikat testowy na produkcyjny w konfiguracji i restartujesz usługę. Wszystko inne — adresy, format danych, podpięte automatyzacje — zostaje bez zmian.

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: każda firma ze swoim certyfikatem w jednym pliku konfiguracyjnym, a usługa sama rozpoznaje, w imieniu której firmy działa — po NIP sprzedawcy z faktury albo jawnym nagłówku.