finanzonline-ts


Read-only TypeScript SDK and CLI for the Austrian FinanzOnline DataBox API.

Quick Start (npx)

Download all unread Bescheide with a single command:

``bash
npx finanzonline-ts sync \
--tid YOUR_TID \
--benid YOUR_BENID \
--pin YOUR_PIN \
--herstellerid ATUxxxxxxxx \
--output-dir ./bescheide \
--erltyp B \
--all
`

Or list documents first:

`bash
npx finanzonline-ts list \
--tid YOUR_TID \
--benid YOUR_BENID \
--pin YOUR_PIN \
--herstellerid ATUxxxxxxxx \
--output-dir /tmp \
--all
`

> Note: You need a FinanzOnline WebService user (not your regular login). Create one in FinanzOnline under Admin → Benutzerverwaltung → Benutzer anlegen → Type "Webservice".

---

This is a TypeScript port of the Python package
finanzonline_databox by
Robert Nowotny (bitranox). Huge thanks for the original implementation and docs.

Features

- Login/logout session handling
- List DataBox documents (Bescheide, Mitteilungen, etc.)
- Download documents as base64-decoded PDF/XML
- CLI with list/download/sync commands
- Layered config: CLI flags → env → .env → TOML
- Strict TypeScript types and error classes

Installation

`bash
pnpm add finanzonline-ts
`

`bash
bun add finanzonline-ts
`

Quick Start

`ts
import { DataboxClient, SessionClient, loadConfig } from "finanzonline-ts";

const { config } = loadConfig();
const sessionClient = new SessionClient({ timeoutSeconds: config.session_timeout });
const databoxClient = new DataboxClient({ timeoutSeconds: config.query_timeout });

const session = await sessionClient.login({
tid: config.tid,
benid: config.benid,
pin: config.pin,
herstellerid: config.herstellerid
});

const entries = await databoxClient.getDatabox(session.sessionId, config, {
erltyp: "B"
});

const pdf = await databoxClient.getDataboxEntry(
session.sessionId,
config,
entries[0].applkey
);
`

CLI Reference

`bash
finanzonline --help
`

$3

`bash
finanzonline list --erltyp B --days 30
finanzonline list --all
finanzonline list --read
`

Defaults: list/sync only show UNREAD unless --read or --all is provided.

$3

`bash
finanzonline download --output ./downloads
`

$3

`bash
finanzonline sync --erltyp B --days 7
finanzonline sync --all
`

Configuration

Config is loaded in priority order:

1. CLI flags
2. Environment variables
3. .env in current/parent directories
4. finanzonline.toml in current/parent directories

Compatibility notes:
- The original Python package uses a layered config system; this port uses a
single finanzonline.toml plus .env discovery.

$3

`bash
FINANZONLINE__TID=12345678
FINANZONLINE__BENID=WEBUSER
FINANZONLINE__PIN=secret
FINANZONLINE__HERSTELLERID=ATU12345678
FINANZONLINE__OUTPUT_DIR=/tmp/finanzonline
FINANZONLINE__SESSION_TIMEOUT=30
FINANZONLINE__QUERY_TIMEOUT=30
`

$3

`toml
[finanzonline]
tid = "12345678"
benid = "WEBUSER"
pin = "secret"
herstellerid = "ATU12345678"
output_dir = "/tmp/finanzonline"
session_timeout = 30
query_timeout = 30
`

$3

`bash
finanzonline \
--tid 12345678 \
--benid WEBUSER \
--pin secret \
--herstellerid ATU12345678 \
--output-dir /tmp/finanzonline
`

SDK Usage

`ts
import { DataboxClient, SessionClient } from "finanzonline-ts";

const sessionClient = new SessionClient({ timeoutSeconds: 30 });
const databoxClient = new DataboxClient({ timeoutSeconds: 30 });

const session = await sessionClient.login({
tid: "12345678",
benid: "WEBUSER",
pin: "secret",
herstellerid: "ATU12345678"
});

const entries = await databoxClient.getDatabox(session.sessionId, {
tid: "12345678",
benid: "WEBUSER",
pin: "secret",
herstellerid: "ATU12345678"
});
`

Edge Cases & Warnings

- Invalid credentials return rc=-4 and throw InvalidCredentialsError.
- Expired sessions return rc=-1 and throw SessionExpiredError.
- Maintenance mode responses include /wartung/ and throw MaintenanceError.
- Network timeouts throw NetworkError.
- Invalid XML responses throw InvalidXmlError`.

License

MIT

Credits

- Original Python implementation:
bitranox/finanzonline_databox