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

Erste Schritte mit der Rest API

Mit diesem Artikel erhalten eine Anleitung zur Einrichtung der REST API mit Finmatics.

Inhalt

 

Was ist eine REST-API? 

Anwendungsprogrammschnittstellen (APIs) ermöglichen die Verwendung der Funktionen eines Computerprogramms durch ein anderes. Sie sind ein Mittel, mit dem zwei verschiedene Programme kommunizieren können. REST-APIs können von der IT für Softwareintegrations- und Automatisierungszwecke verwendet werden.

Wo finde ich die Finmatics API-Dokumentation?

Wenn Sie noch keine Finmatics Zugangsdaten besitzen

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

  • Benutzername: demo
  • Passwort: demodemo

danach können Sie die gewünschte Dokumentations-URL aufrufen:

Wenn Sie bereits Finmatics Zugangsdaten besitzen

Indem Sie /api/v1/redoc/ oder /api/v1/swagger/ an Ihre maßgeschneiderte Finmatics Web-Oberflächen-URL anhängen, z.B.:

Postman

Für das Programm Postman bieten wir eine kleine 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 und 100 für Authentication (token_auth) Requests. Dieses Limit wird regelmäßig geprüft und potentiell weiter heruntergesetzt.

Endpoints im Überblick

Die nachfolgenden Endpoints verwenden die base_url des Produktiv Systems. Für die Sandbox muss lediglich die base_url auf test.finmatics.com gesetzt werden.

Integration

Struktur

Finmatics bietet eine flexible Struktur für die Einrichtung des Systems und der Stammdaten.

  1. An oberster Stelle steht das Unternehmen des Kunden
  2. Danach kommen die einzelnen Mandanten (Subunternehmen, Standorte, …) eines Unternehmen
  3. Diesen Mandanten sind Stammdaten wie Geschäftspartner, Sachkonten, Kostenstellen/Objekte zugeordnet
  4. Am Ende sind auch noch jedem Mandanten Belegtypen wie Eingangsrechnungen, Ausgangrechnungen, Kassabelege, etc. zugeordnet, über welche die Dokumente den jeweiligen Prozessen zugeordnet werden können
  5. In diesen Belegtypen befinden sich dann die entsprechenden Belege des Mandanten

In der API können Daten eines gesamten Unternehmens oder pro Mandant abgeholt werden.
Ein Filtern auf Mandantenebene ist in den meisten Fällen zu empfehlen, wenn zum Beispiel Stammdaten gepflegt oder Belege abgeholt werden sollen.

Nachfolgend eine Veranschaulichung der Struktur:

Restapideutsch.drawio

Objekte und UUIDs

Jedes der oben genannten Objekte hat eine eigene UUID, die als Identifier und Zuordnung im System verwendet wird. Eine UUID ist innerhalb des Objekttyps einzigartig.

  • Ein Beleg ist einem Belegtypen und einem Mandanten zugeordnet.
  • Ein Belegtyp ist einem Mandanten zugeordnet
  • Ein Mandant ist einem Unternehmen zugeordnet
  • Stammdaten sind einem Mandanten zugeordnet

Das bedeutet, dass in jedem Objekt das zugeordnete Objekt über die API, in Form einer UUID, mitgeliefert wird.

Nachfolgend ein Beispiel anhand eines Mandanten:

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 }

  • Die id ist hier die eigene UUID des Objekts
  • Company beinhaltet die UUID des Unternehmens
  • idExternal kann mit einer eigenen system id befüllt werden um ein einfaches Matching mit dem Partnersystem zu erzeugen 

Authentifizierung

Für die Authentifizierung arbeitet die API mit JWTs (JSON Web Tokens), welche eine Woche lang gültig sind. Um einen Token zu erzeugen, muss ein POST request an https://api.finmatics.com/api/v1/token_auth/ gesendet werden.

Über den https://api.finmatics.com/api/v1/token_refresh/ Endpoint kann ein Token aktualisiert werden. Dabei muss der ursprüngliche Token als Payload “token” mitgegeben werden. Die Response ist gleich wie beim Erstellen eines Tokens.

Payload

1 {"username":"","password":""} 

Payload für Refresh

1 {"token":"TOKEN"} 

Response

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

Der Token aus der Response muss dann für alle weiteren Calls als authorization Header mit dem value "jwt=TOKEN" mitgeschickt werden.

Wir empfehlen sparsam mit der Erstellung von Tokens umzugehen und wenn möglich mit refreshes zu arbeiten. Sollten zum Beispiel Geschäftspartner und anschließend Sachkonten abgeglichen werden, so sollte lediglich ein Token für beide Synchronisierungen erstellt werden.

Stammdaten

Stammdaten sind die grundsätzlichen Daten eines Unternehmens, die benötigt werden, damit Belege verarbeitet werden können.

Unternehmen

Das Unternehmen wird meist bereits von Finmatics im System vorbereitet, jedoch können Daten wie Adresse oder USt-IdNr jederzeit aktualisiert werden.

Mandanten

Endpoint: https://api.finmatics.com/api/v1/clients/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Mandanten können jederzeit über die API erstellt, angepasst und gelöscht werden.
Beim Erstellen müssen Name, Nummer und die Zuordnung zum Unternehmen zwingend angegeben werden.

Tipp: Wird das Feld noDefaultBookingTypes auf false gestellt, wird beim Erstellen eines Mandanten auch automatisch ein Belegtyp ER für Eingangsrechnungen, AR für Ausgangsrechnungen und KA für Kassenbelege erstellt.

Belegtypen

Endpoint: https://api.finmatics.com/api/v1/booking_types/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Belegtypen können jederzeit auch manuell für einen Mandanten angelegt oder angepasst werden. Beim Erstellen müssen Belegsymbol (ER, AR, KA, …) und die Zuordnung zum Mandanten zwingend angegeben werden.

Geschäftspartner

Endpoint: https://api.finmatics.com/api/v1/partners/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Geschäftspartner können einzeln oder in bulk (als list) erstellt werden.
Beim Erstellen müssen Belegsymbol (ER, AR, KA), der Name, die Nummer und die Zuordnung zum Mandanten zwingend angegeben werden. Damit die automatische Zuweisung des Geschäftspartners zum Beleg in Finmatics so gut wie möglich funktioniert, wird empfohlen bei der Erstellung so viele Daten wie möglich zu übergeben (Adresse, USt-IdNr, Telefonnummer, etc.).

Geschäftspartner - Bankdaten

Endpoints:

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

Bankdaten können einzeln für den jeweiligen Geschäftspartner oder in Bulk (als list) für mehrere Geschäftspartner erstellt werden.

Beim Erstellen von Bankdaten für einen einzelnen Geschäftspartner werden diese direkt über die ID in der URL dem Geschäftspartner zugeordnet. Dabei muss zwingend das Land angegeben werden.

Beim Erstellen von Bankdaten in Bulk wird der Geschäftspartner nicht in der URL, sondern im Payload über die ID zugeordnet. Zusätzlich muss auch hier das Land zwingend angegeben werden.

Sachkonten

Endpoint: https://api.finmatics.com/api/v1/gl_accounts/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Sachkonten können einzeln oder in Bulk (als list) erstellt werden. Beim Erstellen müssen die Nummer, die Bezeichnung und die Zuordnung zum Mandanten zwingend angegeben werden.

Kostenstellen

Endpoint: https://api.finmatics.com/api/v1/cost_centers/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Kostenstellen können einzeln oder in Bulk (als list) erstellt werden. Beim Erstellen müssen die Nummer und die Zuordnung zum Mandanten zwingend angegeben werden. Sowohl der Name als auch die Nummer sind String Felder und sind daher nicht auf Zahlen eingeschränkt. Wichtig ist jedoch das beim Abholen von Belegen die Nummer übergeben und daher für die Zuordnung relevant ist.

Belege

Endpoint: https://api.finmatics.com/api/v1/documents/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Belege können mit und ohne weiteren Daten einzeln oder in Bulk (als list) übertragen und nach der Verarbeitung jederzeit abgeholt werden. Beim Erstellen eines neuen Beleges müssen die Zuordnung zum Belegtypen oder das Belegsymbol und die Zuordnung zum Mandanten zwingend angegeben werden.

Die Belegverarbeitung erfolgt im System asynchron. Aus diesem Grund sollte nach dem Erstellen einer neuen Belegs regelmäßig überprüft werden, ob die Verarbeitung bereits abgeschlossen ist.

Belegfelder werden nur dann angezeigt, wenn diese dem entsprechenden Belegtypen hinzugefügt wurden. Lesen Sie für weitere Informationen folgenden Artikel:

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

Abholen von Belegdaten

Endpoint: https://api.finmatics.com/api/v1/documents/
Optionen: GET (list/read), PATCH

Belegdaten können jederzeit über die API abgefragt werden. Dabei gibt es verschiedene Parameter die den Verarbeitungsstatus angeben:

  • status - Gibt an ob Finmatics den Beleg maschinell verarbeitet hat (error, processing, finished)
  • verificationLevel - Gibt an ob ein Beleg manuell bestätigt wurde (0 - nicht bestätigt, 10 - maschinell bestätigt, 20 - von Buchhalter bestätigt)
  • exported - Gibt an ob ein Beleg als exportiert markiert wurde
Zusätzlich gibt es noch weitere Filterparameter:
  • client (=uuid) - Um nach Belegen eines einzelnen Mandanten zu filtern
  • creationDate__lte/gte - Um nach Belegen vor oder nach einem bestimmten Zeitpunkt zu filtern
  • fields (=default/all) - Um all (=all) oder nur die wichtigsten (=default) Belegdaten anzuzeigen
  • splitted (=boolean) - Um nur Belege abzuholen welche bereits getrennt wurden (false)
  • reverseTax (=boolean) - Um die Steuersätze bei Reverse Charge richtig zu berechnen (true) sonst 0,- (false)

Abholen von fertig verarbeiteten Belegen

Daraus ergibt sich ein Standard zum Abholen von fertig verarbeiteten Belegen mit folgendem GET Call: https://api.finmatics.com/api/v1/documents/?status=finished&verificationLevel__gte=20&exported=false&splitted=false

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 

Abgeholte Belege als exportiert markieren

Nachdem Belegdaten abgeholt und übernommen wurden, müssen diese über einen PATCH Call als exportiert markiert werden.
Call: PATCH https://api.finmatics.com/api/v1/documents/{uuid}/
Payload:

1 {
2 "exported": true
3 } 

Damit werden diese Belege beim nächsten Abrufen nicht mehr angezeigt und ein doppeltes Abholen von Belegen verhindert. Mit dem PATCH wird auch automatisch das updateDate des Beleges aktualisiert. 

Abholen von Belegbildern

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

Belegbilder können einzeln pro Beleg abgeholt werden und sind Base64 encoded.

Trainingsdaten

Endpoint: https://api.finmatics.com/api/v1/training_data/
Optionen: POST, GET (list/read), PATCH, PUT, DELETE

Trainingsdaten werden als Lerninformation für Finmatics verwendet. Sie ermöglichen eine schnellere und genauere Automatisierung und Auslese von Belegdaten. Trainingsdaten beinhalten historische Belegbilder und Belegdaten.

Trainingsdaten sind genauso wie Belegdaten aufgebaut. Sie können einzeln oder in Bulk (als list) übertragen werden. Um Trainingsdaten mit einem Belegbild hochzuladen, müssen diese mit dem tag “file” und dem Dateipfad hinzugefügt werden. Bei Belegen mit mehreren Positionen müssen diese als “items” in Listen Form übermittelt werden.

1 "items": [
2 {
3 "bookingText": "office supply",
4 "taxPercent":10,
5 "grossAmount":1100,
6 "accountNumber":500,
7 "..."
8 },
9 {
10 "bookingText": "office supply",
11 "netAmount":4000,
12 "..."
13 }
14 ]

Zusätzlich kann als Parameter async=1 mitgegeben werden, um den Upload der Daten im Hintergrund laufen zu lassen. Über den Jobs Endpoint https://api.finmatics.com/api/v1/jobs/ kann dann der Status des Uploads geprüft werden. 

Verbuchte Belege als Trainingsdaten zurück übertragen

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

Eine weitere und sehr wichtige Methode, um die Automatisierung zu erhöhen und Finmatics zu trainieren, ist das Zurückschreiben der Daten von verbuchten Belegen. Dabei geht es darum, dass Daten die von Finmatics übergeben wurden noch einmal verifiziert und ausgebessert werden.
Sobald ein Beleg im ERP-System finalisiert wurde, können die verbuchten Daten an Finmatics zurück gePATCHed und damit für das Training verwendet werden.

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 }

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

Zu Beachten

Damit die Daten für das Training verwendet werden können, muss immer "verificationLevel": 20 übertragen werden, selbst wenn der Beleg dieses Level bereits hat. Um den Prozess zu vereinfachen, sollten Positionen immer in einer "items" list übergeben werden, selbst wenn es nur eine Position ist. Damit kann sichergestellt werden, dass die Daten immer übertragen werden können, egal ob es eine oder mehrere Positionen sind.

Tipps und Tricks

  • Die API Dokumentation bietet eine Vielzahl an Parametern für die meisten Endpoints, anhand welcher Daten gefiltert werden können (z. B.: nur Daten eines Mandanten anzeigen)
  • Die Swagger Dokumentation bietet eine einfache Möglichkeit um GET Calls direkt in der Software zu testen
  • Ein API-User hat vollen Zugriff auf das Finmatics Frontend. Das kann beim Prüfen von Belegen und Daten helfen, da ein direkter Vergleich zwischen dem, was über die API und im Frontend angezeigt wird, verfügbar ist
  • Die API wird mit einem "Trailing Slash" geführt das heißt es sollte am Ende eines Calls (vor den Parametern) immer ein "/" sein. Fehlt dieser führt es zu Weiterleitungen

Bei Fragen oder Informationen zu Erweiterungen, welche hier nicht angeführt sind, kann unser technischer Support unter support@finmatics.com kontaktiert werden.