KSeF Client (TypeScript)

ksef-client to TypeScript SDK do integracji z KSeF. Biblioteka udostępnia typowane klienty endpointów, gotowe workflowy (auth/sesje/eksport) i narzędzia pomocnicze (XAdES, QR, linki weryfikacyjne).

Kompatybilność

• KSeF API: v2.4.0
• Node.js: >= 20
• Środowiska: TEST, DEMO, PRD

KSeF 2.4.0 rozszerza obsługę błędów o application/problem+json oraz doprecyzowuje operacje na tokenie użytym do bieżącego uwierzytelnienia. SDK zachowuje dotychczasowe metody klientów, a bogatszy format błędów możesz wymusić przez nagłówek X-Error-Format: problem-details ustawiony w KsefClientOptions.headers.

Instalacja

npm install ksef-client

Opcjonalne zależności:

npm install qrcode node-forge

• qrcode jest wymagane dla client.qr
• node-forge jest wymagane dla XadesKeyPair.fromPkcs12*

Quick Start

import { KsefClient } from "ksef-client";

const client = await KsefClient.connect({
  environment: "DEMO",
  token: process.env.KSEF_TOKEN!,
  context: { type: "Nip", value: "5265877635" },
  pollIntervalMs: 2000,
  maxAttempts: 60,
});

const metadata = await client.invoices.queryInvoiceMetadata(
  {
    subjectType: "Subject1",
    dateRange: {
      dateType: "Issue",
      from: "2025-01-01",
      to: "2025-01-31",
    },
  },
  0,
  10,
  "Desc",
);

console.log(metadata);

Use Cases

• Token auth i pierwszy request: docs/getting-started.md
• Uwierzytelnienie certyfikatem (XAdES): docs/workflows/auth.md
• Wysyłka faktur w sesji online: docs/workflows/online-session.md
• Wysyłka wsadowa (ZIP): docs/workflows/batch-session.md
• Tryb offline (offline24 / offline): docs/workflows/offline.md
• Eksport i eksport przyrostowy: docs/workflows/export.md
• Gotowe snippety end-to-end: docs/examples/README.md

Dokumentacja

• Start: docs/getting-started.md
• Konfiguracja i błędy: docs/configuration.md, docs/errors.md
• API endpointów: docs/api/README.md
• Workflows: docs/workflows/README.md
• Usługi i utils: docs/services/README.md, docs/utils/README.md
• Przykłady: docs/examples/README.md
• Pełny indeks: docs/README.md
• Dla maintainerów: docs/maintainers.md

Bezpieczeństwo

• Nie loguj tokenów i kluczy prywatnych.
• Przekazuj dane KSEF_* przez zmienne środowiskowe/secrets.
• Nie commituj plików certyfikatów i kluczy (.pem, .p12, .pfx).

Licencja

MIT. Zobacz LICENSE.