Ratgeber › Rechnungsautopilot

FreeFinance API: was die Schnittstelle kann

Die REST-API 2.0 von FreeFinance: Zugang per Technical User, wichtige Endpunkte für Rechnungen und Zahlungen, fehlende Funktionen und Praxis-Tipps.

Stand: 15.10.2026 · Redaktion MW Lab · Allgemeine Information, keine Steuerberatung. Prüfen Sie Ihren Einzelfall mit Ihrer Steuerberatung.

FreeFinance bietet eine öffentliche REST-API. Damit lassen sich Kunden, Rechnungen, Zahlungen und Belege aus eigenen Programmen anlegen und lesen. Dieser Artikel fasst zusammen, was die Schnittstelle kann, was fehlt und worauf Entwickler achten sollten. Grundlage sind die offizielle Dokumentation und die veröffentlichte OpenAPI-Spezifikation, Stand Oktober 2026.

Eckdaten der FreeFinance API

Punkt	Stand Oktober 2026
Version	API 2.0.0, Beta seit 2.12.2025; die öffentliche Spezifikation trägt die Kennung 2.0.0-beta10. Die Legacy-API 1.18 läuft aus, der Support endet laut Hersteller Ende 2026.
Basis-Pfad	`/api/2.0/`, gefolgt vom Modulkürzel, meist pro Mandant: `/clients/{id}/inv/invoices`
Anmeldung	OAuth2/OpenID Connect (Keycloak unter accounts.freefinance.at), Bearer-Token in jedem Aufruf
Zugang für Skripte	„Technical User“ mit Client-Credentials, kostenlos pro Mandant
Zugang für Apps	Authorization-Code-Flow, kostenpflichtig und auf Anfrage
Rechnungsmodul	nur in höheren Tarifen (laut Doku ab Plus); sonst antwortet die API mit 403
Paging	Standard 100, maximal 500 Einträge pro Abfrage (`limit`, `offset`)
Testumgebung	Demo-System, Zugang über den Hersteller
Support	über den Partner BüRomy GmbH, kostenpflichtig; Erstgespräch 15 Minuten kostenlos

Zugang einrichten: der Technical User

Für eigene Skripte und kleine Integrationen ist der Technical User der vorgesehene Weg. Sie legen ihn im jeweiligen Mandanten unter Mein Profil › Benutzer & Berechtigung › Verbundene Apps an und erhalten eine Client-ID und ein Client-Secret. Der Technical User hat kein Passwort für die Oberfläche. Die Zugangsdaten laufen nicht ab, lassen sich aber durch Löschen des Technical Users widerrufen.

Mit Client-ID und Secret holen Sie beim Identity-Provider ein Access-Token. Die Adresse ermitteln Sie über den Endpunkt /auth/issuer, der ohne Anmeldung erreichbar ist. Das Token gilt laut Dokumentation typischerweise 300 Sekunden; beim Client-Credentials-Flow gibt es kein Refresh-Token, Sie fordern einfach ein neues an. Wichtig: Die numerische Mandanten-ID in den Pfaden ist nicht dieselbe wie die Client-ID für die Anmeldung. Welche Mandanten erreichbar sind, liefert GET /clients.

# 1) Token-Adresse ermitteln (liefert IDP-URL und Realm)
curl -s "https://<HOST>/api/2.0/auth/issuer"

# 2) Access-Token holen (Client-Credentials des Technical Users)
curl -s -X POST "<ISSUER_URL>/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id=<API_CLIENT_ID> \
  -d client_secret=<CLIENT_SECRET>

# 3) Rechnungen lesen (Token gilt typischerweise 300 Sekunden)
curl -s "https://<HOST>/api/2.0/clients/<MANDANT_ID>/inv/invoices?limit=100&offset=0" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Alle Werte in spitzen Klammern sind Platzhalter. Secrets gehören in eine Umgebungsvariable oder einen Secret-Speicher, nie in Code oder Logs.

Was die API kann

Rechnungen und Zahlungen

Rechnungen anlegen, lesen und löschen (Entwürfe), finalisieren, stornieren, PDF und XML abrufen. Dazu Statistiken über Rechnungen.
Zahlungen zu einer Rechnung erfassen (über ein Zahlungsmittelkonto oder einen Kassenbeleg), auflisten und stornieren.
Externe Rechnungen mit eigener Nummer, etwa aus einem Shop, die sofort abgeschlossen sind.
Weitere Dokumente: Gutschriften, Angebote, Auftragsbestätigungen und Lieferscheine.
Lesend: Zahlungsbedingungen, Layouts, Nummernkreise und Mahnstufen.

Stammdaten, Belege und mehr

Kunden und Lieferanten inklusive Adressen, Artikel und Artikelkategorien.
Beleg-Upload in die Staging-Liste von „Buchen vom Foto/PDF“ sowie Dateien und Ordner im Doku-Archiv.
Kontoauszüge: Kopfdaten und Zeilen lesen und anlegen; Zeilen mit bereits vorhandener Transaktions-ID werden übersprungen.
Registrierkasse: Kassen, Belege und Tagesabschlüsse.
Konten, Steuersätze, Zahlungsmittelkonten und Tags.

Was (noch) fehlt

Kein Mailversand: Es gibt keinen Endpunkt, der eine Rechnung per E-Mail an den Kunden schickt. Den Versand muss Ihre Anwendung selbst übernehmen.
Keine Abo-Vorlagen: Die Abo-Rechnung aus der Oberfläche ist über die API nicht erreichbar. Zeitplan und Vorlagen müssen außerhalb von FreeFinance liegen.
Keine Mahnungen erzeugen: Mahnstufen lassen sich nur lesen.
Keine Webhooks: Änderungen müssen per Abfrage (Polling) erkannt werden.
Keine dokumentierten Rate-Limits: Planen Sie defensiv mit Pausen und Wiederholungen.

Die Spezifikation ist im Beta-Stadium und wächst: Kontoauszüge, Gutschriften und Angebote kamen seit den ersten veröffentlichten Versionen dazu. Prüfen Sie vor dem Bau einer Integration die aktuelle openapi.json.

Praxis-Tipps für Entwickler

Im Demo-System entwickeln
Auf dem Produktivsystem lassen sich falsch angelegte Datensätze laut Hersteller nicht löschen, auch nicht solche aus der API. Testen Sie Ihre Integration deshalb zuerst in der Demo-Umgebung.
Finalisieren als endgültig behandeln
Mit dem Finalisieren erhält die Rechnung ihre Nummer und ein PDF. Die Nummer bleibt laut Dokumentation auch dann bestehen, wenn die Rechnung wieder geöffnet wird; ein Endpunkt zum Wiedereröffnen ist in der Spezifikation nicht enthalten. Legen Sie daher zuerst Entwürfe an und finalisieren Sie erst nach Prüfung.
Duplikate verhindern
Die API kennt keinen Idempotenz-Schlüssel für Rechnungen. Speichern Sie eine eigene Kennung (z. B. Vertrag und Abrechnungszeitraum) und prüfen Sie vor dem Anlegen, ob es die Rechnung schon gibt. Ein abgebrochener Lauf darf beim Wiederholen keine zweite Rechnung erzeugen.
Summen mitschicken
Die Dokumentation empfiehlt, beim Anlegen erwartete Summen zur Kontrolle mitzusenden, besonders bei Nettobeträgen. So fallen Rundungs- und Steuerfehler sofort auf.
Fehlercodes ernst nehmen
401 heißt: neues Token holen. 403 kann ein fehlendes Modul im Tarif oder fehlende Berechtigungen bedeuten. 409 meldet eine bereits vergebene Kennung.

Selbst bauen oder fertige Lösung?

Für eine einmalige Datenübernahme oder einen einfachen Export reicht ein Skript. Wer wiederkehrende Rechnungen, Versand und Mahnungen automatisieren will, muss Vorlagen, Zeitplan, Mailversand, Duplikatschutz und Fehlerbehandlung selbst bauen und betreiben. Der Rechnungsautopilot nutzt genau diese API mit einem Technical User: Er verwaltet Abo-Vorlagen außerhalb von FreeFinance, legt fällige Rechnungen an, prüft Empfänger, schlägt Mahnungen vor und versendet über Ihren eigenen Mailserver erst nach Freigabe. Wie Abo-Rechnungen in FreeFinance selbst funktionieren, lesen Sie unter FreeFinance: Abo-Rechnungen automatisieren; ohne Programmierung geht die Anbindung von Shops über Make, siehe FreeFinance mit Shopify verbinden.

Häufige Fragen

Hat FreeFinance Webhooks?

Nein, Stand Oktober 2026 sind keine Webhooks dokumentiert. Änderungen an Rechnungen oder Zahlungen müssen Sie regelmäßig abfragen.

Kostet die FreeFinance API extra?

Der Technical User für den Client-Credentials-Zugang ist kostenlos. Das Rechnungsmodul setzt einen höheren Tarif voraus. Kostenpflichtig sind der Authorization-Code-Flow für Apps und der API-Support über BüRomy.

Kann ich Rechnungen über die API per E-Mail versenden?

Nein. Sie können das PDF abrufen und selbst versenden, etwa über Ihren eigenen Mailserver. Einen Versand-Endpunkt gibt es nicht.

Wie viele Datensätze liefert eine Abfrage?

Standardmäßig 100, maximal 500 pro Seite. Größere Listen holen Sie mit offset seitenweise.

Quellen und weiterführende Links

Das nimmt Ihnen Rechnungsautopilot ab

Der Rechnungsautopilot ergänzt FreeFinance um automatische Abo-Läufe, Empfänger-Prüfung, Freigabe-Queue, Mahn-Vorschläge und einen Wochenreport.

30 Tage kostenlos testen, keine Kreditkarte, jederzeit kündbar.

30 Tage kostenlos testen Mehr zu Rechnungsautopilot

Weiterlesen

Haftungsausschluss: Dieser Artikel dient der allgemeinen Information und ersetzt keine steuerliche oder rechtliche Beratung. Gesetze, Formate und Software ändern sich; Angaben ohne Gewähr. Punkte mit „mit Steuerberatung klären“ sind bewusst nicht abschließend beantwortet. Shopify, PayPal, Stripe und FreeFinance sind Marken ihrer jeweiligen Inhaber; MW Lab ist mit diesen Unternehmen nicht verbunden.