ledgerctl — routes och mottagardatabas

[2026-07-24 Fri]

Syfte

Routes-delsystemet gör bankimporten gradvis mer automatisk. När du en gång har bestämt att ett rått banknamn är en viss mottagare och hör till ett visst konto, sparas beslutet och återanvänds vid kommande importer.

Systemet har två filer med olika ansvar:

Fil	Ansvar
`routes.conf`	Ruttar bankens råa text till ett hLedger-konto vid import
`merchant-db.json`	Beskriver merchants, bank-alias och mänskliga shortcuts i schema version 2

routes.conf bestämmer kontot vid importen. merchant-db.json ger en stabil merchantidentitet. Varje merchant har separata aliases för bankdata och shortcuts för mänskliga klienter som larin purchase, ledgerctl add och Emacs-formulären.

routes.conf

Grundformat:

[expenses:groceries]
ICA
WILLYS

[expenses:hobbies:books]
AKADEMIBOKHANDELN
<SJ>

[expenses:uncategorized]

En sektion anger målkommandot. Raderna under sektionen är termer som matchas case-insensitivt mot bankens råa mottagartext.

ICA är en substring-matchning.
<SJ> kräver exakt ordmatchning och matchar inte exempelvis SJÖGRENS BUTIK.
Mer specifika termer bör stå före mer generella termer.
Omatchade utgifter faller tillbaka till expenses:uncategorized och positiva belopp till income:unknown i den underliggande motorn.

Det normala ledgerctl import-flödet stoppar innan sådana poster skrivs.

Börja med seeddata

Vid en ny arbetsyta:

ledgerctl init --with-seed ~/budget

Det ger en startdatabas med ett antal vanliga svenska kedjor. Anpassa default_category i merchant-db.json om ditt eget kontoträd skiljer sig från mallen.

Seedning skriver aldrig över en befintlig, icke-tom merchantdatabas.

Hitta okända mottagare

För en ännu inte importerad fil:

ledgerctl audit imports/2026-07.csv

Importkommandot gör samma kontroll automatiskt, men audit är lämpligt när du vill förbereda routing utan att starta en import.

Lär in mottagare interaktivt

ledgerctl suggest-routes imports/2026-07.csv

Utan filargument väljs en CSV interaktivt från IMPORT_DIR.

Verktyget grupperar snarlika råa namn för att minska antalet frågor. Exempel:

Amazon*134
Amazon*457
AmazonRetail

kan behandlas som en grupp. Klustringen är konservativ för att hellre ställa en extra fråga än slå ihop två olika företag.

Val i suggest-routes

Val	Betydelse
`m`	Skapa en ny merchant och välj standardkategori
`j`	Koppla gruppen till en befintlig merchant med TAB-komplettering
`d`	Dela upp en felaktigt sammanfogad grupp och behandla varje variant separat
`s` eller tom rad	Hoppa över utan ändring
`q`	Avsluta; redan bekräftade beslut behålls

Valen skriver de bekräftade ändringarna direkt till merchant-db.json och routes.conf. Det finns ingen ytterligare slutbekräftelse. Ha därför arbetsytan under versionskontroll eller ta en kopia innan en större session.

Skapa en ny merchant

Vid m (för merchant) får du normalt ange:

visningsnamn,
hLedger-kategori,
valfritt land,
merchant-id.

Kategori-prompten kan komplettera från konton som redan finns i routes.conf, merchantdatabasen och journalen.

Exempel på resultat i merchant-db.json:

{
  "schema_version": 2,
  "merchants": {
    "merchant-uppsala-english-bookshop": {
      "display_name": "Uppsala English Bookshop",
      "default_category": "expenses:hobbies:books",
      "aliases": ["UPPSALA ENGLISH BOOKSHOP", "UEB WEBBOKHANDE"],
      "shortcuts": ["ueb"]
    }
  }
}

suggest-routes lär bankalias. Mänskliga shortcuts kan läggas till genom Merchant API:t eller när merchant skapas med larin merchant add. larin purchase och ledgerctl add använder endast redan skapade merchants och shortcuts.

Skapa merchant med Larin CLI

När du redan vet vilken merchant du vill lägga till är den rekommenderade vardagsvägen:

larin merchant add

Svenskt alias:

larin handlare skapa

Det interaktiva flödet erbjuder TAB-komplettering för kända expense-konton, visar Merchant API:ts preview och skickar sedan exakt samma request med revisionsskydd vid apply. larin skriver aldrig merchant-db.json direkt.

Direkt form:

larin merchant add \
  --name "Uppsala English Bookshop" \
  --category expenses:hobbies:books \
  --shortcut ueb \
  --alias "THE ENGLISH BOOK" \
  --country SE

Använd --preview-only för att granska utan skrivning och --yes för att verkställa den visade previewn utan en andra terminalfråga.

suggest-routes är fortfarande rätt verktyg när utgångspunkten är okända råa namn i en bank-CSV och du samtidigt behöver skapa route-termer. Larin CLI är bättre när du medvetet skapar eller administrerar en merchant utanför ett importflöde.

Uppdatera en merchant utan filredigering

När en merchant har rätt identitet men fel standardkonto ska profilen uppdateras i stället för att en ny merchant skapas. I Emacs:

öppna administrationen med A,
placera markören på merchanten,
tryck u,
ändra exempelvis expenses:travels till expenses:transport,
granska previewn och verkställ.

Det ändrar framtida manuella köp och nya route-förslag som använder merchantens default_category. En redan befintlig sektion i routes.conf ändras inte. Alias och shortcuts lämnas orörda.

Motornära JSON-form:

cat >/tmp/merchant-update.json <<'JSON'
{
  "schema_version": 1,
  "merchant": {
    "default_category": "expenses:transport"
  }
}
JSON

ledgerctl merchant update merchant-sj \
  --input-json /tmp/merchant-update.json \
  --format json

Apply görs först efter granskning med previewns revision och samma requestfil. Befintliga journalposter skrivs inte om när merchantprofilen ändras; felklassificerade manuella köp rättas separat genom Purchase API:t.

Display-namn och rå bankidentitet

När en känd merchant importeras kan journalens rubrik visa det kurerade namnet:

2026-01-05 * Amazon Retail
    ; merchant-id: merchant-amazon
    ; csv-payee: Amazonretail*zg6
    assets:se:swedbank:konto    -388.37 SEK
    expenses:shopping:other

Den råa banktexten i csv-payee är fortfarande den kanoniska källidentiteten. Routing, audit och dedupe är därför inte beroende av att ett display-namn förblir oförändrat.

Du kan byta display_name i merchant-db.json utan att ändra identiteten på redan importerade transaktioner. Nya importer får det nya visningsnamnet; befintliga journalposter skrivs inte om automatiskt.

Koppla en variant till en befintlig merchant

Välj j (för join) när den nya banktexten är en ny variant av något som redan finns. Exempel:

Bastard Burgers Uppsala
BSTRD BURGERS 1042

Båda kan peka på samma merchant-id och standardkategori. Detta är bättre än att skapa dubbla merchants som senare behöver slås ihop.

Dela en felaktig grupp

Välj d (för disjoin) när två liknande namn faktiskt är olika mottagare. Verktyget frågar då för varje variant och kan skriva separata route-termer.

Gissa inte bara för att fuzzy-förslaget ser rimligt ut. Ett felaktigt merchantval påverkar alla framtida importer tills aliaset och routen korrigeras.

Korrigera ett felaktigt beslut

Ta bort eller ändra det felaktiga aliaset i merchantposten i merchant-db.json.
Ta bort den felaktiga termen i routes.conf.
Ta bort en helt felaktig merchant endast om inga andra alias eller shortcuts behöver den.
Kör ledgerctl suggest-routes CSV-FIL igen.
Kör ledgerctl audit CSV-FIL innan import.

Audit av befintlig journal

ledgerctl audit

Utan CSV jämför kommandot routes.conf med den redan importerade journalen och rapporterar bland annat:

råa mottagare som inte längre matchar någon route,
route-termer som inte används av journalen.

En oanvänd term är inte automatiskt ett fel. Det kan vara en framtida regel eller en mottagare som inte förekommit i den valda journalhistoriken. Audit är ett beslutsunderlag och ändrar ingenting.

Referens-only-transaktioner

Vissa betalningar innehåller endast nummer i referens och beskrivning, utan en stabil mottagartext. De kan kategoriseras, men bör inte få ett globalt tomt eller numeriskt alias som riskerar att kollidera med andra betalningar.

Rekommenderat arbetsflöde

För en arbetsyta med aktiverad kuvertbudget:

ledgerctl audit imports/2026-07.csv
ledgerctl suggest-routes imports/2026-07.csv
ledgerctl suggest-envelopes
ledgerctl budget coverage --scope routes
ledgerctl audit imports/2026-07.csv
ledgerctl import imports/2026-07.csv --all
ledgerctl audit

Det första audit-steget visar arbetsmängden. Det andra verifierar att alla mottagare nu är routade. Det sista hittar långsiktig drift mellan journal och routefil.