API - Rechnungen Admin

📕 Für Administratoren und Entwickler.

Über die Public API können Rechnungsdaten aus spiritflow ausgelesen und als PDF heruntergeladen werden. Das Erstellen, Bearbeiten und Löschen von Rechnungen ist ausschließlich über die spiritflow-Anwendung selbst möglich — die Rechnungs-API ist Read-Only.

Basis-Pfad: /api/v1/invoices

Erforderlicher Scope: invoices:read

---

Rechnungs-Status-Werte

Status	Bedeutung
DRAFT	Entwurf (noch keine Rechnungsnummer vergeben)
SENT	Versendet
PAID	Bezahlt
OVERDUE	Überfällig
CANCELLED	Storniert

Hinweis zu Entwuerfen: Bei Rechnungen im Status DRAFT ist das Feld invoiceNumber immer null. Die Rechnungsnummer wird erst beim Versenden (Übergang DRAFT → SENT) vergeben.

---

Rechnungen auflisten

GET /api/v1/invoices

Scope: invoices:read

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
status	String	Nein	Filtern nach Status (z.B. PAID)
customerId	Long	Nein	Filtern nach Kunden-ID
search	String	Nein	Suche in Rechnungsnummer und Titel
createdAfter	String (ISO 8601)	Nein	Nur Rechnungen, die nach diesem Zeitpunkt erstellt wurden
createdBefore	String (ISO 8601)	Nein	Nur Rechnungen, die vor diesem Zeitpunkt erstellt wurden
invoiceDateAfter	String (YYYY-MM-DD)	Nein	Nur Rechnungen mit Rechnungsdatum ab diesem Tag
invoiceDateBefore	String (YYYY-MM-DD)	Nein	Nur Rechnungen mit Rechnungsdatum bis zu diesem Tag
dueDateAfter	String (YYYY-MM-DD)	Nein	Nur Rechnungen mit Zahlungsziel ab diesem Tag
dueDateBefore	String (YYYY-MM-DD)	Nein	Nur Rechnungen mit Zahlungsziel bis zu diesem Tag
page	Integer	Nein	Seite (Standard: 0)
size	Integer	Nein	Einträge pro Seite, max. 100 (Standard: 20)
sort	String	Nein	Sortierung (Standard: invoiceDate,desc). Erlaubte Felder: createdAt, updatedAt, invoiceDate, dueDate, invoiceNumber, status, title

Antwort (200 OK)

{
  "data": [
    {
      "id": 87,
      "invoiceNumber": "RE-2025-0042",
      "title": "Website-Relaunch ACME - Phase 1",
      "description": "Abrechnung der Konzeptionsphase und ersten Designentwuerfe.",
      "customerName": "ACME GmbH",
      "projectName": "Website-Relaunch ACME",
      "netAmount": 3200.00,
      "taxRate": 19.00,
      "taxAmount": 608.00,
      "grossAmount": 3808.00,
      "currency": "EUR",
      "invoiceDate": "2025-02-01",
      "dueDate": "2025-03-01",
      "paidDate": "2025-02-20",
      "status": "PAID",
      "isOverdue": false,
      "isCancellationInvoice": false,
      "lineItems": [
        {
          "description": "Konzeption und Wireframes",
          "quantity": 16.00,
          "unit": "Std",
          "unitPrice": 120.00,
          "netAmount": 1920.00
        },
        {
          "description": "Design-Entwuerfe (3 Varianten)",
          "quantity": 1.00,
          "unit": "Pauschal",
          "unitPrice": 1280.00,
          "netAmount": 1280.00
        }
      ],
      "createdAt": "2025-01-31T16:00:00Z",
      "updatedAt": "2025-02-20T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 28,
    "totalPages": 2
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-03-01T10:30:00Z"
  }
}

cURL-Beispiel

curl -X GET "https://app.spiritflow.team/api/v1/invoices?status=PAID&sort=invoiceDate,desc" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

---

Einzelne Rechnung abrufen

GET /api/v1/invoices/{id}

Scope: invoices:read

Pfad-Parameter

Parameter	Typ	Beschreibung
id	Long	ID der Rechnung

Antwort (200 OK)

Einzelnes PublicInvoiceDto-Objekt mit gleicher Struktur wie in der Liste.

Hinweis: Bei Rechnungsentwuerfen (Status DRAFT) ist invoiceNumber null. In diesem Fall wird null im Feld zurückgegeben.

Fehler-Codes

HTTP-Status	Code	Beschreibung
404	NOT_FOUND	Rechnung nicht gefunden oder gehoert nicht zu diesem Mandanten

cURL-Beispiel

curl -X GET "https://app.spiritflow.team/api/v1/invoices/87" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

---

Rechnungs-PDF herunterladen

GET /api/v1/invoices/{id}/pdf

Scope: invoices:read

Mit diesem Endpunkt kann das fertig generierte PDF einer Rechnung direkt heruntergeladen werden. Das PDF wird on-demand erzeugt und entspricht der aktuellen Rechnungsversion.

Pfad-Parameter

Parameter	Typ	Beschreibung
id	Long	ID der Rechnung

Antwort (200 OK)

PDF-Datei als Binaerdaten.

Response-Header

Header	Beispielwert
Content-Type	application/pdf
Content-Disposition	attachment; filename="RE-2025-0042.pdf"

Fehler-Codes

HTTP-Status	Code	Beschreibung
404	NOT_FOUND	Rechnung nicht gefunden
500	INTERNAL_ERROR	PDF konnte nicht generiert werden

cURL-Beispiel

curl -X GET "https://app.spiritflow.team/api/v1/invoices/87/pdf" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o "rechnung-RE-2025-0042.pdf"

---

Antwort-Felder im Überblick

Feld	Typ	Beschreibung
id	number	Eindeutige ID der Rechnung
invoiceNumber	string oder null	Rechnungsnummer (bei Entwuerfen: null)
title	string	Titel der Rechnung
description	string?	Beschreibungstext
customerName	string?	Name des Kunden
projectName	string?	Name des verknuepften Projekts
netAmount	number	Nettobetrag in der Rechnungswaehrung
taxRate	number	Umsatzsteuersatz in Prozent
taxAmount	number	Umsatzsteuerbetrag
grossAmount	number	Bruttobetrag (inkl. Steuer)
currency	string	Währungscode (z.B. EUR)
invoiceDate	string	Rechnungsdatum (YYYY-MM-DD)
dueDate	string?	Zahlungsziel (YYYY-MM-DD)
paidDate	string?	Zahlungseingang (YYYY-MM-DD), null wenn nicht bezahlt
status	string	Aktueller Status (siehe Tabelle oben)
isOverdue	boolean	Rechnung ist überfällig
isCancellationInvoice	boolean	Handelt es sich um eine Stornorechnung
lineItems	Array	Rechnungspositionen (siehe unten)
createdAt	string	Erstellungszeitpunkt (ISO 8601, UTC)
updatedAt	string	Letzter Aenderungszeitpunkt (ISO 8601, UTC)

Felder einer Rechnungsposition (lineItems)

Feld	Typ	Beschreibung
description	string	Beschreibung der Position
quantity	number	Menge
unit	string?	Einheit (z.B. Std, Pauschal)
unitPrice	number	Einzelpreis
netAmount	number	Positionsbetrag (Menge × Einzelpreis)