Obsługiwane formaty

Ksefnik obsługuje 5 formatów wyciągów bankowych z polskich banków. Każdy parser implementuje interfejs BankStatementParser i jest automatycznie wykrywany na podstawie treści pliku.

Tabela porównawcza

Bank	Format	Separator	Kodowanie	Format daty
MT940	SWIFT MT940	pola :XX:	ASCII	YYMMDD
mBank	CSV	;	UTF-8	YYYY-MM-DD
ING	CSV	;	UTF-8	YYYYMMDD
PKO BP	CSV	,	UTF-8	YYYY-MM-DD
Santander	CSV	;	UTF-8	DD-MM-YYYY

Interfejs BankStatementParser

Wszystkie parsery implementują wspólny interfejs:

interface BankStatementParser {
  bank: string
  canParse(content: string | Buffer): Promise<boolean>
  parse(content: string | Buffer): Promise<BankTransaction[]>
}

• bank — identyfikator parsera (np. 'mbank', 'ing')
• canParse() — sprawdza czy treść pasuje do tego formatu
• parse() — parsuje treść i zwraca tablicę BankTransaction

Auto-detekcja

Nie musisz podawać formatu ręcznie. Funkcja importBankStatement() automatycznie wykrywa format na podstawie nagłówków i struktury pliku:

import { importBankStatement } from '@ksefnik/core'

// Format zostanie wykryty automatycznie
const transactions = await importBankStatement('./wyciag.csv')

Wskazówka

Szczegóły mechanizmu auto-detekcji znajdziesz na stronie Auto-detekcja formatu.

Jak dodać nowy parser

Aby obsłużyć nowy format bankowy, zaimplementuj interfejs BankStatementParser:

import type { BankStatementParser, BankTransaction } from '@ksefnik/shared'

export class MojBankParser implements BankStatementParser {
  bank = 'moj-bank'

  async canParse(content: string | Buffer): Promise<boolean> {
    const text = typeof content === 'string' ? content : content.toString('utf-8')
    return text.includes('MOJ-BANK-HEADER')
  }

  async parse(content: string | Buffer): Promise<BankTransaction[]> {
    const text = typeof content === 'string' ? content : content.toString('utf-8')
    // Logika parsowania...
    return []
  }
}

Następnie przekaż parser do importBankStatementFromString():

import { importBankStatementFromString, getDefaultParsers } from '@ksefnik/core'
import { MojBankParser } from './moj-bank.parser.js'

const parsers = [...getDefaultParsers(), new MojBankParser()]
const transactions = await importBankStatementFromString(content, { parsers })

MT940

Uniwersalny format SWIFT. Dokumentacja

mBank

CSV z separatorem ;. Dokumentacja

ING

CSV z quoted headers. Dokumentacja

PKO BP

CSV z separatorem ,. Dokumentacja