Import wyciągu bankowego

Moduł bank obsługuje import wyciągów bankowych z 5 formatów polskich banków. Automatycznie wykrywa format pliku, parsuje kwoty na grosze i wyciąga NIP-y z tytułów przelewów.

Obsługiwane formaty

Bank	Format	Separator	Kodowanie	Rozszerzenie
mBank	CSV	;	Windows-1250	.csv
ING Bank Śląski	CSV	;	UTF-8	.csv
PKO BP (iPKO)	CSV	,	UTF-8	.csv
Santander	CSV	;	Windows-1250	.csv
Dowolny	MT940 (SWIFT)	—	ASCII	.mt940, .sta

Wskazówka

Nie musisz podawać typu pliku. Ksefnik analizuje nagłówki i strukturę pliku, żeby automatycznie rozpoznać format.

Import wyciągu

SDK

import { createKsefnik } from '@ksefnik/core';

const ksef = createKsefnik({
  config: { nip: '5213456784' },
});

// Import z pliku na dysku
const transactions = await ksef.bank.importStatement('./wyciag-marzec.csv');

console.log(`Zaimportowano ${transactions.length} transakcji`);

for (const tx of transactions) {
  console.log(
    `${tx.date} | ${tx.amount > 0 ? 'IN' : 'OUT'} | ${tx.amount} gr | ${tx.title}`
  );
}

Możesz też zaimportować z ciągu znaków (przydatne gdy dane przychodzą z API):

const csvContent = await fetch('https://example.com/wyciag.csv').then(r => r.text());

const transactions = await ksef.bank.importStatementFromString(csvContent);

CLI

# Import wyciągu — auto-detekcja formatu
ksefnik bank import ./wyciag-marzec.csv

# Wyświetl jako tabelę
ksefnik bank import ./wyciag-marzec.csv --format table

# Zapisz sparsowane transakcje jako JSON
ksefnik bank import ./wyciag-marzec.csv --format json > transakcje.json

# Import wyciągu MT940
ksefnik bank import ./wyciag.mt940

Auto-detekcja formatu

Parser analizuje plik w trzech krokach:

1. Rozszerzenie — pliki .mt940 i .sta trafiają od razu do parsera MT940.
2. Nagłówki CSV — parser porównuje pierwszą linię z znanymi schematami nagłówków banków.
3. Heurystyka — jeśli nagłówki nie pasują, parser analizuje separatory, kodowanie i strukturę kolumn.

Jeśli auto-detekcja zawiedzie, możesz wymusić format:

const transactions = await ksef.bank.importStatement('./wyciag.csv', {
  parser: 'mbank',
});

Ekstrakcja NIP z tytułów przelewów

Ksefnik stosuje 3 strategie ekstrakcji NIP z tytułu przelewu (w kolejności priorytetów):

Strategia	Wzorzec	Przykład tytułu
MPP (split payment)	/VAT/...NIP/1234563218	/VAT/230,00/IDC/FV/2026/03/15/NIP/1234563218
Prefiks NIP	NIP: 1234563218 lub NIP 1234563218	Zapłata za FV/2026/03/15 NIP: 1234563218
Surowy checksum	10-cyfrowy ciąg z poprawną sumą kontrolną	Przelew za usługi 1234563218 marzec

const transactions = await ksef.bank.importStatement('./wyciag.csv');

// Sprawdź, ile transakcji ma wykryty NIP
const withNip = transactions.filter(tx => tx.extractedNip);
console.log(`NIP wykryty w ${withNip.length}/${transactions.length} transakcjach`);

Notatka

Strategia “surowy checksum” może dać fałszywe dopasowania (np. numer rachunku bankowego spełniający checksum NIP). Dlatego ma najniższy priorytet i jest używana tylko gdy pozostałe strategie nie znalazły wyniku.

Parsowanie kwot

Wszystkie kwoty są konwertowane na grosze (liczby całkowite):

Wartość w pliku	Wynik w tx.amount	Kierunek
1 234,56	123456	przychodzący
-1 234,56	-123456	wychodzący
0,01	1	przychodzący

for (const tx of transactions) {
  const zlote = (Math.abs(tx.amount) / 100).toFixed(2);
  const kierunek = tx.amount > 0 ? 'przychodzący' : 'wychodzący';
  console.log(`${zlote} PLN (${kierunek})`);
}

Uwaga

Nigdy nie używaj float do operacji na kwotach. Ksefnik przechowuje wszystko w groszach jako number (integer), żeby uniknąć błędów zaokrągleń.

Przykład: import wyciągu z mBanku za marzec

1. Zaloguj się do mBanku i pobierz wyciąg za marzec 2026 w formacie CSV.
2. Uruchom import:

   ksefnik bank import ./mbank-marzec-2026.csv --format table

3. Przejrzyj wynik — każda transakcja ma datę, kwotę w groszach, tytuł i (opcjonalnie) wykryty NIP.
4. Następny krok: uzgadnianie faktur z przelewami.