Larin — manuella köp genom Purchase API

larin purchase är den rekommenderade vardagsklienten för manuella köp. ledgerctl add finns kvar som en tunn mänsklig adapter när du vill arbeta närmare motorn. Båda använder det versionsmärkta Purchase API:t och saknar egen skrivlogik: de gör preview, visar konsekvenserna och applicerar samma granskade begäran med revision, request_digest och idempotensnyckel.

larin purchase --merchant ueb --amount 300

Förutsättningar

Arbetsytan behöver finance.journal, merchant-db.json med schema_version: 2 och en merchant med shortcut eller känt namn/id.

En okänd merchant skapas separat genom Merchant API:t, exempelvis med larin merchant add. Varken larin purchase eller ledgerctl add skapar merchantdata som en sidoeffekt.

När kuvertbudgeten är aktiv måste köpets expenses:*-konto matcha exakt ett namngivet kuvert. Previewn visar det verkliga kontot, matchande kuvert och can_apply. Ett otäckt eller tvetydigt konto stoppas före skrivning; rätta då merchantens standardkonto eller kuvertmappningen och granska köpet igen.

Interaktiv Larin-klient

larin

Skriv köp eller börja skriva kommandot och tryck TAB. Du kan också starta köpflödet direkt:

larin purchase

Merchantprompten kompletterar shortcuts och merchantnamn från Merchant API:t. Bankalias accepteras inte som mänsklig inmatning.

Merchant och belopp

larin purchase --merchant ueb --amount 300
larin purchase --merchant "Uppsala English Bookshop" --amount 300,50
larin purchase --merchant merchant-uppsala-english-bookshop --amount 300.50

Beloppet anges positivt och behandlas som en exakt decimalsträng. Purchase API bokför köpet som en utgift från tillgångskontot.

Motornära adapter: ledgerctl add

ledgerctl add
ledgerctl add ueb

ledgerctl add har också TAB-komplettering över befintliga shortcuts och merchantnamn. Okänd inmatning hänvisas till Merchant API:t eller larin merchant add.

Datum, anteckning och kategori

larin purchase --merchant ueb --amount 299 --note "Ny fantasyroman"
larin purchase --merchant ueb --amount 299 --date 2026-07-18

# Motornära kategoriöverstyrning:
ledgerctl add ica 450 --category expenses:household:party

Kategoriöverstyrningen gäller endast detta köp; merchantens default_category ändras inte.

Pending och cleared

Standard är pending (!). Använd --cleared endast när köpet redan betraktas som verifierat:

larin purchase --merchant ueb --amount 300 --cleared

Preview

larin purchase --merchant ueb --amount 300 --preview-only

Detta kör en riktig Purchase API-preview och visar journalpost, purchase-ID, idempotensnyckel, utgiftskonto, matchande kuvert och budgetpåverkan. Ingen fil skrivs. Om kategorin inte tillhör exakt ett kuvert visas orsaken och apply förblir blockerad.

Idempotens

Varje normalt terminalflöde genererar en ny nyckel. För script eller en säker retry kan klienten välja den själv:

ledgerctl add ueb 300 \
  --idempotency-key terminal-20260720-book-0001

Dubblettvarning

Ett annat köp med ny nyckel men samma datum och belopp kan vara en dubblett. Preview returnerar kandidater och kommandot kräver bekräftelse. I ett icke-interaktivt flöde:

larin purchase --merchant ueb --amount 300 --yes

I Larin CLI hoppar --yes över den andra terminalfrågan men inte previewn. Dubblettbekräftelse, revisions- och digestskydd är fortfarande aktiva.

Journalens kvitto

Hitta och klassificera om manuella köp

Manuella köp som ligger i Att kategorisera eller saknar entydigt kuvert kan listas skrivskyddat:

ledgerctl purchase list --needs-attention
ledgerctl purchase list --needs-attention --period 2026-07 --format json

Den användarvänliga vägen finns i Emacs budgetpanel. Tryck C, välj köp och välj därefter ett konto från ett namngivet kuvert. Previewn visar konto och kuvert före och efter samt hela journalblocket. Apply kräver samma request_digest och workspace-revision som previewn.

Om merchantens standardkonto också är fel, uppdatera merchanten med u i Emacs-administrationen. Omklassificeringen rättar den valda journalposten; merchantuppdateringen styr framtida köp. Det är två separata och uttryckliga beslut.

Nuvarande reklassificeringsflöde gäller manuella poster med ledgerctl-purchase-id. Importerade poster i reservkuvertet behöver ett separat generellt transaktionsflöde.

Inkomster

Purchase API v1 beskriver köp. Den tidigare --income-vägen är borttagen ur ledgerctl add. Inkomster får ett eget domän-API i stället för att blandas in i köpoperationen.

När bankens CSV senare importeras

Bankposten och den manuella posten har olika källidentitet. Importen varnar om en sannolik motsvarighet men raderar eller slår aldrig ihop poster automatiskt.

Syfte