KSeF Downloader

Pobiera faktury z KSeF i zapisuje je jako XML, PDF lub Markdown. Dostępny jako CLI, serwer MCP i biblioteka TypeScript. Wymaga Node.js 22.14+.

Obsługuje logowanie certyfikatem KSeF, automatyczne odświeżanie sesji i wznawianie eksportu. Oryginalny XML jest zachowywany także przy wyborze PDF lub Markdown.

Szybki start

npx -y --prefer-online ksef-downloader@latest --env-file .env download --from 2026-10-01 --to 2026-10-17 --out ./faktury --formats xml,pdf,md

Polecenie uruchamia najnowsze wydanie. Aby wybrać konkretną wersję, zastąp @latest jej numerem, np. @0.1.0.

Related MCP server: mcp-ksef-pl

Konfiguracja

Ustaw zmienne środowiskowe lub zapisz je w pliku wskazanym przez --env-file:

KSEF_ENVIRONMENT=test
KSEF_NIP=YOUR_COMPANY_NIP
KSEF_CERT_PATH=C:/certificates/authentication.crt
KSEF_KEY_PATH=C:/certificates/authentication.key
KSEF_KEY_PASSWORD=YOUR_PRIVATE_KEY_PASSWORD

Środowiska: test (domyślne), demo, production. Logowanie wymaga certyfikatu uwierzytelniającego, odpowiadającego mu klucza PEM (RSA lub EC) i uprawnień do podanego NIP. Plik z hasłem przechowuj poza repozytorium.

CLI

# Sprawdzenie logowania
npx -y --prefer-online ksef-downloader@latest --env-file .env auth-check

# Lista faktur kosztowych
npx -y --prefer-online ksef-downloader@latest --env-file .env list --from 2026-10-01 --to 2026-10-17

# Pobranie XML i wizualizacji
npx -y --prefer-online ksef-downloader@latest --env-file .env download --from 2026-10-01 --to 2026-10-17 --out ./faktury --formats xml,pdf,md

# Konwersja lokalnego XML
npx -y --prefer-online ksef-downloader@latest render faktura.xml --out faktura.pdf --format pdf

Domyślnie pobierane są faktury kosztowe. Opcja --subject sales wybiera sprzedażowe. Filtry: --seller-nip, --invoice-number, --date-type (Issue, Invoicing, PermanentStorage). Daty bez godziny obejmują cały dzień w strefie Europe/Warsaw. Przy podawaniu godziny dodaj offset, np. 2026-10-01T12:00:00+02:00.

Nazwy plików odpowiadają numerom KSeF. Przy ponownym eksporcie program sprawdza istniejące pliki i pobiera brakujące. Formaty, limity i wznawianie eksportu.

MCP

Dodaj serwer do konfiguracji klienta MCP:

{
  "mcpServers": {
    "ksef-downloader": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "ksef-downloader@latest", "mcp"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_NIP": "YOUR_COMPANY_NIP",
        "KSEF_CERT_PATH": "C:/certificates/authentication.crt",
        "KSEF_KEY_PATH": "C:/certificates/authentication.key",
        "KSEF_KEY_PASSWORD": "YOUR_PRIVATE_KEY_PASSWORD"
      }
    }
  }
}

Podaj bezwzględne ścieżki certyfikatu i klucza. Na Windows można użyć zapisu C:/certificates/authentication.crt. Jeśli klient wymaga pełnej ścieżki do programu, wskaż npx.cmd z instalacji Node.js. Aktualizacja paczki jest uwzględniana po restarcie MCP.

Biblioteka

import { KsefClient, KsefDownloader, settingsFromEnv, invoicePdf } from 'ksef-downloader';

const downloader = new KsefDownloader(new KsefClient(settingsFromEnv()), { pdf: invoicePdf });
const result = await downloader.export({
  from: '2026-10-01',
  to: '2026-10-17',
  directory: './faktury',
  formats: ['xml', 'pdf', 'md'],
});

KsefClient.list() zwraca metadane, a KsefClient.download() oryginalne bajty XML. Funkcje invoiceMarkdown() i invoicePdf() przyjmują również lokalne dokumenty.

Rozwój

npm ci
npm run dev -- --help
npm run check

CI uruchamia testy na Windows i Linux dla Node.js 22 i 24. Wydawanie wersji.

Licencja

MIT. Licencje głównych zależności opisano w THIRD_PARTY_NOTICES.md.