Namespace: reconciliation

Namespace reconciliation uruchamia pipeline uzgadniania, który w 6 przebiegach (passach) dopasowuje faktury do transakcji bankowych.

run()

Uruchamia pełny pipeline uzgadniania. Używa passów zarejestrowanych w PluginRegistry — wbudowanych (order 100-500) oraz z pluginów (order 600+).

async run(
  invoices: Invoice[],
  transactions: BankTransaction[],
): Promise<ReconciliationReport>

Parametry

Pole	Typ	Opis
invoices	Invoice[]	Lista faktur do uzgodnienia
transactions	BankTransaction[]	Lista transakcji bankowych

Wbudowane passy

Pipeline wykonuje passy w kolejności order:

100 — KSeF Reference

Dopasowanie po numerze referencyjnym KSeF w opisie transakcji. Confidence: 100.

200 — Exact NIP + Amount

Dokładne dopasowanie: zgodny NIP i kwota. Confidence: 95.

300 — Invoice Reference

Numer faktury znaleziony w opisie transakcji. Confidence: 85.

400 — Fuzzy Match

Dopasowanie rozmyte (fuzzball) nazwy kontrahenta i opisu. Confidence: 60-80.

450 — Partial Amount

Suma kilku transakcji równa kwocie faktury. Confidence: 70.

500 — Proximity

Bliskość dat i zbliżona kwota jako ostatnia szansa. Confidence: 40-60.

Wskazówka

Pluginy pro dodają passy z order 600+, np. analiza wzorców płatności czy matching po kontach bankowych. Zarejestruj plugin przed wywołaniem run().

ReconciliationReport

Wynik uzgadniania zawiera dopasowania, niedopasowane elementy i podsumowanie.

interface ReconciliationReport {
  id: string                            // UUID raportu
  matched: Match[]                      // Dopasowane pary
  unmatchedInvoices: Invoice[]          // Faktury bez dopasowania
  unmatchedTransactions: BankTransaction[] // Transakcje bez dopasowania
  summary: Summary                      // Podsumowanie statystyczne
  runAt: string                         // ISO datetime uruchomienia
  durationMs: number                    // Czas trwania w ms
}

Summary

interface Summary {
  totalInvoices: number          // Łączna liczba faktur
  totalTransactions: number      // Łączna liczba transakcji
  matchedCount: number           // Liczba dopasowań
  unmatchedInvoiceCount: number  // Niedopasowane faktury
  unmatchedTransactionCount: number // Niedopasowane transakcje
  averageConfidence: number      // Średni confidence (0-100)
  passBreakdown: Record<string, number> // Dopasowania per pass
}

Przykład

import { createKsefnik } from '@ksefnik/core'
import { readFileSync } from 'node:fs'

const ksefnik = createKsefnik({
  config: { nip: '1234567890', environment: 'test' },
})

// Pobierz dane
const invoices = await ksefnik.invoices.list()
const bankContent = readFileSync('./wyciag.csv', 'utf-8')
const transactions = await ksefnik.bank.importFromString(bankContent)

// Uruchom uzgadnianie
const report = await ksefnik.reconciliation.run(invoices, transactions)

// Wyniki
console.log(`Dopasowano: ${report.summary.matchedCount}`)
console.log(`Niedopasowane faktury: ${report.summary.unmatchedInvoiceCount}`)
console.log(`Średni confidence: ${report.summary.averageConfidence.toFixed(1)}%`)
console.log(`Czas: ${report.durationMs}ms`)

// Breakdown per pass
for (const [pass, count] of Object.entries(report.summary.passBreakdown)) {
  console.log(`  ${pass}: ${count} dopasowań`)
}

// Szczegóły dopasowań
for (const match of report.matched) {
  console.log(`Faktura ${match.invoiceId} → Transakcja ${match.transactionId}`)
  console.log(`  Confidence: ${match.confidence}%, Pass: ${match.passName}`)
  console.log(`  Powody: ${match.reasons.join(', ')}`)
}

Filtrowanie po confidence

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

// Tylko pewne dopasowania (confidence >= 80)
const highConfidence = report.matched.filter((m) => m.confidence >= 80)

// Dopasowania wymagające weryfikacji
const needsReview = report.matched.filter(
  (m) => m.confidence >= 40 && m.confidence < 80,
)

console.log(`Pewne: ${highConfidence.length}`)
console.log(`Do weryfikacji: ${needsReview.length}`)
console.log(`Brak dopasowania: ${report.unmatchedInvoices.length}`)