Migracja z konkurencji

Przewodnik migracji na ksefnik z popularnych rozwiązań KSeF i ręcznych procesów.

Dlaczego ksefnik

SDK-first

Cała logika w bibliotece TypeScript. CLI, MCP i API to cienkie wrappery. Pełna kontrola programistyczna.

Open-source core

Darmowy, otwarty core z 6 passami uzgadniania, 20 regułami walidacji i 5 parserami bankowymi.

Plugin system

Rozszerzalny bez forka. Pro features jako osobne pakiety npm, bez DRM.

MCP-ready

Natywna integracja z Claude, Cursor, Windsurf i innymi narzędziami AI przez Model Context Protocol.

Z ksefapi.pl

Porównanie

Aspekt	ksefapi.pl	ksefnik
Model	SaaS API	SDK (biblioteka npm)
Cena	od 500 PLN/NIP/mies.	Core: darmowy, Pro: tańszy
Hosting	Ich serwer	Twoja infrastruktura
Uzgadnianie	Brak	6-pass pipeline + pluginy
AI integration	Brak	MCP server
Vendor lock-in	Tak (API)	Nie (adapter pattern)

Migracja

Zainstaluj ksefnik:
Okno terminala
```
pnpm add @ksefnik/core @ksefnik/shared
```

Stwórz adapter wrappujący istniejący klient ksefapi.pl:

import type { KsefAdapter } from '@ksefnik/shared'

class KsefApiPlAdapter implements KsefAdapter {
  constructor(private apiKey: string) {}

  async fetchInvoices(opts) {
    const res = await fetch('https://api.ksefapi.pl/invoices', {
      headers: { Authorization: `Bearer ${this.apiKey}` },
      body: JSON.stringify({ from: opts.from, to: opts.to }),
    })
    return mapToKsefnikFormat(await res.json())
  }

  async sendInvoice(input) { /* ... */ }
  async getUpo(ref) { /* ... */ }
}

Użyj z ksefnik:

const ksefnik = createKsefnik({
  config: { nip: '1234567890', environment: 'production' },
  adapter: new KsefApiPlAdapter(process.env.KSEFAPI_KEY!),
})

Stopniowo migruj na natywny adapter KSeF (bez proxy przez ksefapi.pl).

Z ręcznego Excela

Ręczne uzgadnianie w Excelu to najczęstszy “konkurent”. Typowy proces:

Eksport faktur z KSeF (ręcznie, portal)
Eksport wyciągu z banku (CSV)
Porównywanie kolumn w Excelu (VLOOKUP, ręczne sprawdzanie)

Co zyskujesz z ksefnik

Ręczny Excel	Ksefnik
Godziny pracy miesięcznie	Sekundy (automatyczny pipeline)
Błędy ludzkie	6 algorytmów dopasowania
Brak walidacji	20 reguł walidacji
Brak historii	Storage (SQLite) z pełną historią
Brak API	MCP dla AI, CLI dla automatyzacji

Migracja

Zainstaluj ksefnik CLI:
Okno terminala
```
pnpm add -g @ksefnik/cli
```
Zaimportuj wyciąg bankowy:
Okno terminala
```
ksefnik bank-import ./wyciag-mbank.csv
```

Pobierz faktury z KSeF:

ksefnik fetch --from 2025-01-01 --to 2025-03-31

Uruchom uzgadnianie:
Okno terminala
```
ksefnik reconcile
```
Przejrzyj wyniki — confidence, powody, niedopasowania.

Z własnego rozwiązania

Jeśli masz własny kod do komunikacji z KSeF, nie musisz go wyrzucać. Adapter pattern pozwala wrappować istniejącą logikę.

import type { KsefAdapter } from '@ksefnik/shared'

// Twój istniejący klient
import { MyKsefClient } from './my-ksef-client'

class MyClientAdapter implements KsefAdapter {
  private client = new MyKsefClient()

  async fetchInvoices(opts) {
    const invoices = await this.client.getAll(opts.from, opts.to)
    return invoices.map((inv) => ({
      id: crypto.randomUUID(),
      invoiceNumber: inv.nr,
      sellerNIP: inv.sprzedawca_nip,
      grossAmount: Math.round(inv.brutto * 100), // PLN → grosze
      currency: 'PLN' as const,
      issueDate: inv.data_wystawienia,
      createdAt: new Date().toISOString(),
    }))
  }

  async sendInvoice(input) { /* ... */ }
  async getUpo(ref) { /* ... */ }
}

const ksefnik = createKsefnik({
  config: { nip: '1234567890', environment: 'production' },
  adapter: new MyClientAdapter(),
})

// Teraz masz pełen pipeline uzgadniania na swoich danych
const invoices = await ksefnik.invoices.fetch({
  from: '2025-01-01',
  to: '2025-03-31',
})

const bankContent = readFileSync('./wyciag.csv', 'utf-8')
const txs = await ksefnik.bank.importFromString(bankContent)

const report = await ksefnik.reconciliation.run(invoices, txs)

// Dodatkowy bonus: walidacja faktur
const validationReports = ksefnik.validation.validate(invoices)

const invalid = validationReports.filter((r) => !r.valid)
if (invalid.length > 0) {
  console.log(`Znaleziono ${invalid.length} niepoprawnych faktur`)
}