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 JSON ze sprzedawcą, nabywcą i pozycjami — otrzymujesz numer KSeF. Bez XML FA(3), bez szyfrowania AES-256, bez 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.

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.

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: użyj podpisu kwalifikowanego w portalu KSeF.

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-..."}
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

Użyj n8n do przetłumaczenia webhooka platformy na wywołanie faktury KSeF. Trzy węzły: Webhook → Transformacja → HTTP Request.

Węzeł Webhook Transformacja POST /ksef/invoice
Sellf → KSeF (workflow w zestawie)
WooCommerce → KSeF (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