Ratgeber › Rechnungsautopilot
FreeFinance Technical User anlegen: Anleitung
Technical User in FreeFinance anlegen: Voraussetzungen, Menüpfad, Client-ID und Secret, Verbindungstest, Widerruf und typische Fehler wie 401 und 403.
Stand: · Redaktion MW Lab · Allgemeine Information, keine Steuerberatung. Prüfen Sie Ihren Einzelfall mit Ihrer Steuerberatung.
Ein Technical User ist ein Zugang zu Ihrem FreeFinance-Mandanten, der nicht für Menschen, sondern für Programme gedacht ist. Er besteht aus einer Client-ID und einem Client-Secret, hat kein Passwort und kann sich nicht in der Oberfläche anmelden. Damit greift ein Programm über die offizielle REST-API auf Kunden, Rechnungen oder Zahlungen zu. Laut FreeFinance-Entwicklerseite ist der Technical User kostenlos und wird pro Mandant angelegt. Diese Anleitung gilt für jedes Programm, das einen Technical User braucht, ob eigenes Skript, Integration oder Add-on wie der Rechnungsautopilot.
Menünamen können sich mit Updates von FreeFinance ändern. MW Lab ist unabhängig von FreeFinance.
Voraussetzungen
- Berechtigung im Mandanten: Anlegen darf laut API-Dokumentation ein Benutzer, der externe Zugänge verbinden darf, in der Praxis meist der Administrator des Mandanten.
- Ersteinrichtung abgeschlossen: Solange der Registrierungsassistent eines neuen Mandanten offen ist (Land, Buchhaltungsart, Paket, AGB), leitet FreeFinance auf den Assistenten um. Schließen Sie ihn zuerst ab.
- Tarif mit Rechnungsmodul: Für Rechnungen über die API braucht der Mandant laut FreeFinance einen höheren Tarif (derzeit ab Plus). Ohne dieses Modul antwortet die Schnittstelle bei Rechnungsabfragen mit 403. Maßgeblich ist die aktuelle Tarifübersicht von FreeFinance.
Technical User anlegen: Schritt für Schritt
Verbundene Apps öffnen
Melden Sie sich in FreeFinance an und öffnen Sie im Menü Mein Profil › Benutzer & Berechtigung › Verbundene Apps. Unten auf der Seite sehen Sie alle Zugänge für Programme, die schon bestehen, mit Benutzerkennung (beginnt mit
service-account-) und Erstelldatum.Technischen Nutzer erstellen
Gibt es noch keinen Zugang, klicken Sie auf Technischen Nutzer erstellen und bestätigen den Dialog. FreeFinance legt den Technical User an und zeigt anschließend die Zugangsdaten. Gibt es bereits einen, öffnen Sie dessen Daten über das Lupen-Symbol in der Zeile.
Drei Werte notieren
Der Dialog enthält die Client-ID (Format etwa
21334_21715633), das Client-Secret und Ihre Mandantennummer (nur die Zahl, etwa21334). Die Mandantennummer steht in jeder API-Adresse; die Client-ID dient nur der Anmeldung. Diese Verwechslung ist der häufigste Einrichtungsfehler.Secret direkt ins Zielprogramm übertragen
Kopieren Sie Client-ID und Secret unmittelbar in das Programm, das den Zugang braucht. Achten Sie dabei auf Leerzeichen am Anfang oder Ende. Legen Sie keine Kopie in Mails, Chats oder Tabellen ab.
Verbindung testen
Im Rechnungsautopilot tragen Sie unter Einstellungen › FreeFinance Mandantennummer, Client-ID und Client-Secret ein und klicken auf Verbindung testen. Der Test liest Ihre Kunden aus FreeFinance und meldet bei Erfolg, wie viele er gefunden hat; dabei wird nichts geschrieben. Client-ID und Secret werden verschlüsselt gespeichert (AES-256-GCM) und danach nur noch mit den letzten vier Zeichen angezeigt.
Widerrufen und erneuern
Die Zugangsdaten eines Technical Users laufen laut Dokumentation nicht ab. Ungültig werden sie erst, wenn Sie den Technical User löschen: unter Verbundene Apps über das Papierkorb-Symbol in seiner Zeile. Ab diesem Moment schlägt jede Anmeldung mit diesen Daten fehl.
Für eine Rotation, etwa nach einem Personalwechsel oder wenn das Secret versehentlich weitergegeben wurde, löschen Sie den alten Technical User, legen einen neuen an und tragen die neuen Daten in allen Programmen ein, die diesen Mandanten nutzen. Prüfen Sie danach in jedem Programm die Verbindung. Nutzen Sie ein Programm nicht mehr, entfernen Sie den Zugang ebenfalls.
Häufige Fehler und Lösungen
| Fehler | Ursache | Lösung |
|---|---|---|
| 401 Unauthenticated, Anmeldung schlägt fehl | Client-ID oder Secret falsch kopiert, Leerzeichen am Ende, Technical User inzwischen gelöscht | Werte über das Lupen-Symbol neu kopieren; wenn der Zugang gelöscht ist, neuen anlegen |
| 403 bei jedem Aufruf | Falsche Mandantennummer, häufig die Client-ID statt der Zahl davor | Nur die numerische Mandantennummer eintragen; zugängliche Mandanten liefert GET /clients |
| 403 nur bei Rechnungen | Rechnungsmodul fehlt im Tarif oder Berechtigung fehlt | Tarif in FreeFinance unter Mein Abo prüfen, gegebenenfalls auf einen Tarif mit Rechnungsmodul wechseln |
| Programm findet keine Daten | Programm zeigt auf das Demo-System statt auf Ihr Produktivsystem | Adresse der Schnittstelle im Programm prüfen |
| Weiterleitung zur Registrierung | Ersteinrichtung des Mandanten nicht abgeschlossen | Registrierungsassistenten in FreeFinance abschließen |
Sicherheitshinweise
- Das Secret ist ein Passwort. Schicken Sie es nie per E-Mail oder Chat, auch nicht an Ihre Kanzlei oder an den Support eines Anbieters. Seriöse Anbieter fragen nicht danach, sondern lassen Sie es selbst eintragen.
- Nur verschlüsselt speichern. Fragen Sie jeden Anbieter, wie und wo er Zugangsdaten ablegt. Der Rechnungsautopilot speichert sie verschlüsselt auf Servern in der EU und zeigt sie im Browser nie im Klartext.
- Weitreichender Zugriff. Ein Technical User greift über die API auf den ganzen Mandanten zu. Geben Sie ihn nur Programmen, denen Sie vertrauen.
- Regelmäßig aufräumen. Prüfen Sie unter Verbundene Apps, welche Zugänge bestehen, und löschen Sie, was nicht mehr gebraucht wird.
Häufige Fragen
Kostet der Technical User etwas?
Nein, laut FreeFinance-Entwicklerseite ist der Technical User für den Mandanten kostenlos. Kostenpflichtig sind der Authorization-Code-Flow für Apps und der API-Support über den Partner BüRomy. Für Rechnungen über die API braucht der Mandant einen Tarif mit Rechnungsmodul.
Kann ich das Secret später noch einmal ansehen?
In unseren Tests ließen sich Client-ID und Secret unter Verbundene Apps über das Lupen-Symbol erneut anzeigen. Behandeln Sie diesen Bereich deshalb wie einen Passwortspeicher und vergeben Sie die nötigen Rechte nur sparsam.
Brauche ich für mehrere Mandanten mehrere Technical User?
Ja. Der Technical User wird pro Mandant angelegt und gilt nur für diesen Mandanten. Betreuen Sie mehrere Mandanten, etwa als Kanzlei, legt jeder Mandant einen eigenen an. Mehr dazu unter Rechnungsautopilot für Kanzleien.
Wie lange gilt ein Token?
Das Access-Token, das ein Programm mit Client-ID und Secret abholt, gilt laut Dokumentation typischerweise 300 Sekunden. Danach holt das Programm einfach ein neues; Sie müssen nichts tun. Technische Details stehen im Artikel FreeFinance API: was die Schnittstelle kann.
Quellen und weiterführende Links
- FreeFinance: Developer-Seite (Technical User, Zugang, Support)
- FreeFinance API-Dokumentation v2 (Authentifizierung, Fehlercodes)
- FreeFinance: Preise und Tarife
- FreeFinance: Schnittstellen
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.
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.