134 lines
3.5 KiB
Markdown
134 lines
3.5 KiB
Markdown
# FinTS Connector
|
|
|
|
The FinTS connector can run embedded in the main API or in the separate local
|
|
agent. Embedded mode is the default for local/self-hosted installs, so users do
|
|
not need to start a second process.
|
|
|
|
The privacy tradeoff is explicit:
|
|
|
|
- Embedded mode: the API process receives PIN/TAN inputs while a FinTS job runs.
|
|
- Separate local-agent mode: PIN/TAN inputs stay in the separate local process.
|
|
|
|
In both modes, PINs are not stored in the database. Normalized observations are
|
|
stored only when you import them.
|
|
|
|
## Required Inputs
|
|
|
|
- `--blz` or `MOUSEHOLD_FINTS_BLZ`: bank identifier/BLZ.
|
|
- `--server` or `MOUSEHOLD_FINTS_SERVER`: FinTS endpoint URL.
|
|
- `--bank-user-id` or `MOUSEHOLD_FINTS_USER_ID`: your bank login ID.
|
|
- PIN: prompted interactively by default, or provided through `MOUSEHOLD_FINTS_PIN`.
|
|
- `--product-id` or `MOUSEHOLD_FINTS_PRODUCT_ID`: required by python-fints 4+.
|
|
Register a product ID with Deutsche Kreditwirtschaft/ZKA before connecting.
|
|
- Optional `--customer-id`, `--tan-medium`, and `--product-version`.
|
|
|
|
## comdirect
|
|
|
|
The web UI has a `comdirect` preset.
|
|
|
|
Current values:
|
|
|
|
```text
|
|
BLZ: 20041111
|
|
FinTS endpoint: https://fints.comdirect.de/fints
|
|
Bank user ID: your comdirect Zugangsnummer
|
|
Customer ID: leave empty
|
|
```
|
|
|
|
If your account uses a different comdirect/Commerzbank GF comdirect BLZ, replace
|
|
the preset BLZ before fetching accounts.
|
|
|
|
## Local State
|
|
|
|
The connector stores non-PIN client state in:
|
|
|
|
```text
|
|
~/.config/mousehold/fints/<profile>.json
|
|
```
|
|
|
|
This caches bank parameter data, selected TAN mechanism, and selected TAN
|
|
medium so repeated syncs do not ask the same setup questions. The file is
|
|
written with mode `0600`.
|
|
|
|
Use `--no-state` for a one-off session without reading or writing that cache.
|
|
|
|
## Commands
|
|
|
|
The browser UI uses the embedded API route by default:
|
|
|
|
```text
|
|
http://127.0.0.1:8001/agent/fints/...
|
|
```
|
|
|
|
To use a separate local-agent HTTP bridge instead:
|
|
|
|
```sh
|
|
mousehold-agent serve --host 127.0.0.1 --port 8765
|
|
```
|
|
|
|
Then set `VITE_LOCAL_AGENT_URL=http://127.0.0.1:8765` in
|
|
`apps/web/.env.development`.
|
|
|
|
List accounts:
|
|
|
|
```sh
|
|
mousehold-agent fints-accounts \
|
|
--profile my-bank \
|
|
--blz <bank-blz> \
|
|
--server <fints-endpoint-url> \
|
|
--bank-user-id <bank-login-id> \
|
|
--with-balances
|
|
```
|
|
|
|
Display transactions:
|
|
|
|
```sh
|
|
mousehold-agent fints-transactions \
|
|
--profile my-bank \
|
|
--blz <bank-blz> \
|
|
--server <fints-endpoint-url> \
|
|
--bank-user-id <bank-login-id> \
|
|
--iban <iban> \
|
|
--start-date 2026-06-01 \
|
|
--end-date 2026-06-27
|
|
```
|
|
|
|
Sync transactions into Mousehold:
|
|
|
|
```sh
|
|
mousehold-agent sync-fints \
|
|
--api-url http://127.0.0.1:8001 \
|
|
--connection-id <connection-id> \
|
|
--household-id <household-id> \
|
|
--owner-user-id <user-id> \
|
|
--source-account-id <account-id> \
|
|
--profile my-bank \
|
|
--blz <bank-blz> \
|
|
--server <fints-endpoint-url> \
|
|
--bank-user-id <bank-login-id> \
|
|
--iban <iban> \
|
|
--days 30 \
|
|
--display
|
|
```
|
|
|
|
## TAN Handling
|
|
|
|
If the bank returns a TAN challenge, the CLI prints the challenge text and asks
|
|
for the TAN. Decoupled app confirmation flows prompt you to confirm in the
|
|
banking app and press Enter. Binary challenge images are written under:
|
|
|
|
```text
|
|
~/.config/mousehold/fints/challenges/
|
|
```
|
|
|
|
## Ledger Mapping
|
|
|
|
FinTS transactions are imported as `source_type = "fints"` and
|
|
`status = "confirmed"`.
|
|
|
|
- Positive bank movements become `income`.
|
|
- Ordinary negative bank movements become `expense`.
|
|
- Negative movements mentioning PayPal, Klarna, or credit-card providers become
|
|
`liability_payment`, so they can later be linked to prior obligations instead
|
|
of becoming duplicate household expenses.
|