bus-bank — import and review bank transactions
bus-bank — import and review bank transactions
bus bank is where bank data usually enters a BusDK workspace. It turns source files into normalized bank rows, lets you inspect the imported result, and gives you control reports for backlog, posting coverage, and statement balance verification.
This module does not create journal entries by itself. After import, the next steps are usually bus-reconcile, bus-journal, or both.
Common tasks
Create the bank datasets for a new workspace:
bus bank init
Import a statement file and list the imported rows for one month:
bus bank import --file ./statements/2026-01.csv
bus bank list --month 2026-01
Add one statement-backed row manually when the source evidence has no reliable human-readable counterparty name:
bus bank add --bank-id bt-2 --import-id imp-1 --booked-date 2026-01-03 \
--amount -5.00 --currency EUR --reference RF-123 \
--message "No counterparty in source"
Import a year of ERP-exported bank history with a deterministic profile:
bus bank import \
--profile ./profiles/erp-bank.yaml \
--source ./exports/bank-2024.tsv \
--year 2024
Find bank rows that are still not matched or posted:
bus bank backlog --month 2026-01 --detail
bus bank --format json -o ./out/bank-coverage-2026.json coverage --year 2026
bus bank control --month 2026-01 --account acct-1
Parse and verify a statement before trusting the closing balance:
bus bank -f json statement parse --file ./statements/2026-01.pdf \
-o ./out/statement-2026-01.json
bus bank statement verify --statement ./out/statement-2026-01.json \
--fail-if-diff-over 0.01
Teach BusDK how to normalize one counterparty name and extract invoice hints from bank messages:
bus bank config counterparty add \
--canonical "Sendanor Oy" \
--alias "SENDANOR" \
--alias "Sendanor Oy"
bus bank config extractors add \
--field invoice_number_hint \
--pattern 'Viite[: ]+([0-9]+)' \
--source message
Synopsis
bus bank init [-C <dir>] [global flags]
bus bank import --file <path> [-C <dir>] [global flags]
bus bank import --profile <path|erp-tsv> --source <path> [--year <YYYY>] [--fail-on-ambiguity] [-C <dir>] [global flags]
bus bank list [--month <YYYY-MM>] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--counterparty <id>] [--invoice-ref <ref>] [-C <dir>] [global flags]
bus bank backlog [--month <YYYY-MM>] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--detail] [--fail-on-backlog] [--max-unposted <n>] [-C <dir>] [global flags]
bus bank coverage --year <YYYY> [-C <dir>] [global flags]
bus bank control [--month <YYYY-MM> | --year <YYYY> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--account <id>] [-C <dir>] [global flags]
bus bank statement extract --file <path> [options] [-C <dir>] [global flags]
bus bank statement parse --file <path> [options] [-C <dir>] [global flags]
bus bank statement verify [--statement <parsed.json|attachment-id>] [--year <YYYY>] [--account <id>] [--fail-if-diff-over <amount>] [-C <dir>] [global flags]
bus bank config <subcommand> ...
Command-local help is available too, for example bus bank add --help.
Import modes
Use import --file when you already have a bank statement or a normalized source file for one import run.
Use import --profile --source when you are migrating history or importing provider-specific exports repeatedly. The profile keeps the mapping rules versioned and reusable.
If the input is messy ERP TSV, the built-in erp-tsv profile is the fast path:
bus bank import --profile erp-tsv --source ./exports/bank.tsv --year 2024 --fail-on-ambiguity
The commands most people use after import
list is the day-to-day inspection command. It prints deterministic rows in a stable order, and it is usually the first thing to run after import.
add is the manual replay surface for one bank row at a time. It is useful when you are recreating statement-backed history and the source evidence is too small or too irregular for a bulk import flow.
backlog tells you which rows are still unreconciled. This is the best command when you want to answer “what is still left to process?”.
coverage goes one step further and tells you whether bank rows are linked into reconciliation records, journal records, both, or neither.
control is the accountant-facing period control view. It combines statement continuity, checkpoint balance math, bank movement totals, unresolved backlog, and coverage counts into one deterministic report.
statement extract, statement parse, and statement verify are the lower-level checkpoint path. Use them when you need to inspect or troubleshoot the underlying statement evidence itself.
Counterparties and reference hints
Two small configuration tables can make bank automation much better over time.
Counterparty aliases let you normalize many name variants to one canonical name, which makes rules and reports easier to read.
Reference extractors pull structured hints such as erp_id or invoice_number_hint out of free-text message or reference fields. When you already know concrete source objects, bus bank add can also store repeatable source_links such as sales_invoice:s6226. Plain --source-id follows the same workspace source_kinds shorthand map as other bookkeeping tools, so the default b -> bank_row mapping makes --source-id b24915 resolve to canonical bank_row:24915. The same source_kinds map also drives short --source-link tokens in related bookkeeping flows. These hints are especially useful for bus-reconcile, because they stay separate from final reconciliation matches.
Typical workflow
For a normal monthly flow, many users do something close to this:
bus bank import --file ./statements/2026-01.csv
bus bank list --month 2026-01
bus bank backlog --month 2026-01 --detail
bus reconcile -o ./out/reconcile-proposals.tsv propose
bus reconcile apply --in ./out/reconcile-proposals.tsv
bus bank coverage --year 2026
bus bank control --month 2026-01 --account acct-1
Files
bus bank owns bank-imports.csv, bank-transactions.csv, and the statement checkpoint dataset. It can also create optional configuration tables for counterparty aliases, reference extractors, and statement-extract profiles. bank-transactions.csv now includes source_links for zero, one, or many pre-reconciliation source-object hints in addition to the older single-value extractor fields.
When a statement-backed replay row has no reliable human-readable counterparty, bus bank add may store blank counterparty fields instead of forcing a fabricated placeholder name. The audit trail stays faithful to the source evidence, while reference, message, IBAN fields, and explicit source_links still remain available for later reconciliation.
Output and flags
These commands use Standard global flags. In practice:
list is most often used as plain terminal output. backlog, coverage, control, and statement parse are the commands that most often benefit from -f json and -o.
When one month or year has more than one statement account in scope, control requires --account so the result stays deterministic. If only one statement account overlaps the selected scope, the command resolves it automatically.
Use --dry-run when you want to preview an import or configuration change without writing datasets.
For the full command and flag matrix, run bus bank --help.
Using from .bus files
Inside a .bus file, write this module target without the bus prefix.
# same as: bus bank import --file ./statements/2026-01.csv
bank import --file ./statements/2026-01.csv
# same as: bus bank backlog --month 2026-01 --detail
bank backlog --month 2026-01 --detail
# same as: bus bank --format json coverage --year 2026
bank --format json coverage --year 2026