Ksefnik to kompletne, otwarte SDK do Krajowego Systemu e-Faktur (KSeF 2.0) — obowiązkowego od 2026-02-01 systemu Ministerstwa Finansów do wystawiania i pobierania faktur elektronicznych w Polsce. Projekt rozwijany przez CodeFormers.it adresuje dwa problemy, które każdy deweloper integrujący się z KSeF musi rozwiązać: (auth flow z challenge + RSA-OAEP, parsowanie FA(2)/FA(3), refresh tokenów, rate limiting) oraz (6-stopniowy pipeline dopasowujący KSeF ↔ MT940/mBank/ING/PKO BP/Santander).
KSeF SDK for TypeScript/Node.js — invoice reconciliation with bank statements (MT940, mBank, ING, PKO, Santander), production KSeF 2.0 HTTP client, MCP server for Claude and Cursor. Open-source, MIT.
ดาว
11
เครื่องมือ
—
อัปไทม์
—
produkcyjny klient HTTP do api.ksef.mf.gov.pl
reconcyliacja faktur z wyciągami bankowymi
Jako jeden z pierwszych SDK-ów do polskiej e-faktury Ksefnik wystawia również Model Context Protocol server — dzięki czemu możesz rozmawiać z KSeF-em z poziomu Claude Desktop, Cursora, Continue albo dowolnego innego klienta MCP. Pobranie faktur kosztowych za marzec, import wyciągu z ING i uruchomienie reconcyliacji sprowadza się do jednego zdania w czacie z AI.
Projekt jest na wczesnym etapie rozwoju — API może się zmieniać między wersjami 0.x. Od 1.0 obowiązuje semver.
Funkcje
Reconciliation Engine
Automatyczne dopasowywanie faktur KSeF do przelewow bankowych w 6 krokach: numer KSeF, dokladne dopasowanie NIP + kwota, numer faktury w tytule przelewu, przyblizone dopasowanie nazwy (fuzzy matching), platnosci czesciowe, dopasowanie bliskosci. Dokumentacja →
Bank Parsers
Import wyciagow z polskich bankow: MT940 (standard), CSV z mBank, ING, PKO BP, Santander. Automatyczna detekcja formatu pliku. Ekstrakcja NIP z tytulow przelewow. Dokumentacja →
HTTP Adapter (@ksefnik/http)
Produkcyjny klient HTTP do KSeF 2.0 (api.ksef.mf.gov.pl). Pelny flow uwierzytelnienia (challenge + RSA-OAEP), pobieranie metadanych faktur, parsowanie FA(2)/FA(3) XML, ekstrakcja kwot brutto. Gotowy do podpiecia pod createKsefnik() przez createHttpAdapter({ nip, token, environment, publicKeyPem }). Szczegoly: packages/http/README.md. Dokumentacja →
KSeF Simulator
Lokalny mock serwer KSeF do testow offline. Deterministyczny, bez polaczenia z Ministerstwem Finansow. Gotowe scenariusze: happy-path, timeout, odrzucenie faktury, wygasniecie sesji. Dokumentacja →
MCP Server
Model Context Protocol server (9 narzedzi) do integracji z Claude i innymi asystentami AI. Reconcyliacja, import wyciagow i zapytania o faktury bezposrednio z poziomu AI. Dokumentacja →
Walidacja faktur
Walidacja faktur przed wyslaniem do KSeF. Reguly biznesowe Ministerstwa Finansow z czytelnymi komunikatami bledow po polsku. Dokumentacja →
Type-Safe SDK
Pelne typy TypeScript wygenerowane z oficjalnych schematow XSD KSeF. Bledy wychwytywane na etapie kompilacji, a nie w runtime.
Instalacja
Wymagania: Node.js 22+, pnpm 9+
npm install @ksefnik/core @ksefnik/http
# lub
pnpm add @ksefnik/core @ksefnik/http
Ksefnik stosuje podejscie SDK-first -- cala logika biznesowa znajduje sie w pakiecie core, a pozostale pakiety (CLI, MCP server) sa cienkimi wrapperami, ktore z niego korzystaja.
ksefnik/
packages/
shared/ @ksefnik/shared Typy Zod, interfejsy, plugin system
core/ @ksefnik/core Reconciliation engine, bank parsers, KSeF adapter
http/ @ksefnik/http Produkcyjny klient HTTP do KSeF API v2
simulator/ @ksefnik/simulator Offline KSeF test harness
mcp/ @ksefnik/mcp MCP server (wrapper na core)
cli/ @ksefnik/cli CLI (Commander.js), standalone binary via bun compile
Pakiet
Opis
@ksefnik/shared
Wspoldzielone typy Zod, interfejsy i plugin system
@ksefnik/core
Glowna logika: reconciliation engine, bank parsers, adapter KSeF
Interfejs wiersza polecen, kompilacja do standalone binary
MCP Server
MCP server udostępnia 9 narzędzi (reconcyliacja, import wyciągów, zapytania o faktury, walidacja, wysyłka, UPO) bezpośrednio z poziomu Claude Desktop, Cursor, Claude Code i innych klientów MCP.
Claude Desktop
Dodaj do claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json na macOS):
Stworz branch z opisowa nazwa (feat/partial-payments, fix/mt940-parser).
Upewnij sie, ze wszystkie testy przechodza (pnpm test).
Dodaj testy dla nowej funkcjonalnosci.
Opisz zmiany w PR -- co, dlaczego i jak przetestowac.
Zapraszamy do zglaszania Issues i Pull Requestow. Projekt jest na wczesnym etapie, wiec kazdego rodzaju wklad jest mile widziany.
Często zadawane pytania
Jak pobrać faktury z KSeF w Node.js albo TypeScript?
Zainstaluj @ksefnik/core i @ksefnik/http, skonfiguruj createHttpAdapter z tokenem KSeF i kluczem publicznym MF, i woła ksef.invoices.fetch({ from, to }). Pełen przykład w sekcji Szybki start. Ksefnik jest w tej chwili jedynym produkcyjnym KSeF SDK dla TypeScript / Node.js z pełnym pokryciem flow uwierzytelnienia KSeF 2.0.
Czy Ksefnik wspiera KSeF 2.0 (obowiązkowe API od 2026-02-01)?
Tak. Pakiet @ksefnik/http rozmawia bezpośrednio z api.ksef.mf.gov.pl/v2, implementuje pełen flow uwierzytelnienia (challenge + RSA-OAEP SHA-256, redeem, refresh) i parsuje faktury w formacie FA(2)/FA(3). Typy są generowane z oficjalnego OpenAPI MF, więc przy każdej zmianie kontraktu w MF masz breaking change na etapie kompilacji TypeScript.
Jak zintegrować KSeF z Claude Desktop, Cursorem albo innym agentem AI?
Ksefnik wystawia pełny serwer Model Context Protocol (@ksefnik/mcp) z 8 narzędziami: pobieranie faktur z KSeF, import wyciągów bankowych, reconcyliacja, zapytania o niedopasowane pozycje, ręczne potwierdzanie matchów, walidacja i wysyłka. Konfiguracja Claude Desktop to 5 linii JSON-a w claude_desktop_config.json — szczegóły w sekcji MCP Server i w @ksefnik/mcp. Jeżeli szukasz KSeF MCP server albo KSeF Claude AI integration — to jest to.
Jak zautomatyzować dopasowanie faktur KSeF do wyciągu bankowego?
Silnik @ksefnik/core odpala 6-stopniowy pipeline reconcyliacji: referencja KSeF → NIP + dokładna kwota → numer faktury w tytule przelewu → fuzzy matching nazwy kontrahenta → płatności częściowe → proximity. Każdy match ma score, strategy i confidence, więc automatycznie wiesz, które dopasowania można zatwierdzić bez oglądania, a które skierować do ręcznej weryfikacji. Wspierane formaty wyciągów: MT940 (SWIFT, wszystkie polskie banki), mBank CSV, ING CSV, PKO BP CSV, Santander CSV.
Czy mogę testować integrację z KSeF offline, bez dostępu do api-test.ksef.mf.gov.pl?
Tak — @ksefnik/simulator to deterministyczny offline mock KSeF z gotowymi scenariuszami testowymi (happy-path, timeout, wygasła sesja, błąd walidacji NIP, opóźnione UPO). Implementuje dokładnie ten sam interfejs co @ksefnik/http, więc kod produkcyjny nie wie, że odpowiada mu mock. Idealny do CI w GitHub Actions — bez tokenów, bez sekretów, bez zależności od dostępności serwerów MF.
Szukam biblioteki do KSeF w Pythonie — czy jest alternatywa w TypeScript?
Ksefnik jest natywnym KSeF SDK w TypeScript — działa w Node.js 22+, Next.js API routes, serverless (Vercel Functions, Lambda, Cloudflare Workers), długo żyjących workerach, CLI i jako MCP server dla agentów AI. Kwoty są trzymane jako integer grosze (bez floatów), modele domenowe są schematami Zod, kryptografia idzie przez node:crypto + webcrypto.subtle (zero zależności kryptograficznych trzecich).
Jakie środowiska KSeF wspiera?
Środowisko
Bazowy URL
production
https://api.ksef.mf.gov.pl/v2
demo
https://api-demo.ksef.mf.gov.pl/v2
test
https://api-test.ksef.mf.gov.pl/v2
Środowisko ustawiasz flagą --env w CLI albo polem environment w createHttpAdapter. Domyślnie test, żeby nic nie wyszło na produkcję przypadkiem.
Czy Ksefnik obsługuje wysyłkę faktur do KSeF, czy tylko odczyt?
W obecnej wersji MVP pełna wysyłka (asynchroniczny POST /invoices/exports + polling + UPO) jest jeszcze niepełna — sendInvoice w @ksefnik/http jest stubem. Pełne wsparcie wysyłki wchodzi w v0.1. Pobieranie faktur, reconcyliacja, walidacja i integracja MCP działają produkcyjnie już dziś.
Licencja
MIT — darmowe dla wszystkich, do dowolnego zastosowania. Szczegóły w pliku LICENSE.
K
Ksefnik
CodeFormers-it·11 ดาว·
KSeF SDK for TypeScript/Node.js — invoice reconciliation with bank statements (MT940, mBank, ING, PKO, Santander), production KSeF 2.0 HTTP client, MCP server for Claude and Cursor. Open-source, MIT.
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
Ksefnik ต้องใช้ API key ไหม?
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Ksefnik ใช้ทรานสปอร์ตแบบใด?
Ksefnik ทำงานแบบโลคัลผ่าน stdio
Ksefnik ถูกตรวจสอบล่าสุดเมื่อใด?
ตรวจสอบล่าสุดเมื่อ 2026-10-28 KSeF SDK for TypeScript/Node.js — invoice reconciliation with bank statements (MT940, mBank, ING, PKO, Santander), production KSeF 2.0 HTTP client, MCP server for Claude and Cursor. Open-source, MIT.