Przejdź do głównej zawartości
ksefnik ksefnik — SDK do uzgadniania faktur KSeF

Szybki start

Ten przewodnik przeprowadzi Cię przez pierwsze uzgadnianie faktur KSeF z przelewami bankowymi. Użyjemy symulatora, więc nie potrzebujesz dostępu do prawdziwego KSeF.

  1. Zainstaluj pakiety

    Okno terminala
    pnpm add @ksefnik/core @ksefnik/simulator

  2. Utwórz plik reconcile.ts

    import { createKsefnik } from '@ksefnik/core'
    import { createKsefSimulator } from '@ksefnik/simulator'
    

    async function main() {
      // 1. Utwórz symulator z gotowym scenariuszem
      const { adapter, invoices } = createKsefSimulator({
        scenario: 'happy-path',
      })
    

      // 2. Zainicjalizuj SDK z symulatorem zamiast prawdziwego KSeF
      const ksef = createKsefnik({
        config: { nip: '5213456784', environment: 'test' },
        adapter,
      })
    

      // 3. Zaimportuj wyciąg bankowy (symulator generuje dopasowane transakcje)
      const bankStatement = await ksef.bank.importFromFile('./wyciag.csv')
    

      // 4. Uruchom uzgadnianie
      const report = await ksef.reconciliation.run(invoices, bankStatement)
    

      // 5. Wyświetl wyniki
      console.log('Podsumowanie uzgadniania:')
      console.log(`  Dopasowane:     ${report.summary.matchedCount}`)
      console.log(`  Niedopasowane:  ${report.summary.unmatchedInvoices}`)
      console.log(`  Bez faktury:    ${report.summary.unmatchedTransactions}`)
    

      // 6. Szczegóły dopasowań
      for (const match of report.matches) {
        console.log(
          `  ${match.invoice.number} → ${match.transaction.title} ` +
          `(${match.confidence}%, pass: ${match.passName})`
        )
      }
    }
    

    main()

  3. Uruchom skrypt

    Okno terminala
    npx tsx reconcile.ts

  4. Sprawdź wynik

    Podsumowanie uzgadniania:
      Dopasowane:     8
      Niedopasowane:  2
      Bez faktury:    1
    

      FV/2026/001 → Przelew za FV/2026/001 (99%, pass: ksef-ref)
      FV/2026/002 → Zapłata dla Acme Sp. z o.o. (95%, pass: exact)
      FV/2026/003 → FV 2026/003 opłata (90%, pass: invoice-ref)
      FV/2026/004 → Płatność Acme (78%, pass: fuzzy)
      ...

Co dalej?

Dział zatytułowany „Co dalej?”
Instalacja Szczegóły instalacji, wymagania systemowe i konfiguracja monorepo.
Jak działa pipeline Poznaj 6 etapów silnika uzgadniania i dowiedz się, jak konfigurować passy.
Import wyciągu bankowego Obsługiwane formaty bankowe, auto-detekcja i ekstrakcja NIP.