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:

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:

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

pnpm add finanzonline-ts

bun add finanzonline-ts

Quick Start

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

finanzonline --help

List documents

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

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

Download a specific document

finanzonline download <applkey> --output ./downloads

Sync documents

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.

Environment variables

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

TOML config (finanzonline.toml)

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

CLI flags

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

SDK Usage

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