REST-API und Swagger-Dokumentation

Finito stellt eine REST-API bereit, mit der Sie Ihre Daten programmatisch abrufen und pflegen können – etwa um Finito an andere Systeme anzubinden, wiederkehrende Abläufe zu automatisieren oder Rechnungen und Offerten aus einer eigenen Anwendung heraus zu erstellen. Die vollständige Schnittstelle ist als interaktive Swagger-Oberfläche (OpenAPI 3.0) dokumentiert, in der Sie jeden Endpunkt direkt im Browser ausprobieren können.

Zuletzt aktualisiert:

ℹ

Möchten Sie keine eigene Anwendung bauen, sondern eine KI-App wie Claude mit Finito sprechen lassen? Dafür gibt es die MCP-Schnittstelle – mit Finito-Login statt API-Schlüssel.

ℹ

Für wiederkehrende Abläufe brauchen Sie nicht zwingend eine eigene Anwendung: Finito bringt ein eingebautes Automatisierungssystem mit visueller Flow-Programmierung mit. Fehlt eine Funktion, lässt sie sich dort als Block ergänzen. Details finden Sie unter Automatisierungen einrichten.

1. Die Swagger-Oberfläche öffnen

Die interaktive API-Dokumentation erreichen Sie über den API-Host Ihrer Region – ohne Anmeldung an der Weboberfläche:

Region Adresse der Swagger-Oberfläche
Schweiz https://api.finitopro.ch/api/v1/schema/swagger-ui/
Polen https://api.finitopro.pl/api/v1/schema/swagger-ui/

Das reine, maschinenlesbare OpenAPI-Schema (z. B. zum Import in Postman, Insomnia oder einen Code-Generator) finden Sie unter /api/v1/schema/ desselben Hosts.

ℹ

Verwenden Sie für alle Anfragen den passenden Host Ihrer Region – https://api.finitopro.ch bzw. https://api.finitopro.pl. Oben in der Swagger-Oberfläche lässt sich der Server über das Auswahlfeld «Servers» umschalten.

2. Authentifizieren

Fast alle Endpunkte setzen eine Authentifizierung mit einem API-Schlüssel voraus. Der Schlüssel ist an Ihre Organisation gebunden – jede Anfrage wirkt genau auf die Organisation, zu der der Schlüssel gehört.

API-Schlüssel erstellen

API-Schlüssel erstellen Sie selbst direkt in Finito – Sie benötigen dafür die Berechtigung zur Organisationsverwaltung.

  1. Öffnen Sie Einstellungen und wählen Sie in der Gruppe Organisation das Modul «API-Schlüssel».
  2. Vergeben Sie einen Namen (damit Sie mehrere Schlüssel auseinanderhalten können) und klicken Sie auf «Schlüssel erstellen».
  3. Kopieren Sie den Schlüssel sofort und bewahren Sie ihn sicher auf – aus Sicherheitsgründen wird er später nicht mehr vollständig angezeigt.
  4. Einen nicht mehr benötigten Schlüssel können Sie hier jederzeit widerrufen; Integrationen, die ihn verwenden, funktionieren danach nicht mehr.

Schlüssel verwenden

  1. Klicken Sie in der Swagger-Oberfläche oben rechts auf die Schaltfläche «Authorize» (Schloss-Symbol).
  2. Tragen Sie Ihren API-Schlüssel ein und bestätigen Sie mit «Authorize». Ab jetzt sendet Swagger den Schlüssel bei jeder Anfrage mit.
  3. Für eigene Anfragen ausserhalb von Swagger setzen Sie den Schlüssel im Authorization-Header:
    Authorization: api_key IHR_SCHLÜSSEL
ℹ

Für die Nutzung der API benötigen Sie ein aktives Abonnement. Ein Schlüssel wirkt im Namen Ihrer Organisation – behandeln Sie ihn entsprechend vertraulich.

⚠

Behandeln Sie Ihren API-Schlüssel wie ein Passwort. Geben Sie ihn nicht weiter und legen Sie ihn nicht offen in Frontend-Code oder öffentlichen Repositories ab.

3. Aufbau der API

Die Endpunkte sind in fachliche Bereiche gegliedert, die in Swagger als aufklappbare Abschnitte erscheinen. Die wichtigsten sind:

Bereich Zweck
Organization Profil der aktuellen Organisation abrufen.
Clients Kundinnen und Kunden anlegen und verwalten.
Products & Services Katalog wiederverwendbarer Produkte und Dienstleistungen pflegen.
Offer Management Offerten samt Positionen, Gruppen und PDF erstellen und bearbeiten.
Invoice Management Rechnungen inkl. Positionen, Vorlagen, wiederkehrender Rechnungen und PDF.
Accounting Kontenplan, MWST-Codes, Buchungsjournal und die noch offenen Zeilen aus dem Kontoauszug – genug, um einen Beleg vollständig zu verbuchen (siehe Abschnitt 6).
Automations Automatisierungs-Flows, Webhooks und Ausführungshistorie.
Inquiry Management / Leads Anfragen und Leads erfassen und verwalten.
Status Öffentlicher Health-Check mit Version und konfiguriertem Land.
ℹ

Die Swagger-Oberfläche zeigt bewusst nur einen Ausschnitt der gesamten API – die für die Integration gängigsten Endpunkte. Jeder Endpunkt trägt eine Kurzbeschreibung («summary») und eine ausführlichere Erläuterung.

4. Endpunkte direkt ausprobieren

  1. Klappen Sie den gewünschten Endpunkt mit einem Klick auf die Zeile auf.
  2. Lesen Sie Beschreibung, Parameter und die erwartete Antwort. Klicken Sie dann auf «Try it out».
  3. Füllen Sie die Parameter bzw. den Anfrage-Body (Request Body) aus und klicken Sie auf «Execute».
  4. Swagger zeigt den vollständigen Aufruf (inkl. cURL-Befehl), den HTTP-Statuscode und die Antwort der API an.

5. Belege automatisch verbuchen

Der Bereich Accounting ist so geschnitten, dass eine externe Anwendung – etwa ein Assistent, dem Sie fotografierte Rechnungen zuschicken – einen Beleg von Anfang bis Ende verbuchen kann. Mehr als die API-Adresse und ein API-Schlüssel sind dafür nicht nötig.

Der Ablauf

Schritt Endpunkt
Kontenplan lesen (welche Konten gibt es?) GET /api/v1/expenses/accounts
MWST-Codes lesen (welche Sätze gibt es?) GET /api/v1/accounting/tax-codes
Beleg als Bild oder PDF hochladen POST /api/v1/expenses/scan
Buchungssatz als Entwurf erfassen POST /api/v1/accounting/journal-entries
Buchung ins Hauptbuch verbuchen POST /api/v1/accounting/journal-entries/{uuid}/post
Falsch gebucht? Storno-Gegenbuchung POST /api/v1/accounting/journal-entries/{uuid}/reverse

Alternativ: offene Zeilen aus dem Kontoauszug

Arbeiten Sie mit importierten Kontoauszügen, kann eine Integration stattdessen die noch unverbuchten Zeilen abarbeiten:

Schritt Endpunkt
Kontoauszug hochladen (multipart/form-data) POST /api/v1/accounting/bank-imports
Offene Zeilen holen – mit missing_documents=true nur jene ohne Beleg GET /api/v1/accounting/bank-transactions
Beleg an eine Zeile hängen POST /api/v1/accounting/bank-transactions/{uuid}/create-expense
Kontierung bzw. MWST-Aufteilung setzen PATCH /api/v1/accounting/bank-transactions/{uuid}
Zeile verbuchen POST /api/v1/accounting/bank-transactions/{uuid}/post

Der Auszug muss dafür nicht von Hand in der App hochgeladen werden: Senden Sie die Datei als multipart/form-data mit den Feldern file und bank_account_uuid (das Bankkonto aus dem Kontenplan, z. B. 1020). Das Format erkennt Finito an der Datei selbst – CAMT (ISO 20022, XML) sowie die CSV-Exporte von ZKB und UBS. Die Antwort nennt, wie viele Zeilen neu übernommen wurden (imported) und wie viele als bereits vorhanden erkannt wurden (skipped_duplicates); derselbe Monat darf also ohne Doppelbuchungen erneut gesendet werden.

ℹ

Das Format muss unter Einstellungen → Funktionen → Bank-Importformate freigeschaltet sein – über die API gilt dieselbe Regel wie in der App, sonst wird der Upload mit HTTP 403 abgelehnt. Welche Formate in Frage kommen, nennt GET /api/v1/accounting/bank-import-formats.

MWST richtig übermitteln

⚠

Die MWST gehört immer auf eine eigene Buchungszeile: den Nettobetrag auf das Aufwand- bzw. Ertragskonto, den Steuerbetrag auf das MWST-Konto (1170 Vorsteuer, 2200 Umsatzsteuer) mit tax_code_uuid. Die MWST-Abrechnung summiert genau die Zeilen mit MWST-Code – ein Code auf einer Bruttozeile verfälscht die Abrechnung.

Ein Beleg mit teilweiser MWST wird darum als eine Buchung mit mehreren Zeilen übermittelt: je Steuersatz eine Nettozeile, dazu eine MWST-Zeile, alles gegen eine einzige Zahlungszeile. Bei Zeilen aus dem Kontoauszug drücken Sie dasselbe über splits aus – je Position account_uuid, tax_code_uuid, der Bruttobetrag amount und optional vat_amount, wenn der Beleg einen abweichend gerundeten MWST-Betrag ausweist. Die Hintergründe stehen unter Belege mit teilweiser MWST buchen.

ℹ

Ein Buchungssatz wird zunächst als Entwurf angelegt und erst durch den post-Aufruf ins Hauptbuch übernommen. Bis dahin lässt er sich beliebig korrigieren oder löschen – danach hilft nur noch das Storno. Diese Trennung eignet sich gut, um automatisch erzeugte Buchungen erst von einem Menschen prüfen zu lassen.

6. Konventionen

  • Kein abschliessender Schrägstrich: Sammel-Endpunkte enden ohne «/» (z. B. /api/v1/invoices), Detail-Endpunkte tragen die UUID direkt an (z. B. /api/v1/invoices/{uuid}).
  • Aktualisieren mit PATCH: Bestehende Datensätze ändern Sie per PATCH (nur die übermittelten Felder werden angepasst). Ein PUT wird nicht angeboten.
  • Seitenweise Ergebnisse: Listen sind paginiert – steuern Sie sie über die Parameter page und page_size.
  • UUIDs statt IDs: Datensätze werden über ihre UUID referenziert.
ℹ

Fehlt Ihnen eine Funktion in der Dokumentation? Schreiben Sie an hello@finitopro.ch und teilen Sie uns mit, welchen Endpunkt Sie benötigen – wir dokumentieren ihn oder schalten ihn für Sie frei.

War dieser Artikel hilfreich?