🚀 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, Positionen, Transaktionen, Produkten, Steuersätzen und wiederkehrender Abrechnung. 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. 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, gedacht für den Import von Altrechnungen. 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. Ohne Angabe vergibt der Nummernkreis die Nummer. 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. 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
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.

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

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.

Request Body:

status string * Zielstatus: sent oder cancelled

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.

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 vergeben. 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_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.

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 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.

Request Body:

client_uuid string * Kunden-UUID (teamgebunden)
invoice_uuid string UUID der gutzuschreibenden Rechnung
contact_uuid string Kontakt-UUID des Kunden
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.

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. 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 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. 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)

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.

⚠️ 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)