🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowAccounting API - für Rechnungsstellung und Finanzmanagement

Eine umfassende REST API zur Verwaltung von Rechnungen, Angeboten, Gutschriften, Positionen, Transaktionen, Produkten, Steuersätzen und wiederkehrender Abrechnung sowie von Ausgaben und Belegen. Mit PDF-, ZUGFeRD- und XRechnung-Export sowie Stripe-Zahlungsabgleich.

🔐 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowaccounting/invoices https://creativeskyline.de/api/flowaccounting/transactions https://creativeskyline.de/api/flowaccounting/products https://creativeskyline.de/api/flowaccounting/tax-rates https://creativeskyline.de/api/flowaccounting/recurring-invoices https://creativeskyline.de/api/flowaccounting/billable-items https://creativeskyline.de/api/flowaccounting/quotes https://creativeskyline.de/api/flowaccounting/credit-notes https://creativeskyline.de/api/flowaccounting/expenses https://creativeskyline.de/api/flowaccounting/suppliers https://creativeskyline.de/api/flowaccounting/expense-categories https://creativeskyline.de/api/flowaccounting/reports
Team-bezogene Daten
Alle Endpoints sind team-bezogen: Es werden ausschließlich Daten des Teams zurückgegeben, dem Ihr API-Key zugeordnet ist.

1. API-Zugangsdaten abrufen

Bevor Sie die API nutzen können, benötigen Sie Ihre persönlichen Zugangsdaten: Melden Sie sich an, navigieren Sie zu Profil → API-Zugang und kopieren Sie Ihren persönlichen API-Key (pk_...).

2. Authentifizierung

Alle API-Anfragen benötigen diesen HTTP-Header:

Authorization: Bearer pk_dein_api_key
Accept: application/json

🧾 Rechnungen

Bearbeitungseinschränkungen
Bearbeiten ist nur bei Status draft oder sent (und Quelle manual) möglich, Löschen nur bei draft. Versendete oder bezahlte Rechnungen werden stattdessen storniert.

Rechnungen auflisten

GET /api/flowaccounting/invoices

Ruft eine paginierte Liste aller Rechnungen des Teams ab (sortiert nach Rechnungsdatum, absteigend).

Query-Parameter:

include string Mit items werden die Rechnungspositionen einschließlich name und description eingebettet
status string Filter: draft, sent, partially_paid, paid, overdue, past_due, cancelled
client_uuid string Filter nach Kunden-UUID (cmm_clients). Breaking Change: die früheren Filter client_id und contact_id werden mit 422 abgelehnt, statt stillschweigend ignoriert zu werden
search string Suchbegriff (Rechnungsnummer, Empfängername, Firma)
from string Rechnungsdatum ab (YYYY-MM-DD)
to string Rechnungsdatum bis (YYYY-MM-DD)
per_page integer Anzahl pro Seite (1-200, Standard: 15)

Rechnung erstellen

POST /api/flowaccounting/invoices

Erstellt eine neue Rechnung. Die Rechnungsnummer wird automatisch aus dem Nummernkreis des Teams vergeben; für den Import von Altrechnungen kann sie über invoice_number vorgegeben werden. Eine Rechnung mit vorgegebener Nummer erhält ohne payment_method die Zahlungsart bank_transfer; die Standard-Zahlungsart des Kunden wird dann nicht übernommen. Die vollständige Reihenfolge einer Übernahme steht im Abschnitt „Belege aus einem Fremdsystem übernehmen“. Kollidiert der Nummernkreis mit vorhandenen Belegen, antwortet der Endpunkt mit 409 und error_code: document_number_conflict. Positionen können entweder direkt beim Erstellen über items mitgegeben oder nachträglich über den Positionen-Endpoint hinzugefügt werden, beide Wege sind gültig. Ohne send entsteht die Rechnung im Status draft. Mit send wird sie unmittelbar nach dem Anlegen per E-Mail versendet und wechselt dabei in den Status sent. Die Antwort führt in diesem Fall zusätzlich das Feld sent, bei einem gescheiterten Versand ergänzt um send_error_code und send_message. Die Rechnung bleibt auch dann mit 201 angelegt. Wird billing_operation_key mitgegeben und existiert die Rechnung dazu bereits, liefert die API den vorhandenen Stand zurück und wendet weder items noch send ein zweites Mal an, so dass ein wiederholter Aufruf keinen Doppelversand auslöst. Breaking Change: Die früheren numerischen Felder client_id, contact_id und items.*.product_id werden nicht mehr akzeptiert (Validierungsfehler); Kunde, Kontakt und Produkt werden ausschließlich über client_uuid, contact_uuid und items.*.product_uuid angegeben.

Request Body:

recipient_name string * Name des Rechnungsempfängers
invoice_date string * Rechnungsdatum (YYYY-MM-DD)
due_date string Fälligkeitsdatum (>= invoice_date). Wenn leer: invoice_date + Zahlungsziel des Teams (Standard 14 Tage)
currency_code string * ISO 4217 Währungscode (3 Zeichen, z.B. EUR)
client_uuid string Optional: Kunden-UUID (cmm_clients, teamgebunden)
contact_uuid string Optional: Kontakt-UUID (teamgebunden)
invoice_number string Optional: eigene Rechnungsnummer, nur für den Import von Altrechnungen gedacht. Im Normalfall weglassen, dann vergibt der Nummernkreis die Nummer. KI-Assistenten und Agenten setzen das Feld nur, wenn der Nutzer ausdrücklich auf einer eigenen Nummer besteht. Höchstens 40 Zeichen aus den Buchstaben A bis Z, Ziffern, Leerzeichen, Punkt, Unterstrich und Bindestrich, am Anfang und Ende ein Buchstabe oder eine Ziffer. Muss im Team eindeutig sein, auch gegenüber gelöschten Entwürfen und stornierten Rechnungen. Liegt die Nummer im laufenden Nummernkreis, muss sie unter dem nächsten Zählerstand liegen; dafür vorher in den FlowAccounting-Einstellungen die nächste Rechnungsnummer über die höchste Importnummer setzen. Der Zähler bleibt unverändert. Nach dem Anlegen lässt sich die Nummer nicht mehr ändern
notes string Sichtbare Notiz auf der Rechnung
payment_method string Zahlungsart: bank_transfer | sepa | stripe | paypal | cash | other. Ohne Angabe gilt die Standard-Zahlungsart des Kunden aus FlowCRM (nicht gesetzt = Banküberweisung); Kreditkarte oder SEPA werden also nur übernommen, wenn sie dort als Standard hinterlegt oder hier explizit angegeben sind. Ausnahme: Mit vorgegebener invoice_number gilt ohne Angabe immer bank_transfer, damit eine übernommene Altrechnung nicht auf ein hinterlegtes Zahlungsmittel des Kunden läuft; eine ausdrücklich angegebene Zahlungsart gilt auch dann. stripe, sepa und paypal setzen eine gespeicherte Stripe-Zahlungsmethode des Kunden vom passenden Typ voraus (sonst 422).
stripe_pm_id string Optional: konkrete Stripe-Zahlungsmethode (pm_...) des Kunden. Ohne Angabe wird sie bei stripe, sepa und paypal aus der Standard-Zahlungsmethode des Kunden ergänzt.
tax_treatment string Steuerbehandlung dieser Rechnung: standard | reverse_charge. Ohne Angabe gilt bei manuellen Rechnungen die Steuerbehandlung des Kunden aus FlowCRM. Bei reverse_charge weist die Rechnung keine Umsatzsteuer aus: Positionen mit tax_rate über 0 oder mit unit_price_gross werden mit 422 abgelehnt. Nur für source manual
document_language string Belegsprache der Rechnung: de | en | pt. Ohne Angabe gilt bei manuellen Rechnungen die Rechnungssprache des Kunden aus FlowCRM, sonst de
send boolean Rechnung sofort nach dem Anlegen per E-Mail versenden. Ohne dieses Flag bleibt es beim Entwurf
items array Rechnungspositionen direkt mitgeben, 1 bis 200 Stück. Je Position sind <code>quantity</code> und <code>unit_price</code> verpflichtend, optional sind <code>name</code>, <code>description</code>, <code>tax_rate</code>, <code>unit</code>, <code>position</code>, <code>product_uuid</code>, <code>discount_percent</code> und <code>type</code>. Ohne <code>position</code> werden die Positionen fortlaufend nummeriert

Rechnungs-Details abrufen

GET /api/flowaccounting/invoices/{uuid}

Rechnungs-Details abrufen, inklusive Positionen, Transaktionen sowie total_paid, remaining_amount und allowed_transitions. sent_date nennt den Tag des Versands und ist im Entwurf null. original_invoice_number ist nur gesetzt, wenn die Rechnung über den Status storniert wurde, und nennt die Nummer, unter der sie ausgestellt war. Unter credit_notes stehen die Gutschriften, die zu dieser Rechnung angelegt wurden, aufsteigend nach Gutschriftsdatum und jeweils mit uuid, credit_note_number, status, credit_note_date, total und currency_code; die vollständige Gutschrift liefert der Gutschriften-Endpoint. credit_notes gibt es nur in dieser Detailantwort, nicht in der Liste.

Rechnung aktualisieren

PUT /api/flowaccounting/invoices/{uuid}

Rechnung aktualisieren. Nur möglich bei Status draft oder sent und Quelle manual (sonst 422). Akzeptiert dieselben Felder wie beim Erstellen. Breaking Change: client_id und contact_id werden nicht mehr akzeptiert; ausschließlich client_uuid und contact_uuid.

Request Body:

recipient_name string Name des Rechnungsempfängers
due_date string Fälligkeitsdatum
notes string Sichtbare Notiz auf der Rechnung
document_language string Belegsprache der Rechnung: de | en | pt

Rechnung löschen

DELETE /api/flowaccounting/invoices/{uuid}

Rechnung löschen. Nur möglich im Status draft (sonst 422).

Rechnungsstatus setzen

POST /api/flowaccounting/invoices/{uuid}/status

Direkter Statuswechsel. Über diesen Endpoint sind nur die Übergänge nach sent (versenden) und cancelled (stornieren) möglich. Bei unzulässigem Übergang: 422 mit Feld allowed_transitions. Beim Wechsel nach sent gilt der heutige Tag als Versanddatum; eine E-Mail wird dabei nicht verschickt. Für Altrechnungen aus einem Fremdsystem kann das tatsächliche Versanddatum über sent_date mitgegeben werden. Eine Rechnung mit einem Versanddatum vor dem Tag ihrer Erfassung gilt als übernommener Altbeleg: Sie wird nicht automatisch gemahnt und nicht automatisch abgebucht. Von Hand geht beides weiter.

Request Body:

status string * Zielstatus: sent oder cancelled
sent_date string Optional: tatsächliches Versanddatum (YYYY-MM-DD), nur für die Übernahme von Altrechnungen aus einem Fremdsystem gedacht. Im Normalfall weglassen, dann gilt der heutige Tag. Nur zusammen mit status sent, nur beim Wechsel aus dem Entwurf und nur für manuelle Rechnungen (source manual), sonst 422. Frühestens das Rechnungsdatum, spätestens heute. Liegt das Datum vor dem Tag, an dem die Rechnung hier erfasst wurde, gilt sie als übernommener Altbeleg und wird nicht automatisch gemahnt oder abgebucht

Rechnung per E-Mail versenden

POST /api/flowaccounting/invoices/{uuid}/send

Versendet die Rechnung per E-Mail an den hinterlegten Empfänger. Beim Erstversand wechselt eine Rechnung im Status draft automatisch nach sent. Eine bereits versendete Rechnung kann erneut verschickt werden, der Status bleibt dabei unverändert. Der Endpoint ist auf 10 Anfragen pro Minute je API-Key begrenzt, darüber hinausgehende Anfragen werden mit 429 beantwortet. Nicht versandfähig sind stornierte Rechnungen, Rechnungen ohne hinterlegte Empfänger-E-Mail sowie E-Rechnungsformate mit offenen Validierungsfehlern. Versendbar sind außerdem nur Rechnungen aus den Quellen manual, hosting_checkout und hosting_renewal, weil automatisch abgerechnete Quellen ihre Rechnungsmail bereits selbst verschicken. In all diesen Fällen antwortet die API mit 422 und dem Feld error_code, das die Werte not_sendable, no_recipient_email oder einvoice_invalid annehmen kann. Eine unbekannte UUID ergibt 404.

Rechnung als PDF herunterladen

GET /api/flowaccounting/invoices/{uuid}/pdf PDF

Lädt die Rechnung als Standard-PDF herunter (Team-Einstellung einvoice_format=pdf). Antwort ist ein Datei-Download, kein JSON.

Rechnung als ZUGFeRD herunterladen

GET /api/flowaccounting/invoices/{uuid}/pdf ZUGFeRD

Lädt die Rechnung als ZUGFeRD 2.x herunter (PDF mit eingebettetem XML nach EN 16931). Team-Einstellung einvoice_format=zugferd erforderlich.

Rechnung als XRechnung herunterladen

GET /api/flowaccounting/invoices/{uuid}/pdf XRechnung (XML)

Lädt die Rechnung als XRechnung (reines XML nach CIUS-DE) herunter. Team-Einstellung einvoice_format=xrechnung erforderlich. Pflichtformat für Rechnungen an Bundesbehörden.

Rechnung duplizieren

POST /api/flowaccounting/invoices/{uuid}/duplicate

Dupliziert die Rechnung inklusive Positionen als neuen draft. Antwort: 201 mit der neuen Rechnung.

Korrekturrechnung erstellen

POST /api/flowaccounting/invoices/{uuid}/correct

Storniert die versendete Rechnung und erstellt den inhaltsgleichen Korrekturentwurf. Die Korrektur trägt die Nummer des Originals mit angehängter Korrekturziffer, das Original wird auf cancelled gesetzt und auf die Korrektur verwiesen. Möglich bei sent, overdue, past_due und partially_paid und ausschließlich bei manuell geführten Rechnungen; sonst 422. Antwort: 201 mit der Korrekturrechnung.

Mahnung versenden

POST /api/flowaccounting/invoices/{uuid}/dunning

Beauftragt eine Zahlungserinnerung oder Mahnung. level muss genau die nächste fällige Stufe sein: eine übersprungene oder wiederholte Stufe wird mit 422 und dunning_level_not_due abgelehnt. Welche Stufe fällig ist, richtet sich nach den Mahnfristen der Teameinstellungen und den bereits versendeten Stufen, also nach denselben Regeln wie der automatische Mahnlauf. Ohne recipient_emails gelten die Empfänger des Kunden.

Request Body:

level string * Mahnstufe: reminder, dunning_1, dunning_2 oder dunning_3
recipient_emails array Abweichende Empfängeradressen, höchstens 50

Rechnung als bezahlt markieren

POST /api/flowaccounting/invoices/{uuid}/mark-paid

Markiert die Rechnung über eine Stripe-PaymentIntent-ID als vollständig bezahlt. Idempotent: Eine erneute Anfrage mit derselben PaymentIntent-ID gibt den aktuellen Stand zurück (200). Zulässige Ausgangsstatus: sent, requires_action, past_due.

Request Body:

stripe_payment_intent_id string * Stripe-PaymentIntent-ID (pi_3Q...)
date_paid string Zahlungsdatum (YYYY-MM-DD)

PaymentIntent speichern

POST /api/flowaccounting/invoices/{uuid}/record-payment-intent

Speichert eine Stripe-PaymentIntent-ID an der Rechnung, ohne den Zahlstatus auf paid zu setzen. Für 3DS-ausstehende oder überfällige Zahlungen.

Request Body:

stripe_payment_intent_id string * Stripe-PaymentIntent-ID
status string Optional: past_due | requires_action

Rechnung per Stripe abbuchen

POST /api/flowaccounting/invoices/{uuid}/charge

Löst die Abbuchung der Rechnung über die hinterlegte Stripe-Zahlungsart aus (Karte oder SEPA-Lastschrift). Voraussetzung: Die Rechnung hat einen Kunden und eine Stripe-gestützte Zahlungsart, sonst antwortet der Endpoint mit 422 und einem error_code (no_client, wrong_payment_method). Eine abgelehnte Zahlung ist kein Anfragefehler: Die Antwort ist 200 mit charged: false. Ein wiederholter Aufruf bucht nicht doppelt ab. Ist Stripe vorübergehend nicht erreichbar, antwortet der Endpoint mit 503. Der Aufruf ist pro API-Key begrenzt.

Zahlstatus abfragen

GET /api/flowaccounting/invoices/{uuid}/payment-status

Schlanke Statusabfrage für das Polling nach einer Abbuchung, ohne Positionen und Transaktionen. Liefert uuid, status, payment_intent_status, last_charge_error und stripe_charge_id. SEPA-Lastschriften werden erst nach Tagen endgültig bestätigt, der Status ändert sich dann ohne weiteren Aufruf.

💰 Rechnungspositionen

Nur bei draft bearbeitbar
Positionen können nur verändert werden, solange sich die Rechnung im Status draft befindet. Nach jeder Änderung werden die Rechnungssummen neu berechnet.

Positionen auflisten

GET /api/flowaccounting/invoices/{uuid}/items

Alle Positionen einer Rechnung auflisten.

Position hinzufügen

POST /api/flowaccounting/invoices/{uuid}/items

Fügt der Rechnung eine Position hinzu. Breaking Change: Das frühere numerische Feld product_id wird nicht mehr akzeptiert; das Produkt wird ausschließlich über product_uuid angegeben.

Request Body:

quantity number * Menge (min 0.01)
unit_price number * Einzelpreis (negativ erlaubt für Gutschriften)
name string Positionsbezeichnung (max 255)
description string Beschreibung (max 1000)
tax_rate number Steuersatz in Prozent (0-100). Ohne Angabe 0 %
unit string Einheit (z.B. Std.)
product_uuid string Produkt-UUID (fac_products, teamgebunden)

Position bearbeiten

PUT /api/flowaccounting/invoices/{uuid}/items/{itemUuid}

Position bearbeiten. Die Position wird über ihre UUID adressiert; numerische IDs werden nicht mehr akzeptiert (HTTP 404). Nur bei draft.

Request Body:

quantity number Menge
unit_price number Einzelpreis
name string Positionsbezeichnung

Position löschen

DELETE /api/flowaccounting/invoices/{uuid}/items/{itemUuid}

Position löschen. Die Position wird über ihre UUID adressiert. Nur bei draft.

💳 Transaktionen

Zahlungen und Gutschriften werden als Transaktionen einer Rechnung erfasst. Der Zahlstatus der Rechnung (partially_paid, paid) wird automatisch neu berechnet.

Transaktionen einer Rechnung auflisten

GET /api/flowaccounting/invoices/{uuid}/transactions

Alle Transaktionen einer Rechnung auflisten (sortiert nach Datum, absteigend).

Transaktion erfassen

POST /api/flowaccounting/invoices/{uuid}/transactions

Erfasst eine Transaktion. Nur zulässig, wenn die Rechnung im Status sent, partially_paid oder overdue ist. Die Transaktion wird in der Währung der Rechnung gebucht. Gleicht sie die Rechnung aus, übernimmt die Rechnung das transaction_date dieser Zahlung als paid_date, auch bei nachträglich erfassten Zahlungen.

Request Body:

type string * Transaktionstyp: payment | refund | credit
amount number * Betrag (min 0.01)
transaction_date string * Transaktionsdatum (YYYY-MM-DD)
payment_method string * Zahlungsmethode: bank_transfer | sepa | stripe | paypal | cash | other
reference string Referenz (max 255)
notes string Notiz (max 1000)

Transaktion löschen

DELETE /api/flowaccounting/invoices/{uuid}/transactions/{transactionUuid}

Transaktion löschen. Die Transaktion wird über ihre UUID adressiert; numerische IDs werden nicht mehr akzeptiert (HTTP 404). Nicht möglich bei Rechnungen im Status draft oder cancelled.

Team-weite Transaktionsübersicht

GET /api/flowaccounting/transactions

Team-weite Transaktions-Übersicht über alle Rechnungen (paginiert, 25 pro Seite).

Query-Parameter:

from string Transaktionsdatum ab (YYYY-MM-DD)
to string Transaktionsdatum bis (YYYY-MM-DD)
search string Suchbegriff (Notiz, Referenz, Rechnungsnummer)

📦 Produkte

Produkte auflisten

GET /api/flowaccounting/products

Produkte auflisten (paginiert, sortiert nach Nutzungshäufigkeit).

Query-Parameter:

type string Filter nach Quelle (z.B. manual)
search string Suchbegriff (Titel/Beschreibung)
per_page integer Anzahl pro Seite (1-200, Standard: 50)

Produkt abrufen

GET /api/flowaccounting/products/{uuid}

Ruft ein einzelnes Produkt Ihres Teams über die uuid ab. Unbekannte oder teamfremde Einträge führen zu 404.

Produkt anlegen

POST /api/flowaccounting/products

Neues Produkt anlegen.

Request Body:

title string * Produktname (max 255)
unit_price number * Netto-Einzelpreis (min 0). Pflicht, wenn <code>unit_price_gross</code> fehlt; nicht zusammen mit <code>unit_price_gross</code>
unit_price_gross number Brutto-Einzelpreis inkl. MwSt. (min 0), alternativ zu <code>unit_price</code>. Wird exakt gespeichert, der Nettopreis wird daraus abgeleitet
tax_rate number * Steuersatz (0-100)
description string Beschreibung
unit string Einheit (max 50)
is_active boolean Aktiv (Standard: true)

Produkt aktualisieren

PUT /api/flowaccounting/products/{uuid}

Produkt aktualisieren.

Request Body:

title string Produktname
unit_price number Netto-Einzelpreis, macht das Produkt zu einem Netto-Produkt
unit_price_gross number Brutto-Einzelpreis inkl. MwSt., wird exakt gespeichert; nicht zusammen mit <code>unit_price</code>
tax_rate number Steuersatz
is_active boolean Aktiv

Produkt löschen

DELETE /api/flowaccounting/products/{uuid}

Produkt löschen.

🏷️ Steuersätze

Adressierung per UUID
Steuersätze werden ausschließlich über ihre UUID adressiert. Die frühere numerische ID wird nicht mehr akzeptiert (HTTP 404).

Steuersätze auflisten

GET /api/flowaccounting/tax-rates

Alle Steuersätze des Teams abrufen (unpaginiert, sortiert nach sort_order).

Steuersatz abrufen

GET /api/flowaccounting/tax-rates/{uuid}

Ruft einen einzelnen Steuersatz Ihres Teams über die uuid ab. Unbekannte oder teamfremde Einträge führen zu 404.

Steuersatz anlegen

POST /api/flowaccounting/tax-rates

Neuen Steuersatz anlegen.

Request Body:

name string * Bezeichnung (max 255)
rate number * Steuersatz in Prozent (0-100)
description string Beschreibung
is_default boolean Als Standard setzen
is_active boolean Aktiv
sort_order integer Sortierreihenfolge (>= 0)

Steuersatz aktualisieren

PUT /api/flowaccounting/tax-rates/{uuid}

Steuersatz aktualisieren.

Request Body:

name string Bezeichnung
rate number Steuersatz
is_active boolean Aktiv

Steuersatz löschen

DELETE /api/flowaccounting/tax-rates/{uuid}

Steuersatz löschen. Nicht möglich, wenn er in Rechnungspositionen verwendet wird (422).

Als Standard setzen

POST /api/flowaccounting/tax-rates/{uuid}/default

Setzt diesen Steuersatz als Team-Standard (alle anderen verlieren das Standard-Flag).

🔁 Wiederkehrende Rechnungen

Automatische Rechnungserzeugung
Aus aktiven Vorlagen werden in festen Intervallen automatisch Rechnungen erzeugt. Pausieren Sie Vorlagen, wenn keine Rechnungen erzeugt werden sollen.

Auflisten

GET /api/flowaccounting/recurring-invoices

Auflisten (paginiert, 25 pro Seite).

Query-Parameter:

status string Filter: active, paused
client_uuid string Filter nach Kunden-UUID. Breaking Change: der frühere Filter client_id wird mit 422 abgelehnt, statt stillschweigend ignoriert zu werden

Wiederkehrende Rechnung abrufen

GET /api/flowaccounting/recurring-invoices/{uuid}

Ruft eine einzelne wiederkehrende Rechnung Ihres Teams über die uuid ab. Unbekannte oder teamfremde Einträge führen zu 404.

Neue wiederkehrende Rechnung anlegen

POST /api/flowaccounting/recurring-invoices

Neue wiederkehrende Rechnung anlegen. Breaking Change: Das frühere numerische Feld client_id wird nicht mehr akzeptiert; der Kunde wird ausschließlich über client_uuid angegeben.

Request Body:

client_uuid string * Kunden-UUID (cmm_clients, teamgebunden)
interval_value integer * Intervallwert (>= 1)
interval_unit string * Intervalleinheit: day | week | month | year
start_date string * Startdatum (YYYY-MM-DD)
template_items array * Positionen der Vorlage (min 1)
auto_send boolean Automatisch versenden
end_date string Enddatum (>= start_date)
status string Status: active | paused

Aktualisieren

PUT /api/flowaccounting/recurring-invoices/{uuid}

Wiederkehrende Rechnung aktualisieren.

Request Body:

interval_value integer Intervallwert
interval_unit string Intervalleinheit
auto_send boolean Automatisch versenden

Löschen

DELETE /api/flowaccounting/recurring-invoices/{uuid}

Wiederkehrende Rechnung löschen.

Pausieren

POST /api/flowaccounting/recurring-invoices/{uuid}/pause

Pausiert die Vorlage (Status paused) - es werden keine neuen Rechnungen erzeugt.

Aktivieren

POST /api/flowaccounting/recurring-invoices/{uuid}/activate

Aktiviert die Vorlage wieder (Status active) und legt dabei fest, was der automatische Lauf tun darf. auto_send, auto_charge und recipient_emails sind die eigentliche Freigabe: ohne sie entstehen nur Entwürfe. auto_send ist standardmäßig aktiv, auto_charge standardmäßig aus und setzt eine Stripe- oder SEPA-Zahlungsart auf der Serie voraus (sonst 422). Ohne recipient_emails gelten die Empfänger des Kunden; ist dort keine Adresse hinterlegt und soll versendet werden, antwortet die API mit 422.

Request Body:

auto_send boolean Erzeugte Rechnungen automatisch versenden (Standard: true)
auto_charge boolean Erzeugte Rechnungen automatisch einziehen (Standard: false, benötigt Zahlungsart stripe oder sepa)
recipient_emails array Empfängeradressen des automatischen Versands, höchstens 50

Nächste Rechnung erzeugen

POST /api/flowaccounting/recurring-invoices/{uuid}/generate

Erzeugt die fällige Rechnung der Serie sofort, ohne auf den nächtlichen Lauf zu warten. Ist derzeit keine Rechnung fällig oder die Freigabe der Serie nicht mehr gültig, antwortet die API mit 422 und nothing_to_generate.

🧮 Abrechenbare Positionen

Bereits abgerechnete Positionen
Positionen, die bereits zu einer Rechnung konsolidiert wurden, können weder bearbeitet noch gelöscht werden (422).

Auflisten

GET /api/flowaccounting/billable-items

Auflisten (paginiert, 25 pro Seite).

Query-Parameter:

open boolean true = nur offene, false = nur abgerechnete
client_uuid string Filter nach Kunden-UUID. Breaking Change: der frühere Filter client_id wird mit 422 abgelehnt, statt stillschweigend ignoriert zu werden

Abrechenbare Position abrufen

GET /api/flowaccounting/billable-items/{uuid}

Ruft eine einzelne abrechenbare Position Ihres Teams über die uuid ab. Unbekannte oder teamfremde Einträge führen zu 404.

Neue Position anlegen

POST /api/flowaccounting/billable-items

Neue abrechenbare Position anlegen. Breaking Change: Das frühere numerische Feld client_id wird nicht mehr akzeptiert; der Kunde wird ausschließlich über client_uuid angegeben.

Request Body:

client_uuid string * Kunden-UUID (cmm_clients, teamgebunden)
description string * Beschreibung (max 255)
unit_price number * Einzelpreis
quantity number Menge (min 0.01)
unit string Einheit (max 50)
tax_rate number Steuersatz
due_date string Fälligkeitsdatum
auto_bill boolean Automatisch abrechnen

Position bearbeiten

PUT /api/flowaccounting/billable-items/{uuid}

Bearbeiten. Nur möglich, solange die Position nicht abgerechnet ist (422).

Request Body:

description string Beschreibung
unit_price number Einzelpreis
quantity number Menge

Position löschen

DELETE /api/flowaccounting/billable-items/{uuid}

Löschen. Nur möglich, solange nicht abgerechnet (422).

Positionen konsolidieren

POST /api/flowaccounting/billable-items/consolidate

Fasst mehrere offene Positionen zu Rechnungen zusammen - pro Kunde wird eine Entwurfs-Rechnung erzeugt. Antwort: 201 mit den erstellten Rechnungen.

Request Body:

uuids array * UUIDs der zu konsolidierenden Positionen (min 1, eindeutig)

Position einzeln abrechnen

POST /api/flowaccounting/billable-items/{uuid}/generate

Rechnet genau diese Position sofort ab und liefert den Rechnungsentwurf. Das Fälligkeitsdatum wird dabei bewusst übergangen, es wird nichts versendet. Eine bereits abgerechnete Position liefert mit 200 ihre vorhandene Rechnung statt einer zweiten.

📄 Angebote

Bearbeitungseinschränkungen
Ein Angebot lässt sich nur im Status draft ändern oder löschen. Sobald es beim Kunden ist, ist sein Inhalt das, was der Kunde erhalten hat; danach sind nur noch die Aktionen erlaubt, die das Feld available_actions der Antwort nennt.

Angebote auflisten

GET /api/flowaccounting/quotes

Ruft eine paginierte Liste aller Angebote des Teams ab, sortiert nach Angebotsdatum, absteigend.

Query-Parameter:

status string Filter: draft, sent, accepted, declined, expired, withdrawn
client_uuid string Filter nach Kunden-UUID
search string Suchbegriff (Angebotsnummer, Empfängername, Firma)
from string Angebotsdatum ab (YYYY-MM-DD)
to string Angebotsdatum bis (YYYY-MM-DD)
per_page integer Anzahl pro Seite (1-200, Standard: 25)

Angebot erstellen

POST /api/flowaccounting/quotes

Erstellt ein Angebot im Status draft. Die Angebotsnummer wird automatisch aus dem Nummernkreis des Teams vergeben; für die Übernahme bestehender Angebote aus einem Fremdsystem kann sie über quote_number vorgegeben werden. Nicht angegebene Felder werden aus den Teameinstellungen und den Kundendaten ergänzt, etwa Währung, Sprache, Gültigkeitsdauer sowie Anschreiben- und Schlusstext. Die vollständige Liste der schreibbaren Felder liefert GET /api/flowaccounting/context. Die Steuerbehandlung übernimmt das Angebot vom Kunden aus FlowCRM und gibt sie als tax_treatment zurück (standard oder reverse_charge). Bei reverse_charge weist das Angebot keine Umsatzsteuer aus: Ein übergebener tax_rate wird auf 0 gesetzt. Die Rechnung aus einem angenommenen Angebot übernimmt dessen Steuerbehandlung.

Request Body:

client_uuid string * Kunden-UUID (teamgebunden)
contact_uuid string Kontakt-UUID des Kunden
quote_number string Optional: eigene Angebotsnummer, nur für die Übernahme bestehender Angebote aus einem Fremdsystem gedacht. Im Normalfall weglassen, dann vergibt der Nummernkreis die Nummer beim Anlegen. KI-Assistenten und Agenten setzen das Feld nur, wenn der Nutzer ausdrücklich auf einer eigenen Nummer besteht. Höchstens 40 Zeichen aus den Buchstaben A bis Z, Ziffern, Leerzeichen, Punkt, Unterstrich und Bindestrich, am Anfang und Ende ein Buchstabe oder eine Ziffer. Muss im Team eindeutig sein, auch gegenüber gelöschten Entwürfen und zurückgezogenen Angeboten. Liegt die Nummer im laufenden Nummernkreis, muss sie unter dem nächsten Zählerstand liegen; dafür vorher in den FlowAccounting-Einstellungen die nächste Angebotsnummer über die höchste Importnummer setzen. Der Zähler bleibt unverändert. Nach dem Anlegen lässt sich die Nummer nicht mehr ändern
quote_date string Angebotsdatum (YYYY-MM-DD, Standard: heute)
valid_until string Gültig bis (YYYY-MM-DD, Standard: Gültigkeitsdauer des Teams)
signature_type string Annahmeart: button oder canvas
currency_code string EUR, USD, CHF oder GBP
document_language string de oder en
discount_percent number Gesamtrabatt in Prozent
greeting_text string Anschreiben über den Positionen
closing_text string Schlusstext unter den Positionen
notes string Sichtbare Notiz auf dem Angebot
internal_notes string Interne Notiz, nicht auf dem Dokument
items array * Positionen, 1 bis 200 Stück. Je Position <code>name</code>, <code>quantity</code>, <code>unit_price</code> und <code>tax_rate</code>; optional <code>description</code>, <code>unit</code>, <code>discount_percent</code>, <code>type</code>, <code>unit_code</code>, <code>product_uuid</code> und <code>project_uuid</code>
recipient_name string Abweichender Empfängername
recipient_company string Abweichende Empfängerfirma
recipient_email string Abweichende Empfängeradresse

Angebots-Details abrufen

GET /api/flowaccounting/quotes/{uuid}

Angebots-Details einschließlich Positionen, Summen, available_actions und allowed_transitions.

Angebot aktualisieren

PUT /api/flowaccounting/quotes/{uuid}

Ändert ein Angebot im Status draft; sonst 422. Es werden nur die gesendeten Felder geändert, alle übrigen bleiben stehen. Wird items mitgegeben, ersetzt die Liste sämtliche Positionen. Die Angebotsnummer lässt sich nicht ändern: quote_number wird hier mit 422 abgelehnt.

Request Body:

valid_until string Gültig bis (YYYY-MM-DD)
notes string Sichtbare Notiz auf dem Angebot
items array Ersetzt alle Positionen

Angebot löschen

DELETE /api/flowaccounting/quotes/{uuid}

Löscht ein Angebot im Status draft; sonst 422.

Angebot per E-Mail versenden

POST /api/flowaccounting/quotes/{uuid}/send

Versendet das Angebot und setzt es dabei auf sent. Erfordert einen Header Idempotency-Key im UUID-Format; derselbe Schlüssel versendet nicht zweimal. Ohne recipient_emails gelten die Empfänger des Kunden. Ist die Absenderdomain nicht verifiziert, antwortet die API mit 409 und sender_domain_not_verified.

Request Body:

recipient_emails array Abweichende Empfängeradressen, höchstens 50

Angebot zurückziehen

POST /api/flowaccounting/quotes/{uuid}/withdraw

Zieht ein versendetes Angebot zurück. Nur aus dem Status sent möglich; sonst 422.

Annahme erfassen

POST /api/flowaccounting/quotes/{uuid}/accept

Hält fest, dass der Kunde das Angebot angenommen hat, etwa telefonisch oder per E-Mail. Nur aus dem Status sent möglich und nur einmal; sonst 422. Für die Annahme über den Angebotslink des Kunden ist dieser Endpoint nicht gedacht, dort wird zusätzlich die Unterschrift erfasst.

In Rechnung umwandeln

POST /api/flowaccounting/quotes/{uuid}/convert

Erzeugt aus einem angenommenen Angebot einen Rechnungsentwurf. Nur im Status accepted möglich; sonst 422 mit quote_not_accepted. Ein zweiter Aufruf liefert mit 200 die bereits erzeugte Rechnung statt einer weiteren.

Angebots-PDF herunterladen

GET /api/flowaccounting/quotes/{uuid}/pdf BINARY

Liefert das Angebot als PDF-Datei (application/pdf), im Dokumentlayout des Teams und in der auf dem Dokument festgehaltenen Sprache.

🧮 Angebotspositionen

Summen
Nach jeder Änderung an einer Position werden die Summen des Angebots neu berechnet. Positionen lassen sich nur ändern, solange das Angebot ein Entwurf ist.

Positionen auflisten

GET /api/flowaccounting/quotes/{uuid}/items

Listet die Positionen eines Angebots, sortiert nach ihrer Reihenfolge.

Query-Parameter:

per_page integer Anzahl pro Seite (1-200, Standard: 50)

Position hinzufügen

POST /api/flowaccounting/quotes/{uuid}/items

Fügt dem Angebot eine Position hinzu. Ohne position wird sie hinten angefügt. Ein project_uuid muss zu einem Projekt des Angebotskunden gehören; sonst 422.

Request Body:

name string * Bezeichnung der Position
quantity number * Menge
unit_price number * Einzelpreis netto
tax_rate number * Steuersatz in Prozent
description string Beschreibungstext
unit string Einheit, etwa Stunde oder Stück
discount_percent number Positionsrabatt in Prozent
type string service, product oder hours
position integer Reihenfolge
product_uuid string Produkt-UUID aus dem Produktkatalog
project_uuid string Projekt-UUID des Angebotskunden

Position aktualisieren

PUT /api/flowaccounting/quotes/{uuid}/items/{itemUuid}

Ändert eine einzelne Position. Es werden nur die gesendeten Felder geändert.

Request Body:

quantity number Menge
unit_price number Einzelpreis netto
tax_rate number Steuersatz in Prozent

Position löschen

DELETE /api/flowaccounting/quotes/{uuid}/items/{itemUuid}

Entfernt eine Position aus dem Angebot und berechnet die Summen neu.

↩️ Gutschriften

Ausstellen ist endgültig
Mit dem Ausstellen erhält die Gutschrift ihre Nummer, sofern beim Anlegen keine vorgegeben wurde, und ist nicht mehr änderbar. Wurde die zugrunde liegende Rechnung über Stripe bezahlt, wird dabei die Erstattung angestoßen. Eine fehlgeschlagene Erstattung nimmt das Ausstellen nicht zurück, sondern wird im Feld refund_status gemeldet.

Gutschriften auflisten

GET /api/flowaccounting/credit-notes

Ruft eine paginierte Liste aller Gutschriften des Teams ab, sortiert nach Gutschriftsdatum, absteigend.

Query-Parameter:

status string Filter: draft, issued, settled, cancelled
client_uuid string Filter nach Kunden-UUID
from string Gutschriftsdatum ab (YYYY-MM-DD)
to string Gutschriftsdatum bis (YYYY-MM-DD)
per_page integer Anzahl pro Seite (1-200, Standard: 25)

Gutschrift erstellen

POST /api/flowaccounting/credit-notes

Erstellt eine Gutschrift im Status draft. Mit invoice_uuid wird sie der gutzuschreibenden Rechnung zugeordnet; diese muss demselben Kunden gehören und dieselbe Währung führen. Gutschriftpositionen sind freie Zeilen ohne Produkt- oder Projektverknüpfung. Eine Gutschrift zu einer Rechnung übernimmt deren Steuerbehandlung, eine freie Gutschrift die des Kunden; die Antwort nennt sie als tax_treatment. Bei reverse_charge weist die Gutschrift keine Umsatzsteuer aus: Ein übergebener tax_rate wird auf 0 gesetzt. Ihre Nummer erhält die Gutschrift erst beim Ausstellen aus dem Nummernkreis des Teams; für die Übernahme bestehender Gutschriften aus einem Fremdsystem kann sie über credit_note_number vorgegeben werden.

Request Body:

client_uuid string * Kunden-UUID (teamgebunden)
invoice_uuid string UUID der gutzuschreibenden Rechnung
contact_uuid string Kontakt-UUID des Kunden
credit_note_number string Optional: eigene Gutschriftnummer, nur für die Übernahme bestehender Gutschriften aus einem Fremdsystem gedacht. Im Normalfall weglassen, dann vergibt der Nummernkreis die Nummer beim Ausstellen. KI-Assistenten und Agenten setzen das Feld nur, wenn der Nutzer ausdrücklich auf einer eigenen Nummer besteht. Höchstens 40 Zeichen aus den Buchstaben A bis Z, Ziffern, Leerzeichen, Punkt, Unterstrich und Bindestrich, am Anfang und Ende ein Buchstabe oder eine Ziffer. Muss im Team eindeutig sein, auch gegenüber gelöschten Entwürfen und stornierten Gutschriften. Liegt die Nummer im laufenden Nummernkreis, muss sie unter dem nächsten Zählerstand liegen; dafür vorher in den FlowAccounting-Einstellungen die nächste Gutschriftnummer über die höchste Importnummer setzen. Der Zähler bleibt unverändert, auch beim Ausstellen. Nach dem Anlegen lässt sich die Nummer nicht mehr ändern
credit_note_date string Gutschriftsdatum (YYYY-MM-DD, Standard: heute)
currency_code string EUR, USD, CHF oder GBP
document_language string de oder en
einvoice_format string pdf, zugferd oder xrechnung
notes string Sichtbare Notiz auf der Gutschrift
items array * Positionen, 1 bis 200 Stück, mit <code>name</code>, <code>quantity</code>, <code>unit_price</code> und <code>tax_rate</code>

Gutschrifts-Details abrufen

GET /api/flowaccounting/credit-notes/{uuid}

Gutschrifts-Details einschließlich Positionen, Summen und available_actions.

Gutschrift aktualisieren

PUT /api/flowaccounting/credit-notes/{uuid}

Ändert eine Gutschrift im Status draft; sonst 422. Wird items mitgegeben, ersetzt die Liste sämtliche Positionen. Die Gutschriftnummer lässt sich nicht ändern: credit_note_number wird hier mit 422 abgelehnt.

Request Body:

notes string Sichtbare Notiz auf der Gutschrift
items array Ersetzt alle Positionen

Gutschrift löschen

DELETE /api/flowaccounting/credit-notes/{uuid}

Löscht eine Gutschrift im Status draft; sonst 422.

Gutschrift ausstellen

POST /api/flowaccounting/credit-notes/{uuid}/issue

Stellt die Gutschrift aus und vergibt ihre Nummer, sofern beim Anlegen keine vorgegeben wurde. Ist die zugrunde liegende Rechnung über Stripe bezahlt, wird die Erstattung angestoßen. Das Feld refund_status meldet started, not_required oder review_required. Nur im Status draft möglich; sonst 422. Ebenfalls 422, wenn die verknüpfte Rechnung noch ein Entwurf ist (zuerst die Rechnung ausstellen), wenn sie storniert wurde oder wenn sie ihre Steuerbehandlung geändert hat, seit die Gutschrift gespeichert wurde: Dann die Gutschrift zuerst per PUT mit ihren Positionen neu speichern.

Gutschrift verrechnen

POST /api/flowaccounting/credit-notes/{uuid}/settle

Verrechnet eine ausgestellte Gutschrift und bucht dafür genau eine Transaktion vom Typ credit. Mit mode offset wird der Betrag auf die verknüpfte Rechnung gebucht: Er darf weder die Gutschriftsumme noch den offenen Betrag der Rechnung übersteigen, und Rechnung und Gutschrift müssen dieselbe Währung führen. Deckt die Buchung den offenen Betrag, gilt die Rechnung als bezahlt (paid), sonst als teilweise bezahlt (partially_paid); eine Rechnung im Entwurf oder eine stornierte Rechnung wird abgelehnt. Mit pool wandert der Betrag ohne Rechnungsbezug ins Guthaben des Kunden und steht dort für spätere Rechnungen zur Verfügung. In beiden Fällen ist die Gutschrift danach vollständig verrechnet (settled), auch bei einem Teilbetrag: Der Rest wandert nicht ins Guthaben und lässt sich nicht nachträglich verrechnen. Ohne amount wird der höchste zulässige Betrag gebucht. transaction_date ist für die Übernahme historischer Belege gedacht und legt das Buchungsdatum der Transaktion fest. Die Antwort enthält die Gutschrift in data, die gebuchte Transaktion in transaction und bei offset den Stand der Rechnung in invoice (uuid, invoice_number, status, paid_date, remaining_amount); bei pool ist invoice null. Der Aufruf ist über den Status abgesichert: Eine Wiederholung bucht nichts und liefert 422 mit credit_note_already_settled, ein Entwurf oder eine stornierte Gutschrift 422 mit credit_note_not_issued. Weitere Ablehnungen mit 422: credit_note_without_invoice, invoice_not_settleable, currency_mismatch, amount_exceeds_limit und transaction_date_out_of_range.

Request Body:

mode string * <code>offset</code> (mit der verknüpften Rechnung verrechnen) oder <code>pool</code> (dem Guthaben des Kunden gutschreiben)
amount number Zu buchender Betrag, mindestens 0,01. Standard: die Gutschriftsumme, bei <code>offset</code> höchstens der offene Betrag der Rechnung
transaction_date string Buchungsdatum (YYYY-MM-DD, Standard: heute). Frühestens das Gutschriftsdatum, spätestens heute

Gutschrift stornieren

POST /api/flowaccounting/credit-notes/{uuid}/cancel

Storniert eine Gutschrift im Status draft oder issued; der Aufruf hat keinen Body. Die Stornierung ist endgültig. Beleg und Nummer bleiben erhalten: Die Gutschrift lässt sich weiter abrufen, und ihre Nummer wird nicht wieder frei. Das gilt auch für einen Entwurf, der mit vorgegebener credit_note_number angelegt wurde; er belegt diese Nummer weiter. Eine verrechnete oder bereits stornierte Gutschrift liefert 422 mit action_not_available. Ebenfalls 422, mit credit_note_refund_started, wenn für die verknüpfte Rechnung eine Stripe-Erstattung angestoßen wurde, die nicht fehlgeschlagen ist: Das Geld ist dann an den Kunden zurückgeflossen, und der Beleg dazu muss bestehen bleiben.

Gutschrift per E-Mail versenden

POST /api/flowaccounting/credit-notes/{uuid}/send

Versendet die ausgestellte Gutschrift an genau eine Adresse; mehrere Empfänger werden mit 422 abgelehnt. Erfordert einen Header Idempotency-Key im UUID-Format. Ohne recipient_emails gilt die hinterlegte Adresse des Kunden.

Request Body:

recipient_emails array Genau eine abweichende Empfängeradresse

Gutschrifts-PDF herunterladen

GET /api/flowaccounting/credit-notes/{uuid}/pdf BINARY

Liefert die Gutschrift als PDF-Datei (application/pdf) im Dokumentlayout des Teams.

🧾 Ausgaben

Belege
Ein Beleg wird als Datei hochgeladen (multipart/form-data), nicht als Link: erlaubt sind PDF, JPEG und PNG bis 10 MB. Die Datei liegt auf einem privaten Speicher und ist ausschließlich über den Download-Endpoint erreichbar, nie über eine öffentliche Adresse.

Ausgaben auflisten

GET /api/flowaccounting/expenses

Ruft eine paginierte Liste aller Ausgaben des Teams ab, sortiert nach Buchungsdatum, absteigend.

Query-Parameter:

status string Filter: pending oder booked
supplier_uuid string Filter nach Lieferanten-UUID
expense_category_uuid string Filter nach Kategorie-UUID
search string Suchbegriff (Beschreibung, Lieferanten-Rechnungsnummer)
from string Buchungsdatum ab (YYYY-MM-DD)
to string Buchungsdatum bis (YYYY-MM-DD)
per_page integer Anzahl pro Seite (1-200, Standard: 25)

Ausgabe erfassen

POST /api/flowaccounting/expenses

Erfasst eine Ausgabe im Status pending; gebucht wird sie in einem eigenen Schritt über POST /api/flowaccounting/expenses/{uuid}/book. Netto-, Steuer- und Bruttobetrag werden aus gross_amount, tax_rate und vat_mode berechnet. Eine zweite Ausgabe mit derselben Lieferanten-Rechnungsnummer desselben Lieferanten wird mit 422 abgelehnt.

Request Body:

booking_date string * Buchungsdatum (YYYY-MM-DD)
gross_amount number * Bruttobetrag
tax_rate number Steuersatz in Prozent (Standard: Steuersatz des Teams)
vat_mode string full, none oder reverse_charge (Standard: full)
currency_code string EUR, USD, CHF oder GBP
supplier_uuid string Lieferanten-UUID
expense_category_uuid string Kategorie-UUID
supplier_invoice_number string Rechnungsnummer des Lieferanten
description string Kurze Beschreibung
notes string Interne Notiz

Ausgaben-Details abrufen

GET /api/flowaccounting/expenses/{uuid}

Ausgaben-Details einschließlich der berechneten Beträge sowie has_receipt und receipt_name.

Ausgabe aktualisieren

PUT /api/flowaccounting/expenses/{uuid}

Ändert eine Ausgabe im Status pending. Bereits gebuchte Ausgaben bleiben unverändert und werden mit 422 abgelehnt.

Request Body:

gross_amount number Bruttobetrag
expense_category_uuid string Kategorie-UUID
description string Kurze Beschreibung

Ausgabe löschen

DELETE /api/flowaccounting/expenses/{uuid}

Löscht eine Ausgabe im Status pending; sonst 422.

Beleg hochladen

POST /api/flowaccounting/expenses/{uuid}/receipt

Hängt den Beleg als multipart/form-data an die Ausgabe. Erlaubt sind PDF, JPEG und PNG bis 10 MB. Ein vorhandener Beleg wird ersetzt, sobald der neue gespeichert ist. Bei bereits gebuchten Ausgaben antwortet die API mit 422.

Request Body:

file file * Belegdatei (PDF, JPEG oder PNG, höchstens 10 MB)

Ausgabe buchen

POST /api/flowaccounting/expenses/{uuid}/book

Bucht eine Ausgabe im Status pending: Sie wechselt in den Status booked und erhält das Zahlungsdatum paid_date. Erst eine gebuchte Ausgabe zählt in den Berichten, und zwar im Zeitraum ihres Zahlungsdatums. Die Reihenfolge ist: Ausgabe anlegen, Beleg hochladen, buchen. Nach dem Buchen sind Ändern, Löschen und der Austausch des Belegs über die API gesperrt (422). Das Buchen lässt sich über die API nicht rückgängig machen; eine gebuchte Ausgabe wird in der Weboberfläche korrigiert. Der Aufruf ist über den Status abgesichert: Eine Wiederholung bucht nichts und liefert 422 mit expense_booked.

Request Body:

paid_date string * Zahlungsdatum (YYYY-MM-DD), höchstens heute

Beleg herunterladen

GET /api/flowaccounting/expenses/{uuid}/receipt BINARY

Liefert die hinterlegte Belegdatei. Ohne Beleg antwortet die API mit 404.

🚚 Lieferanten

Verwendete Lieferanten
Ein Lieferant, auf den bereits Ausgaben gebucht sind, lässt sich nicht löschen. Er wird stattdessen über is_active deaktiviert und verschwindet aus den Auswahllisten, ohne die Historie zu verändern.

Lieferanten auflisten

GET /api/flowaccounting/suppliers

Ruft eine paginierte Liste aller Lieferanten des Teams ab, alphabetisch sortiert.

Query-Parameter:

is_active boolean Filter: nur aktive oder nur inaktive Lieferanten
search string Suchbegriff im Namen
per_page integer Anzahl pro Seite (1-200, Standard: 25)

Lieferant anlegen

POST /api/flowaccounting/suppliers

Legt einen Lieferanten an.

Request Body:

name string * Name des Lieferanten
address string Anschrift
vat_id string Umsatzsteuer-Identifikationsnummer
tax_id string Steuernummer
email string E-Mail-Adresse
phone string Telefonnummer
is_active boolean Aktiv (Standard: true)

Lieferanten-Details abrufen

GET /api/flowaccounting/suppliers/{uuid}

Lieferanten-Details abrufen.

Lieferant aktualisieren

PUT /api/flowaccounting/suppliers/{uuid}

Ändert einen Lieferanten. Es werden nur die gesendeten Felder geändert.

Request Body:

name string Name des Lieferanten
is_active boolean Aktiv

Lieferant löschen

DELETE /api/flowaccounting/suppliers/{uuid}

Löscht einen Lieferanten, auf den noch keine Ausgabe gebucht ist. Andernfalls antwortet die API mit 422 und dem Hinweis, den Lieferanten zu deaktivieren.

🗂️ Ausgabenkategorien

Kategorien werden deaktiviert
Kategorien lassen sich nicht löschen: eine entfernte Kategorie würde sich von jeder Ausgabe lösen, die je unter ihr gebucht wurde, und damit vergangene Auswertungen verändern. Der Löschaufruf antwortet deshalb mit 422; zum Ausblenden dient is_active.

Ausgabenkategorien auflisten

GET /api/flowaccounting/expense-categories

Ruft eine paginierte Liste aller Ausgabenkategorien des Teams ab, alphabetisch sortiert.

Query-Parameter:

is_active boolean Filter: nur aktive oder nur inaktive Kategorien
search string Suchbegriff im Namen
per_page integer Anzahl pro Seite (1-200, Standard: 25)

Ausgabenkategorie anlegen

POST /api/flowaccounting/expense-categories

Legt eine Ausgabenkategorie an. Mit parent_uuid wird sie einer übergeordneten Kategorie untergeordnet; eine Verkettung im Kreis wird mit 422 abgelehnt.

Request Body:

name string * Name der Kategorie
number string Kontonummer
parent_uuid string UUID der übergeordneten Kategorie
euer_group string Zuordnung in der Einnahmenüberschussrechnung
is_active boolean Aktiv (Standard: true)

Ausgabenkategorie abrufen

GET /api/flowaccounting/expense-categories/{uuid}

Details einer Ausgabenkategorie einschließlich parent_uuid.

Ausgabenkategorie aktualisieren

PUT /api/flowaccounting/expense-categories/{uuid}

Ändert eine Ausgabenkategorie. Es werden nur die gesendeten Felder geändert.

Request Body:

name string Name der Kategorie
is_active boolean Aktiv

Ausgabenkategorie löschen

DELETE /api/flowaccounting/expense-categories/{uuid}

Antwortet mit 422: Kategorien werden deaktiviert und nicht gelöscht. Der Endpoint besteht, damit der Grund benannt wird statt stillschweigend zu wirken.

🗃️ Einnahmenkategorien

Einnahmenkategorien auflisten

GET /api/flowaccounting/income-categories

Ruft eine paginierte Liste aller Einnahmenkategorien des Teams ab, alphabetisch sortiert.

Query-Parameter:

is_active boolean Filter: nur aktive oder nur inaktive Kategorien
income_group string Filter: umsatz, kapital, privat oder sonstige
search string Suchbegriff im Namen
per_page integer Anzahl pro Seite (1-200, Standard: 25)

Einnahmenkategorie anlegen

POST /api/flowaccounting/income-categories

Legt eine Einnahmenkategorie an.

Request Body:

name string * Name der Kategorie
number string Kontonummer
income_group string umsatz, kapital, privat oder sonstige
is_active boolean Aktiv (Standard: true)

Einnahmenkategorie abrufen

GET /api/flowaccounting/income-categories/{uuid}

Details einer Einnahmenkategorie.

Einnahmenkategorie aktualisieren

PUT /api/flowaccounting/income-categories/{uuid}

Ändert eine Einnahmenkategorie. Es werden nur die gesendeten Felder geändert.

Request Body:

name string Name der Kategorie
is_active boolean Aktiv

Einnahmenkategorie löschen

DELETE /api/flowaccounting/income-categories/{uuid}

Antwortet mit 422: Kategorien werden deaktiviert und nicht gelöscht.

📈 Berichte und Kontext

Währungen bleiben getrennt
Berichte rechnen nichts um. Jede Währung wird einzeln ausgewiesen, damit keine erfundene Umrechnung in die Auswertung gerät. Das Feld basis jeder Antwort benennt, worauf die Zahlen beruhen, etwa Rechnungsdatum oder Zahlungseingang.

Bericht abrufen

GET /api/flowaccounting/reports/{kind}

Liefert einen Bericht für den angegebenen Zeitraum. Mögliche Werte für kind: open_items (offene Posten), revenue (Rechnungsumsatz), revenue_per_client (Umsatz je Kunde), cash_flow (Einnahmen und Ausgaben nach Zahlungseingang), euer (Einnahmenüberschussrechnung) und profit_loss (Gewinn und Verlust). client_uuid ist nur bei open_items, revenue und revenue_per_client zulässig, sonst 422. Entwürfe und stornierte Rechnungen bleiben in jedem Bericht außen vor.

Query-Parameter:

from string * Beginn des Zeitraums (YYYY-MM-DD)
to string * Ende des Zeitraums (YYYY-MM-DD, nicht vor from)
client_uuid string Auf einen Kunden einschränken
page integer Seite der Ergebnisliste, 50 Zeilen je Seite

Schreibkontext abrufen

GET /api/flowaccounting/context

Liefert die Dokumentvorgaben des Teams, die Steuersätze und je Datensatzart die vollständige Liste der schreibbaren Felder. Damit lässt sich ein gültiger Rumpf für Angebote, Rechnungen, Gutschriften, Ausgaben, Lieferanten und Kategorien aufbauen, ohne die Feldnamen zu erraten. Verknüpfungen erscheinen unter ihren öffentlichen Namen, etwa client_uuid statt einer internen Nummer.

📥 Belege aus einem Fremdsystem übernehmen

Übernommene Rechnungen bleiben aus den automatischen Läufen heraus
Eine Rechnung mit einem Versanddatum vor dem Tag ihrer Erfassung gilt als übernommener Altbeleg. Sie wird nicht automatisch gemahnt und nicht automatisch abgebucht, auch wenn sie noch offen ist. Von Hand lässt sie sich weiterhin mahnen und abbuchen.
Nicht über den Status stornieren
Eine übernommene Rechnung, die im Fremdsystem per Gutschrift storniert wurde, wird hier ebenfalls über ihre Gutschrift ausgeglichen und steht danach auf paid. Setzen Sie sie nicht auf cancelled: Die Rechnung bekäme dabei eine neue Nummer aus dem laufenden Nummernkreis, und eine Gutschrift zu einer stornierten Rechnung lässt sich weder ausstellen noch mit ihr verrechnen.

Rechnungen und Gutschriften, die in einem anderen System ausgestellt wurden, lassen sich mit ihren ursprünglichen Nummern und Daten übernehmen. Die Reihenfolge der Aufrufe ist dabei festgelegt. Sie gilt für manuelle Rechnungen (source manual, der Standard beim Anlegen).

1. Nummernkreise vorbereiten

Folgen die zu übernehmenden Nummern dem Format Ihres laufenden Nummernkreises, setzen Sie zuerst in den FlowAccounting-Einstellungen die nächste Rechnungsnummer und die nächste Gutschriftnummer über die höchste Nummer, die Sie übernehmen. Eine vorgegebene Nummer, die im laufenden Nummernkreis auf oder über dem nächsten Zählerstand liegt, wird mit 422 abgelehnt. Vorgegebene Nummern verändern den Zähler nicht.

2. Rechnung anlegen

POST /api/flowaccounting/invoices mit invoice_number, dem ursprünglichen invoice_date und due_date sowie den Positionen. Die Rechnung entsteht als Entwurf. Ohne payment_method erhält sie die Zahlungsart bank_transfer, ein beim Kunden hinterlegtes Zahlungsmittel wird nicht übernommen. Lassen Sie send weg, sonst geht die Rechnung per E-Mail an den Kunden.

3. Als versendet markieren

POST /api/flowaccounting/invoices/{uuid}/status mit status sent und dem ursprünglichen Versanddatum als sent_date. Dabei wird keine E-Mail verschickt. Ohne sent_date gilt der heutige Tag, und die Rechnung nimmt wie jede neu ausgestellte an den automatischen Läufen teil.

4. Bezahlte Rechnung: Zahlung buchen

POST /api/flowaccounting/invoices/{uuid}/transactions mit type payment, dem Betrag und dem ursprünglichen Zahlungsdatum als transaction_date. Gleicht die Zahlung die Rechnung aus, steht sie auf paid und übernimmt das transaction_date als paid_date.

5. Per Gutschrift stornierte Rechnung: Gutschrift übernehmen

Legen Sie die Gutschrift mit POST /api/flowaccounting/credit-notes an und geben Sie credit_note_number, die invoice_uuid der übernommenen Rechnung und credit_note_date mit. Stellen Sie sie mit POST /api/flowaccounting/credit-notes/{uuid}/issue aus; Nummer und Datum bleiben dabei erhalten. Verrechnen Sie sie danach mit POST /api/flowaccounting/credit-notes/{uuid}/settle, mode offset und dem ursprünglichen Datum als transaction_date. Deckt die Gutschrift den offenen Betrag, steht die Rechnung auf paid und übernimmt das transaction_date als paid_date. Die Detailantwort der Rechnung nennt die Gutschrift unter credit_notes.

Worauf Sie achten sollten

  • Löschen Sie einen Entwurf mit vorgegebener Nummer nicht. Die Nummer bleibt auch nach dem Löschen belegt und lässt sich kein zweites Mal vergeben. Korrigieren Sie den Entwurf stattdessen per PUT und seine Positionen über die Positionen-Endpoints. Die Nummer selbst lässt sich nach dem Anlegen nicht mehr ändern.
  • Eine Transaktion vom Typ credit an der Rechnung ersetzt keine Gutschrift. Sie bucht nur einen Betrag auf die Rechnung; ein Gutschriftbeleg mit eigener Nummer entsteht dabei nicht.
  • Das Buchungsdatum der Verrechnung liegt frühestens auf dem Gutschriftsdatum und spätestens heute, das Versanddatum der Rechnung frühestens auf dem Rechnungsdatum und spätestens heute.

⚠️ Status-Übergänge

📊 Response-Format

Erfolgreiche Antwort

Listen-Endpoints liefern zusätzlich ein meta-Objekt mit Pagination-Informationen.

{"success": true, "data": {...}, "meta": {"current_page": 1, "per_page": 15, "total": 42}}

Fehler-Antwort

Fehler verwenden durchgehend das Feld message. Validierungsfehler (422) enthalten zusätzlich errors.

Status-Übergänge

Der Rechnungsstatus folgt einer festen Zustandsmaschine. Der Endpoint POST /invoices/{uuid}/status erlaubt direkt nur die Übergänge nach sent und cancelled. Zahlungsbezogene Status (partially_paid, paid) entstehen automatisch durch Transaktionen bzw. den mark-paid-Endpoint. Das Feld allowed_transitions jeder Rechnung zeigt die aktuell möglichen Folgestatus.

Von Status Mögliche Folgestatus
draft sent, cancelled
sent paid, partially_paid, overdue, past_due, cancelled
partially_paid paid, overdue, past_due, cancelled
overdue paid, partially_paid, past_due, cancelled
past_due paid, partially_paid, overdue, cancelled
paid cancelled
cancelled Endstatus (keine weiteren Übergänge)