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

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

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 vergeben. 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)
notes string Sichtbare Notiz auf der Rechnung
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.

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

💰 Rechnungspositionen

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
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, sonst Team-Standard)
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

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

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

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

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 anlegen

POST /api/flowaccounting/products

Neues Produkt anlegen.

Request Body:

title string * Produktname (max 255)
unit_price number * Einzelpreis (min 0)
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 Einzelpreis
tax_rate number Steuersatz
is_active boolean Aktiv

Produkt löschen

DELETE /api/flowaccounting/products/{uuid}

Produkt löschen.

🏷️ Steuersätze

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

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

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

🧮 Abrechenbare Positionen

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

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)

⚠️ Status-Übergänge

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

📊 Response-Format

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

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)