REST-API

• 1: Dokumente über Filterpfade finden
• 2: OData-Reporting mit Excel und Power Query
• 3: Dokumente als Archiv exportieren und importieren
• 4: API-Benutzer
• 5: Beispiele
• 6: Sicherheit

1 - Dokumente über Filterpfade finden

Überblick

Die Find-API ermöglicht es, Dokumente anhand eines Filterpfads über die FLOWWER-REST-API zu finden. Der Filterpfad verwendet dieselbe Abfragelogik wie die Filterseite und kann dort ohne manuelles Zusammensetzen erstellt und geprüft werden. Die Funktion eignet sich beispielsweise, wenn eine eigene Integration regelmäßig genau die Dokumente abrufen soll, die einer fachlich zusammengestellten Filterkombination entsprechen.

Filterpfad erstellen

1. Öffnen Sie die Filterseite.
2. Wählen Sie die benötigten Merkmale und Werte aus.
3. Prüfen Sie die Ergebnisliste in FLOWWER.
4. Übernehmen Sie den Filterpfad aus der Adresszeile für den API-Aufruf.

Auch Mehrfachauswahlen und ODER-Gruppen sind Bestandteil des Filterpfads und werden bei der Abfrage berücksichtigt.

Abfrage über die REST-API

Die Find-Aktion für Filterpfade ist in der Swagger-Oberfläche des jeweiligen FLOWWER-Kontos dokumentiert:

https://<Ihre-FLOWWER-Kontokennung>.flowwer.de/swagger

Dort finden Sie die für Ihre FLOWWER-Version gültige Route, HTTP-Methode und Request-Struktur. Übergeben Sie den zuvor erstellten Filterpfad an die dort beschriebene Aktion.

Für den Zugriff gelten die normale Authentifizierung der FLOWWER-REST-API und die Berechtigungen des verwendeten API-Benutzers. Zurückgegeben werden nur Dokumente, auf die dieser Benutzer zugreifen darf.

Typischer Ablauf

1. Fachlichen Filter in FLOWWER zusammenstellen und testen.
2. Filterpfad in die eigene Integration übernehmen.
3. Find-API mit den Zugangsdaten eines geeigneten API-Benutzers aufrufen.
4. Die gefundenen Dokumente in der eigenen Anwendung weiterverarbeiten.

Derzeitige Abgrenzung

Dieser Endpunkt verarbeitet Filterpfade der Filterseite. Gespeicherte Suchen und Abfragen der Erweiterten Suche können derzeit nicht über dieselbe Find-Aktion ausgeführt werden. Für tabellarische Reporting-Auswertungen in Excel oder Power Query steht alternativ der OData-Reporting-Endpunkt zur Verfügung.

2 - OData-Reporting mit Excel und Power Query

Überblick

FLOWWER stellt unter /odata/reporting einen schreibgeschützten OData-Endpunkt für Auswertungen bereit. Excel und Power Query können diesen Dienst direkt als OData-Feed verwenden.

Der Dienst stellt ein echtes OData-Service-Dokument, $metadata und Datenmengen wie Documents bereit. Sofern diese Datenmenge in der jeweiligen FLOWWER-Umgebung verfügbar ist, steht für Auswertungen mit Belegaufteilungen zusätzlich DocumentsWithReceiptSplits zur Verfügung.

Der Endpunkt dient ausschließlich der Auswertung. Dokumente oder Dokumenteigenschaften können darüber nicht geändert werden.

Einstieg über die FLOWWER-Filterseite

Auf der Filterseite kann aus dem aktuellen Filterpfad ein passender Reporting-Aufruf erzeugt werden. Der URI-Builder stellt dafür wahlweise bereit:

• eine fertige OData-URI,
• oder vollständigen Power-Query-M-Code.

Dadurch müssen Filter und technische OData-Parameter nicht manuell zusammengesetzt werden.

OData-URI erzeugen

1. Öffnen Sie die Filterseite und stellen Sie die gewünschte Dokumentmenge zusammen.
2. Öffnen Sie den URI-Builder für OData-Reporting.
3. Wählen Sie die gewünschte Datenquelle, beispielsweise Documents oder DocumentsWithReceiptSplits.
4. Kopieren Sie die erzeugte OData-URI.
5. Verwenden Sie die URI in Excel, Power Query oder einem anderen OData-fähigen Werkzeug.

Power-Query-Code erzeugen

1. Stellen Sie auf der Filterseite den gewünschten Filterpfad zusammen.
2. Lassen Sie den passenden Power-Query-M-Code erzeugen.
3. Kopieren Sie den Code vollständig.
4. Öffnen Sie in Excel den Power-Query-Editor und legen Sie eine leere Abfrage an.
5. Öffnen Sie den Erweiterten Editor, ersetzen Sie den vorhandenen Inhalt durch den kopierten Code und bestätigen Sie die Abfrage.

Direkter Zugriff auf den Dienst

Der Basisendpunkt lautet:

https://<Ihre-FLOWWER-Kontokennung>.flowwer.de/odata/reporting

Typische Unteradressen sind:

https://<Ihre-FLOWWER-Kontokennung>.flowwer.de/odata/reporting/$metadata
https://<Ihre-FLOWWER-Kontokennung>.flowwer.de/odata/reporting/Documents
https://<Ihre-FLOWWER-Kontokennung>.flowwer.de/odata/reporting/DocumentsWithReceiptSplits

Über OData-Query-Optionen kann die Datenmenge weiter eingeschränkt oder sortiert werden. Für den normalen Einstieg empfiehlt sich der URI-Builder auf der Filterseite, da er den aktuellen Filter bereits in eine passende Abfrage überführt.

Documents und DocumentsWithReceiptSplits

Documents

Documents liefert Dokumentdaten auf Dokumentebene. Diese Datenmenge eignet sich beispielsweise für Übersichten zu Lieferanten, Beträgen, Statuswerten und Fristen.

DocumentsWithReceiptSplits

DocumentsWithReceiptSplits bezieht zusätzlich die Belegaufteilung ein. Diese Datenmenge eignet sich für Auswertungen nach Konto, Kostenstelle, Kostenträger oder einzelnen Aufteilungspositionen.

Durch die zusätzlichen Positionen kann ein Dokument in dieser Ausgabe mehrfach vorkommen.

Berechtigungen und Aktualisierung

Der OData-Abruf erfolgt im Kontext der verwendeten FLOWWER-Zugangsdaten. Es werden daher nur Dokumente und Daten ausgegeben, auf die dieser Benutzer zugreifen darf.

Power Query kann die Abfrage später erneut ausführen. Dadurch lässt sich eine einmal eingerichtete Arbeitsmappe mit den jeweils aktuellen FLOWWER-Daten aktualisieren.

Abgrenzung zu FlexReport

FlexReport erstellt Auswertungen direkt innerhalb von FLOWWER und kann Ergebnisse als Excel- oder CSV-Datei exportieren. Der OData-Endpunkt ist insbesondere dann geeignet, wenn eine Excel- oder Power-Query-Auswertung dauerhaft mit FLOWWER verbunden und wiederholt aktualisiert werden soll.

3 - Dokumente als Archiv exportieren und importieren

Überblick

FLOWWER kann Dokumente einschließlich der zugehörigen Informationen als Archiv exportieren und später wieder importieren. Die Funktion steht über die REST-API und über die entsprechenden Befehle des FLOWWER-Agent zur Verfügung.

Der Export eignet sich beispielsweise für die Übernahme abgeschlossener Dokumentbestände in ein anderes FLOWWER-Konto oder für eine gezielte Übergabe auf Unternehmens- beziehungsweise Floww-Ebene.

Welche Dokumente werden exportiert?

Exportiert werden ausschließlich Dokumente in den Zuständen:

• Verarbeitet
• Gelöscht

Je nach gewähltem Aufruf umfasst der Export:

• alle exportierbaren Dokumente des FLOWWER-Kontos,
• die exportierbaren Dokumente eines bestimmten Unternehmens,
• oder die exportierbaren Dokumente eines bestimmten Flowws.

Enthaltene Daten

Das Archiv übernimmt neben den Dokumenten unter anderem:

• Dokumenteigenschaften,
• Belegaufteilungen,
• FiBu-Notiz und Benutzernotiz,
• Logbuch beziehungsweise Audit-Trail,
• Volltextindex,
• E-Rechnungsdaten,
• Aufbewahrungsfrist.

Vorschau-PDFs werden beim ersten Öffnen im Zielsystem neu erzeugt.

Ziel des Imports

Ein Archiv kann importiert werden in:

• ein ausgewähltes Zielunternehmen,
• oder einen ausgewählten Zielfloww.

Beim Import in ein Ziel mit einer längeren Aufbewahrungsdauer kann die Aufbewahrungsfrist neu berechnet und dadurch verlängert werden. Eine bereits bestehende Aufbewahrungsfrist wird durch den Import jedoch nicht verkürzt.

Verwendung mit FLOWWER-Agent

Die folgenden Beispiele verwenden Platzhalter. Ersetzen Sie Kontokennung, API-Schlüssel und IDs durch die Werte Ihrer Umgebung.

Alle exportierbaren Dokumente exportieren

flowwer.exe exportall `
  -t <Kontokennung> `
  -a <API-Schlüssel> `
  -o C:\FLOWWER-Export

Dokumente eines Unternehmens exportieren

flowwer.exe exportfromcompany `
  -t <Kontokennung> `
  -a <API-Schlüssel> `
  --companyid=<Unternehmens-ID> `
  -o C:\FLOWWER-Export

Dokumente eines Flowws exportieren

flowwer.exe exportfromflow `
  -t <Kontokennung> `
  -a <API-Schlüssel> `
  --flowid=<Floww-ID> `
  -o C:\FLOWWER-Export

Archiv in ein Unternehmen importieren

flowwer.exe importtocompany `
  -t <Kontokennung> `
  -a <API-Schlüssel> `
  --companyid=<Unternehmens-ID> `
  -i C:\FLOWWER-Export\Export_<Zeitstempel>.zip

Archiv in einen Floww importieren

flowwer.exe importtoflow `
  -t <Kontokennung> `
  -a <API-Schlüssel> `
  --flowid=<Floww-ID> `
  --note="Importierter Dokumentbestand" `
  -i C:\FLOWWER-Export\Export_<Zeitstempel>.zip

Verwendung über die REST-API

Die Export- und Importaktionen stehen auch über die REST-API zur Verfügung. Die in Ihrer FLOWWER-Umgebung verfügbaren Aktionen und Request-Modelle finden Sie in der Swagger-Oberfläche unter:

https://<Ihre-FLOWWER-Kontokennung>.flowwer.de/swagger

Für automatisierte Übernahmen empfiehlt sich ein eigener API-Token-Benutzer mit den dafür erforderlichen Berechtigungen.

Hinweise

• Prüfen Sie vor einem Import, ob Zielunternehmen beziehungsweise Zielfloww korrekt ausgewählt sind.
• Bewahren Sie Exportarchive geschützt auf, da sie Dokumente, Notizen und Protokolldaten enthalten.
• Testen Sie größere Übernahmen zunächst mit einem begrenzten Dokumentbestand.

4 - API-Benutzer

FLOWWER sieht für Zugriffe auf die REST-API die Verwendung eines API-Benutzers vor.
Der API-Benutzer stellt automatisch einen API-Key zur Verfügung.

Vorteile

Sicherheits- und Audit-Logs

Da API-Benutzer separate Identitäten darstellen, kann ihre Nutzung in Protokollen leicht nachverfolgt und überwacht werden.
Dies erleichtert die Sicherheitsüberwachung und die Erkennung von Anomalien.

Organisation

Bewährte Praxis ist es, für jeden API-Zugreifenden (FLOWWER-Agent, FTP, InvoiceFetcher, etc.) einen eigenen API-Benutzer zu erstellen.

Langfristige API-Keys

Die API-Benutzer verwenden vom System vergebene API-Keys.
Diese sind dauerhaft gültig und somit für fortlaufende oder wiederkehrende Aufgaben ideal.

Eingeschränkte Berechtigungen

Das Konto kann so konfiguriert werden, dass es nur die für die jeweiligen API-Operationen erforderlichen Berechtigungen erhält.

Keine GUI-Abhängigkeit

API-Benutzer dürfen sich nicht an der FLOWWER-Benutzeroberfläche anmelden.
So ist sichergestellt, dass Integrationen nicht durch UI-Updates unterbrochen werden.

Minimierung menschlicher Interaktion

Da keine Benutzeroberfläche (UI) verwendet wird, gibt es weniger Möglichkeiten für Fehler oder unbefugten Zugriff durch menschliche Benutzer.

Vereinfachung:

Dar vergebene API-Key identifiziert den zugehörigen API-Benutzer eindeutig und ist in der FLOWWER-Benutzerverwaltung sichtbar.

Einrichtung

Zur Einrichtung: API-Benutzer

5 - Beispiele

Hochladen eines neuen Dokuments

Sende einen ‘POST’-Request an https://Ihre-FLOWWER-Kontokennung.flowwer.de/api/v1/upload Authentifizierung / Sicherheit

6 - Sicherheit

Die allermeisten Endpoints der FLOWWER-API finden im Kontext eines FLOWWER-Benutzers statt.
Hierfür ist zur Authentifizierung ein API-Key im HTTP-Header ("X-FLOWWER-ApiKey") des REST-Calls zu hinterlegen.

Einen API-Key können Sie über die Benutzeroberfläche im Bereich API-Benutzer der Benutzerverwaltung erstellen.