Syfte

Bankimporten konverterar en banks CSV-export till hLedger-format och lägger de nya posterna i arbetsytans finance.journal. Den gemensamma importmotorn är byggd för flera bankformat, men i den här versionen är endast Swedbanks CSV registrerad och praktiskt stödd.

Importflödet omfattar:

1. parsning av CSV,
2. val av bankkonto,
3. routing av mottagare till hLedger-konton,
4. kontroll av okända mottagare,
5. fil- och innehållsbaserad dubblettkontroll,
6. valfri saldoavstämning,
7. rendering och append till journalen.

Rekommenderad start från en verklig bankfil

När den första arbetsytan ska bli ekonomiskt korrekt behöver den ett öppningssaldo. Swedbanks kolumn Bokfört saldo anger saldot efter respektive transaktion. Larin kan därför härleda saldot före den äldsta transaktionen:

öppningssaldo = bokfört saldo efter första transaktionen - transaktionsbelopp

Exempel: ett köp på -300.00 SEK med 4000.00 SEK i Bokfört saldo betyder att saldot före köpet var 4300.00 SEK.

Använd den användarvänliga klienten:

larin bootstrap ~/Hämtningar/first.csv ~/budget

Eller motorn direkt. Preview är standard:

ledgerctl bootstrap ~/Hämtningar/first.csv ~/budget

Previewn innehåller ett preview_digest. Verkställ först efter granskning:

ledgerctl bootstrap ~/Hämtningar/first.csv ~/budget \
  --apply \
  --preview-digest DIGEST-FRÅN-PREVIEW

Bootstrap validerar hela saldokedjan, kräver en enda valuta och ett entydigt bankkonto, skapar arbetsytan i en temporär katalog och publicerar den först när hledger check och budgetinvarianten har godkänts. Om CSV:n innehåller flera konton måste --bankaccount anges.

Den skapade opening.journal innehåller en riktig hledger-transaktion mot equity:opening-balances. Samma belopp speglas till budget:unallocated i den maskinhanterade funding-journalen, så den första budgetstatusen redan har rätt bankmedel och rätt mängd ej fördelade pengar.

CSV-filen kopieras till imports/ men importeras inte automatiskt. Fortsätt med:

cd ~/budget
ledgerctl audit imports/first.csv
ledgerctl suggest-routes imports/first.csv
ledgerctl import imports/first.csv
larin status

Detta bevarar importens vanliga säkerhetsmodell: okända mottagare får aldrig smita förbi preflight bara för att arbetsytan skapas.

Manuell initiering utan bankens öppningssaldo

En arbetsyta är katalogen där din ekonomiska data bor. Den ska normalt vara skild från katalogen där själva ledgerctl-koden är installerad.

ledgerctl init ~/budget

Eller:

mkdir -p ~/budget
cd ~/budget
ledgerctl init

Kommandot skapar endast sådant som saknas och rör inte befintliga filer:

~/budget/
  ledgerctl.conf
  finance.journal
  routes.conf
  imports/

Med en förberedd mottagardatabas:

ledgerctl init --with-seed ~/budget

Då skapas även en merchant-db.json med schema_version: 2 från projektets mall, om filen saknas eller är en giltig tom databas. En befintlig databas med merchants skrivs aldrig över.

Hur arbetsytan hittas

ledgerctl letar efter konfiguration i följande ordning:

1. filen som anges i miljövariabeln LEDGERCTL_CONFIG,
2. ledgerctl.conf i aktuell katalog eller någon föräldrakatalog,
3. ledgerctl.conf i verktygets installationskatalog,
4. ~/.config/ledgerctl/config.

Det vanliga arbetsflödet är därför:

cd ~/budget
ledgerctl report bal

Du kan stå i en underkatalog; sökningen går uppåt ungefär som Git letar efter .git.

Visa den aktiva konfigurationen:

ledgerctl config show
ledgerctl config path

Redigera den:

ledgerctl config edit

Viktiga inställningar

Ett normalt ledgerctl.conf kan innehålla:

LEDGER=finance.journal
ROUTES=routes.conf
IMPORT_DIR=imports
MERCHANT_DB=merchant-db.json
ASSET_ACCOUNT=assets:se:swedbank:konto
CURRENCY=SEK
# BANKACCOUNT=8327-9,1234567890
# HLEDGER=hledger
# MAKE=make

Relativa sökvägar tolkas relativt katalogen där ledgerctl.conf ligger.

ASSET_ACCOUNT är kontot som representerar bankkontot i hLedger. BANKACCOUNT är däremot bankens kontonummer i CSV-filen och kan användas när en export innehåller flera konton.

Placera bankfilen

Lägg Swedbanks CSV i imports/:

cp ~/Hämtningar/Kontohändelser.csv ~/budget/imports/2026-07.csv

Ge gärna filen ett stabilt och begripligt namn. Originalfilens hash och källrader används för spårbarhet och dubblettskydd.

Förhandskontroll

Kontrollera först filen mot nuvarande routing:

ledgerctl audit imports/2026-07.csv

Detta skriver ingenting. Om mottagare saknas, lär systemet dem med:

ledgerctl suggest-routes imports/2026-07.csv

Se Routes och mottagare.

Kuverttäckning före import

När BUDGET_ENABLED är aktivt gör importen en skrivskyddad kontroll av alla utgiftskonton i routes.conf innan CSV:n konverteras. Varje expenses:*-konto måste matcha exakt ett namngivet kuvert:

0 kuvert   -> fel: kategorin ligger utanför budgeten
1 kuvert   -> korrekt
2+ kuvert  -> fel: samma utgift skulle påverka flera kuvert

Kontrollera endast routes:

ledgerctl budget coverage --scope routes

Om flera kategorier saknar kuvert är den interaktiva assistenten snabbast:

ledgerctl suggest-envelopes

TAB kompletterar befintliga kuvert. Du kan välja ett kuvert, skapa ett nytt, välja en säker föräldrarot eller hoppa över. Besluten samlas i en enda plan; ingenting skrivs förrän hela planen har staged-validerats och du har godkänt den avslutande previewn.

Det obligatoriska reservkuvertet ser ut så här:

[envelope uncategorized]
label = Att kategorisera
accounts = expenses:uncategorized

Okända utgifter kan då importeras till expenses:uncategorized och blir synliga för senare klassificering. Okända inkomster stoppas fortfarande.

Om kontrollen misslyckas skriver importen uttryckligen att den stannade före CSV-konvertering och att inga journalfiler har ändrats. Felrapporten visar även körbara exempel för larin envelope update, larin envelope add och ledgerctl suggest-envelopes.

Importera

Grundkommando:

ledgerctl import imports/2026-07.csv

Utan filargument väljs den senast ändrade .csv-filen i IMPORT_DIR:

ledgerctl import

Interaktiv filväljare finns också:

ledgerctl fff

Vad som sker före skrivning

Importen verifierar bland annat routes, namngiven kuverttäckning, dubbletter och vald bankidentitet innan finance.journal öppnas för append.

ledgerctl import gör följande innan journalen ändras:

1. läser CSV-filen,
2. söker efter okända mottagare,
3. stoppar med exitkod 3 om någon mottagare saknar route,
4. skriver då ut ett utdrag som kan klistras in i routes.conf,
5. kontrollerar sannolika dubbletter mot manuella Purchase API-poster,
6. frågar om bekräftelse.

Okända utgifter får alltså inte tyst hamna i expenses:uncategorized genom det normala ledgerctl import-flödet.

Importlägen

För vanlig, noggrann månadsimport är --all det tydligaste läget:

ledgerctl import imports/2026-07.csv --all

För skriptad körning kan bekräftelsen stängas av:

ledgerctl import imports/2026-07.csv --all --yes

Använd --yes endast när preflight och felkoder faktiskt hanteras av skriptet. Flaggan accepterar även import trots sannolika dubbletter mot manuella poster.

Välj bankkonto i en fler-kontoexport

Tillfälligt:

ledgerctl import export.csv --bankaccount '8327-9,1234567890'

Permanent i ledgerctl.conf:

BANKACCOUNT='8327-9,1234567890'

Dubblettskydd

Importmotorn använder två kompletterande skydd:

• filhash stoppar en exakt återimport av samma CSV,
• innehållsfingeravtryck stoppar samma banktransaktion när överlappande exportperioder importeras.

Fingeravtrycken är förekomstmedvetna. Två verkliga, identiska köp samma dag kan behållas som två separata transaktioner i stället för att den ena försvinner.

Manuella köp från larin purchase eller ledgerctl add har inte bankens råa mottagarfält och kan därför inte behandlas som säkra bankdubbletter. Importen ger i stället en mjuk varning när datum, belopp, valuta och mottagaridentitet ser ut att motsvara en manuell post. Ingenting tas bort automatiskt.

Efter import

Kör minst:

ledgerctl reconcile
ledgerctl report reg20
ledgerctl report unknown

När budgetlagret är aktivt:

ledgerctl budget check
larin status

Felsituationer

Okända mottagare

Symptom: importen stoppar och visar ett routes-utdrag.

Åtgärd:

ledgerctl suggest-routes FIL.csv
ledgerctl audit FIL.csv
ledgerctl import FIL.csv

Fel bankkonto

Symptom: exporten innehåller flera konton eller inget konto matchar.

Åtgärd: ange --bankaccount eller sätt BANKACCOUNT i konfigurationen.

Samma CSV har redan importerats

Det är normalt ett skydd, inte ett fel i datan. Kontrollera journalens proveniensblock och använd inte --yes som försök att kringgå filhashen.

CSV saknar löpande saldo

Import och routing kan fortfarande fungera. Strikt reconcile och dagliga saldoassertions kan däremot inte ge samma kontroll utan saldokolumn.