Belegaufteilungen per API lesen und ersetzen

FLOWWER stellt umfangreiche Schnittstellen bereit, über die sich Daten aus Dokumenten automatisiert auslesen lassen.
Dies ermöglicht Integrationen mit nachgelagerten Systemen, wie zum Beispiel Finanz- oder Reporting-Software.

Ein häufiges Szenario ist das Lesen oder Ersetzen der Belegaufteilung.
Dabei geht es um die Aufschlüsselung eines Dokuments in einzelne Buchungspositionen mit Konten, Kostenstellen und Steuerinformationen.
So können die erfassten Daten direkt weiterverarbeitet oder aus einem angebundenen System zurück nach FLOWWER geschrieben werden.

Swagger-Dokumentation

Für jede FLOWWER-Kontokennung steht eine interaktive API-Dokumentation (Swagger) zur Verfügung:

https://<flowwer-kontokennung>.flowwer.de/swagger/

Dort sind alle Endpunkte, Parameter und Beispiele aufgeführt.
Über den Button Authorize oben rechts können Anfragen auch direkt getestet werden.

API-Key via API-Benutzer einrichten

Für API-Zugriffe wird ein API-Benutzer verwendet. Dieses spezielle Benutzerkonto liefert automatisch einen dauerhaften API-Key.
Weitere Informationen: API-Benutzer

Vorteile eines API-Benutzers

• Eigenständige Identität im System – erleichtert Audit-Logs und Nachvollziehbarkeit
• Langfristig gültige API-Keys – ideal für automatisierte Prozesse
• Einschränkbare Berechtigungen – nur die notwendigen Rechte vergeben
• Keine GUI-Anmeldung möglich – verhindert versehentliche UI-Nutzung
• Kein menschliches Eingreifen erforderlich für Automatisierungen

Einrichtung

1. In der Benutzerverwaltung einen API-Benutzer anlegen.
2. Der API-Key wird automatisch erzeugt und dem Benutzer zugewiesen.
3. Der Key muss als HTTP-Header übermittelt werden:

X-FLOWWER-ApiKey: <API_KEY>

Belegaufteilung abrufen

GET /api/v1/documents/{DocumentId}/receiptsplits

• Basis-URL: https://<flowwer-kontokennung>.flowwer.de
• Pfadparameter:
  • DocumentId – Dokument-ID in FLOWWER (int64), siehe Dokumenteigenschaften
• Authentifizierung: API-Key im Header

X-FLOWWER-ApiKey: <API_KEY>

Beispielaufruf

curl -s   
     -H "Accept: application/json"   
	 -H "X-FLOWWER-ApiKey: <API_KEY>"   
	 "https://beispiel.flowwer.de/api/v1/documents/123456/receiptsplits"

Beispielantwort

{
  "documentNumber": "RE-2025-00123",
  "invoiceNumber": "2025-00123",
  "supplierName": "Muster GmbH",
  "invoiceDate": "2025-08-01",
  "documentId": 123456,
  "documentName": "2025-08_Muster_Rechnung_00123.pdf",
  "documentKind": "Invoice",
  "currentStage": "Approved",
  "paymentState": "TransferIsPrepared",
  "paymentMethod": "SEPA",
  "documentReceiptSplits": [
    {
      "splitId": 98765,
      "groupName": "Allgemeine Kosten",
      "account": "4210",
      "costCenter": "1000",
      "costUnit": "MKT",
      "amountNet": 100.00,
      "amountTax": 19.00,
      "amountGross": 119.00,
      "taxRate": 19.0,
      "taxCode": "DE19",
      "text": "Monatspauschale"
    }
  ]
}

Struktur der Antwort

DocumentWithReceiptSplits

• documentNumber – Belegnummer in FLOWWER
• invoiceNumber – Rechnungsnummer
• supplierName – Name des Lieferanten
• invoiceDate – Rechnungsdatum
• documentId – interne Dokument-ID
• documentName – Dateiname
• documentKind – Dokumentart (z. B. Invoice)
• currentStage – aktuelle Floww-Stufe
• paymentState – Zahlungsstatus
• paymentMethod – Zahlungsmethode
• documentReceiptSplits – Liste der Aufteilungszeilen

DocumentReceiptSplit

• splitId – ID der Aufteilungszeile
• groupName – Name der Aufteilungsgruppe
• account – Sachkonto
• costCenter – Kostenstelle
• costUnit – Kostenträger
• amountNet – Nettobetrag
• amountTax – Steuerbetrag
• amountGross – Bruttobetrag
• taxRate – Steuersatz
• taxCode – Steuerkennzeichen
• text – Buchungstext

Belegaufteilung ersetzen

PUT /api/v1/documents/{DocumentId}/receiptsplits

Das übermittelte JSON-Array bildet den vollständigen neuen Zustand der Belegaufteilung des Dokuments ab. Der Endpunkt ergänzt die vorhandenen Zeilen daher nicht lediglich, sondern ersetzt alle bisherigen Aufteilungsgruppen.

Beispielaufruf

curl -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-FLOWWER-ApiKey: <API_KEY>" \
  --data '[
    {
      "groupName": "Allgemeine Kosten",
      "account": "4210",
      "costCenter": "1000",
      "costUnit": "MKT",
      "amountNet": 100.00,
      "amountTax": 19.00,
      "amountGross": 119.00,
      "taxRate": 19.0,
      "taxCode": "DE19",
      "text": "Monatspauschale"
    }
  ]' \
  "https://beispiel.flowwer.de/api/v1/documents/123456/receiptsplits"

Die genaue Struktur von DocumentReceiptSplit kann in der Swagger-Dokumentation der jeweiligen FLOWWER-Installation eingesehen und getestet werden.

Fehlercodes

• 401 Unauthorized – API-Key fehlt oder ungültig
• 403 Missing permission – keine Berechtigung für das Dokument
• 404 Not Found – Dokument nicht vorhanden oder nicht zugreifbar

Minimalbeispiel in C#

using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

var client = new HttpClient
{
    BaseAddress = new Uri("https://beispiel.flowwer.de")
};
client.DefaultRequestHeaders.Add("X-FLOWWER-ApiKey", "<API_KEY>");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

long documentId = 123456;
var response = await client.GetAsync($"/api/v1/documents/{documentId}/receiptsplits");
string json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

• ←Zurück
• Weiter→