Zu Content springen
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

Wie verbinde ich Finmatics via REST API?

Nutzen Sie die Finmatics REST-API für nahtlose Integrationen. Erfahren Sie hier alles zu Authentifizierung Endpoints und Dokumentation.


Wo finde ich die Finmatics API-Dokumentation?

Wenn Sie noch keine Finmatics Zugangsdaten besitzen

Melden Sie sich mit den nachfolgenden Demo-Benutzerdaten unter https://app.finmatics.com/ an:

  • Benutzername: demo
  • Passwort: demodemo

Danach können Sie die gewünschte Dokumentation aufrufen:

Wenn Sie bereits Finmatics Zugangsdaten besitzen

Hängen Sie /api/v1/redoc/ oder /api/v1/swagger/ an Ihre kundenspezifische Finmatics URL an, z.B.:

Postman Collection

Für das Programm Postman bieten wir eine Collection mit den wichtigsten API-Calls an:

Um einen API-Benutzer anzufordern, wenden Sie sich bitte an customers@finmatics.com.

Limitierungen

Die API hat ein Rate Limit von 1000 Requests pro Minute für generelle Anfragen und 100 Requests pro Minute für Authentifizierung (token_auth).

Welche Endpoints stehen zur Verfügung?

Die nachfolgenden Endpoints verwenden die Base-URL des Produktivsystems. Für die Sandbox muss die Base-URL auf test.finmatics.com gesetzt werden.

Wie ist die Integration strukturiert?

Struktur-Hierarchie

Finmatics bietet eine flexible Struktur für die Einrichtung des Systems:

  1. Unternehmen (Kunde)
  2. Mandanten (Subunternehmen, Standorte)
  3. Stammdaten (Geschäftspartner, Sachkonten, Kostenstellen – dem Mandanten zugeordnet)
  4. Belegtypen (ER, AR, Kasse – dem Mandanten zugeordnet)
  5. Belege (Befinden sich in den Belegtypen)

In der API können Daten eines gesamten Unternehmens oder pro Mandant abgeholt werden. Ein Filtern auf Mandantenebene wird empfohlen.

Finmatics API Struktur Diagramm

 

Objekte und UUIDs

Jedes Objekt hat eine eigene UUID als eindeutigen Identifier. In jedem Objekt wird das zugeordnete Objekt als UUID mitgeliefert.

Beispiel Mandant:

1 {
2 "id": "11111111-2222-3333-4444-555555555555",
3 "idExternal": "string",
4 "clientName": "Test",
5 "clientNo": "1234",
6 "company": "11111111-2222-3333-4444-555555555555",
7 }

  • id: UUID des Objekts
  • company: UUID des zugeordneten Unternehmens
  • idExternal: Kann für das Matching mit Ihrem Partnersystem genutzt werden.

Wie funktioniert die Authentifizierung?

Die API arbeitet mit JWTs (JSON Web Tokens), die eine Woche gültig sind.

  1. Token erstellen: POST request an https://api.finmatics.com/api/v1/token_auth/
    Payload: {"username":"","password":""}
  1. Token aktualisieren: POST request an https://api.finmatics.com/api/v1/token_refresh/
    Payload: {"token":"TOKEN"}

Response:

1 Status 200 OK
2 {
3 "pk": 1234567890,
4 "token": "eyJhb...RN1xT"
5 }

Der Token muss im Header als Authorization: jwt=TOKEN mitgeschickt werden.

Empfehlung: Nutzen Sie Refreshes und erstellen Sie Tokens sparsam (z.B. ein Token für mehrere Synchronisierungen).

Wie verwalte ich Stammdaten?

Unternehmen

Wird meist von Finmatics vorbereitet. Adressen oder USt-IdNr können aktualisiert werden.

Mandanten

  • Endpoint: https://api.finmatics.com/api/v1/clients/
  • Optionen: POST, GET, PATCH, PUT, DELETE
  • Pflichtfelder: Name, Nummer, Zuordnung zum Unternehmen.
  • Tipp: Setzen Sie noDefaultBookingTypes auf false, um automatisch ER, AR und KA Belegtypen zu erstellen.

Belegtypen

Geschäftspartner

  • Endpoint: https://api.finmatics.com/api/v1/partners/
  • Pflichtfelder: Belegsymbol, Name, Nummer, Mandantenzuordnung.
  • Empfehlung: Übergeben Sie so viele Daten wie möglich (Adresse, USt-IdNr), um die KI-Zuweisung zu optimieren.

Bankdaten

Können einzeln https://api.finmatics.com/api/v1/partners/{id}/banks oder als Bulk https://api.finmatics.com/api/v1/partner_banks/ erstellt werden. Das Land muss zwingend angegeben werden.

Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Sachkonten & Kostenstellen

Wie verarbeite ich Belege?

Belege können einzeln oder als Bulk übertragen werden. Die Verarbeitung erfolgt asynchron; prüfen Sie den Status regelmäßig. Felder werden in der API-Antwort nur angezeigt, wenn sie in der Erfassungsmaske konfiguriert sind. 

Lesen Sie für weitere Informationen folgenden Artikel:

Eine Ausnahme bilden customFields, die auch ohne Konfiguration angezeigt werden. 

Felder Konfiguration in Finmatics

 

Abholen von Belegdaten

  • Endpoint: https://api.finmatics.com/api/v1/documents/
  • Filter-Parameter:
    • status: finished, processing, error
    • verificationLevel: 10 (Maschine), 20 (Buchhalter)
    • exported: true/false
    • client: UUID des Mandanten
    • creationDate__gte: Datum (z.B. 2023-01-01)
    • fields (=default/all) - Um all (=all) oder nur die wichtigsten (=default) Belegdaten anzuzeigen
    • splitted (=boolean) - um nur getrennte Belege abholen (false)
    • reverseTax (=boolean) - Um die Steuersätze bei Reverse Charge richtig zu berechnen (true) sonst 0,- (false)

Abholen von fertig verarbeiteten Belegen

GET Call: https://api.finmatics.com/api/v1/documents/?status=finished&verificationLevel__gte=20&exported=false&splitted=false

Abgeholte Belege als "exportiert" markieren

Senden Sie nach dem Abholen einen PATCH-Request, um ein erneutes Abholen zu verhindern:
Call: https://api.finmatics.com/api/v1/documents/{uuid}/

Payload:

1 {
2 "exported": true
3 } 

Belegbilder abholen

Endpoint: https://api.finmatics.com/api/v1/documents/{uuid}/pdf/
Optionen: GET

Abholen von Belegen im “Notfall”

Zusätzlich ist es sinnvoll, Kunden eine Möglichkeit zu bieten, einzelne Belege sofort abzuholen, egal in welchem Status sie sich befinden. Dafür kann zum Beispiel ein GET Call mit Einschränkung auf einen Mandanten und ein Erstellungsdatum verwendet werden:
https://api.finmatics.com/api/v1/documents/?client={uuid}&exported=false&creationDate__gte=2023-01-01 

Trainingsdaten?

Trainingsdaten hochladen

Verbuchte Belege als Trainingsdaten zurückschreiben

Endpoint: https://api.finmatics.com/api/v1/documents/
Optionen: PATCH (alternativ PUT)

Sobald ein Beleg im ERP final verbucht ist, senden Sie die korrekten Daten per PATCH an Finmatics zurück, um die KI zu trainieren.

Alternativ kann auch ein PUT Call verwendet werden. Dabei müssen alle Datenfelder mit gesendet werden, auch wenn keine Veränderung stattgefunden hat.

Wichtig: Setzen Sie "verificationLevel": 20, damit die Daten als Training akzeptiert werden. Um den Prozess zu vereinfachen, sollten Positionen immer in einer "items" list übergeben werden, selbst wenn es nur eine Position ist. 

Call: PATCH https://api.finmatics.com/api/v1/documents/{uuid}/

Beispiel Payload:

1 {
2 "currency": "EUR",
3 "invoiceCategory": debit,
4 "invoiceDate": "2023-02-12",
5 "invoiceNo": "123456789",
6 "items": [
7 {
8 "position": 1,
9 "accountNumber": "10",
10 "bookingText": "TEXT",
11 "taxPercent": 10,
12 "grossAmount": 100,
13 "netAmount": 90,
14 "taxAmount": 10,
15 },
16 {
17 "position": 2,
18 "accountNumber": "20",
19 "bookingText": "TEXT2",
20 "taxPercent": 10,
21 }
22 ],
23 "partnerName": "Partner-1",
24 "partnerNo": "1000",
25 "totalGrossAmount": 200,
26 "totalNetAmount": 180,
27 "totalTaxAmount": 20,
28 "vat": "AT123456789",
29 "verificationLevel": 20,
30 }

Tipps & Tricks

  • Trailing Slash: Beenden Sie URLs immer mit / (z.B. /api/v1/clients/), um Redirects zu vermeiden.
  • Frontend-Check: API-User haben Zugriff auf das Web-Frontend. Nutzen Sie dies, um API-Daten visuell zu verifizieren.
  • Swagger: Nutzen Sie die Swagger-Doku für schnelle Tests von GET-Calls.

Bei technischen Fragen kontaktieren Sie bitte support@finmatics.com.