Public API - Belege Admin

📕 Für Administratoren und Entwickler

Über die spiritflow Public API können Belege (eingehende Rechnungen, Kassenbelege, Reisekostenabrechnungen) programmatisch verwaltet und durch den Genehmigungs-Workflow gesteuert werden. Alle Endpunkte sind unter dem Basis-Pfad /api/v1/receipts erreichbar und erfordern einen gültigen API-Key mit dem entsprechenden Scope.

Referenzwerte

Beleg-Status-Werte

Status	Bedeutung
`UPLOADED`	Hochgeladen (noch nicht eingereicht)
`SUBMITTED`	Eingereicht
`IN_REVIEW`	In Prüfung
`APPROVED`	Genehmigt
`REJECTED`	Abgelehnt
`SETTLED`	Abgerechnet
`WITHDRAWN`	Zurückgezogen
`VOIDED`	Entwertet

Zahlungsstatus-Werte

Status	Bedeutung
`OPEN`	Offen
`PAID`	Bezahlt
`OVERDUE`	Überfällig

Beleg-Typen

Typ	Bedeutung
`INVOICE`	Eingangsrechnung
`RECEIPT`	Kassenbeleg
`CREDIT_NOTE`	Gutschrift
`TRAVEL_EXPENSE`	Reisekostenabrechnung
`OTHER`	Sonstiger Beleg

Belege auflisten

GET /api/v1/receipts

Erforderlicher Scope: receipts:read

Query-Parameter:

Parameter	Typ	Pflicht	Beschreibung
`status`	String	Nein	Filtert nach Belegstatus (z.B. `APPROVED`)
`paymentStatus`	String	Nein	Filtert nach Zahlungsstatus (`OPEN`, `PAID`, `OVERDUE`)
`categoryId`	Long	Nein	Filtert nach Kategorie-ID
`receiptDateAfter`	String	Nein	Belegdatum ab (YYYY-MM-DD)
`receiptDateBefore`	String	Nein	Belegdatum bis (YYYY-MM-DD)
`supplierName`	String	Nein	Textsuche im Lieferantennamen
`active`	Boolean	Nein	`true` = nur aktive Belege (UPLOADED bis SETTLED), `false` = nur inaktive (WITHDRAWN/REJECTED/VOIDED), nicht gesetzt = alle
`page`	Integer	Nein	Seitennummer (Standard: `0`)
`size`	Integer	Nein	Einträge pro Seite, max. 100 (Standard: `20`)
`sort`	String	Nein	Sortierung (Standard: `createdAt,desc`). Erlaubte Felder: `createdAt`, `updatedAt`, `receiptDate`, `dueDate`, `grossAmount`, `status`, `receiptNumber`, `supplierName`

Antwort (200 OK):

{
  "data": [
    {
      "id": 42,
      "receiptNumber": "BLG-2025-0001",
      "externalInvoiceNumber": "RE-2025-00123",
      "type": "INVOICE",
      "status": "APPROVED",
      "isActive": true,
      "supplierName": "Bürobedarfs GmbH",
      "receiptDate": "2025-03-01",
      "dueDate": "2025-03-31",
      "netAmount": 84.03,
      "vatRate": 19.00,
      "vatAmount": 15.97,
      "grossAmount": 100.00,
      "currency": "EUR",
      "paymentStatus": "OPEN",
      "paymentMethod": null,
      "paymentDate": null,
      "categoryId": 3,
      "categoryName": "Bürobedarf",
      "projectId": null,
      "projectName": null,
      "submittedById": 5,
      "submittedByName": "Lisa Schmidt",
      "notes": null,
      "attachmentCount": 1,
      "createdAt": "2025-03-01T09:00:00Z",
      "updatedAt": "2025-03-05T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-03-01T10:30:00Z"
  }
}

cURL-Beispiel:

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

Einzelnen Beleg abrufen

GET /api/v1/receipts/{id}

Erforderlicher Scope: receipts:read

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Belegs

Antwort (200 OK): Einzelnes Belegobjekt (gleiche Struktur wie in der Liste)

Fehler-Codes:

HTTP-Status	Code	Beschreibung
404	`NOT_FOUND`	Beleg nicht gefunden

cURL-Beispiel:

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

Beleg erstellen

POST /api/v1/receipts

Erstellt einen neuen Beleg. Neue Belege erhalten automatisch eine Belegnummer und den Status SUBMITTED.

Erforderlicher Scope: receipts:write

Request-Body:

Feld	Typ	Pflicht	Standard	Beschreibung
`receiptDate`	String	Ja	-	Belegdatum (YYYY-MM-DD)
`grossAmount`	number	Ja	-	Bruttobetrag (>= 0)
`externalInvoiceNumber`	String	Nein	`null`	Externe Rechnungsnummer (max. 255 Zeichen)
`type`	String	Nein	`INVOICE`	Belegtyp (siehe Beleg-Typen oben)
`supplierName`	String	Nein	`null`	Lieferantenname (max. 255 Zeichen)
`dueDate`	String	Nein	`null`	Fälligkeitsdatum (YYYY-MM-DD)
`netAmount`	number	Nein	`null`	Nettobetrag
`vatRate`	number	Nein	`null`	Mehrwertsteuersatz in Prozent (z.B. `19.0`)
`currency`	String	Nein	`EUR`	Währungscode (ISO 4217, z.B. `EUR`)
`categoryId`	Long	Nein	`null`	ID der Belegkategorie
`projectId`	Long	Nein	`null`	ID des zugehörigen Projekts
`notes`	String	Nein	`null`	Notizen (max. 500 Zeichen)

Beispiel-Request:

{
  "receiptDate": "2025-03-01",
  "grossAmount": 100.00,
  "supplierName": "Bürobedarfs GmbH",
  "externalInvoiceNumber": "RE-2025-00123",
  "netAmount": 84.03,
  "vatRate": 19.0,
  "type": "INVOICE",
  "categoryId": 3
}

Antwort (201 Created): Erstelltes Belegobjekt

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Pflichtfeld fehlt oder Feldwert ungültig

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/receipts" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "receiptDate": "2025-03-01",
    "grossAmount": 100.00,
    "supplierName": "Bürobedarfs GmbH",
    "externalInvoiceNumber": "RE-2025-00123"
  }'

Beleg aktualisieren

PATCH /api/v1/receipts/{id}

Aktualisiert einen vorhandenen Beleg (PATCH-Semantik). Nur angegebene Felder werden geändert.

Erforderlicher Scope: receipts:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Belegs

Request-Body: Gleiche Felder wie beim Erstellen, alle optional.

Antwort (200 OK): Aktualisiertes Belegobjekt

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Validierungsfehler
404	`NOT_FOUND`	Beleg nicht gefunden

cURL-Beispiel:

curl -X PATCH "https://app.spiritflow.team/api/v1/receipts/42" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "supplierName": "Neue Bürobedarfs GmbH",
    "categoryId": 5
  }'

Beleg-Status ändern

PATCH /api/v1/receipts/{id}/status

Ändert den Workflow-Status eines Belegs für reguläre Vorwärts-Übergänge.

Erlaubte Übergänge:

UPLOADED → SUBMITTED
SUBMITTED → IN_REVIEW
IN_REVIEW → APPROVED
APPROVED → SETTLED

Für Zurückziehen, Ablehnen und Entwerten stehen dedizierte Endpoints zur Verfügung (über die spiritflow-Anwendung).

Erforderlicher Scope: receipts:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Belegs

Request-Body:

Feld	Typ	Pflicht	Beschreibung
`status`	String	Ja	Zielstatus

Antwort (200 OK): Aktualisiertes Belegobjekt

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Ungültiger oder nicht erlaubter Statusübergang
404	`NOT_FOUND`	Beleg nicht gefunden

cURL-Beispiel:

curl -X PATCH "https://app.spiritflow.team/api/v1/receipts/42/status" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "IN_REVIEW"}'

Anhänge eines Belegs

Anhänge auflisten

GET /api/v1/receipts/{id}/attachments

Erforderlicher Scope: receipts:read

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Belegs

Antwort-Felder:

Feld	Typ	Beschreibung
`id`	number	ID des Anhangs
`displayFilename`	String	Dateiname
`contentType`	String?	MIME-Typ
`sizeBytes`	number	Dateigröße in Bytes
`isPrimary`	boolean	Ist dieser Anhang der Hauptbeleg
`attachedByName`	String	Name des Hochladers
`attachedAt`	String	Hochladezeitpunkt (ISO 8601, UTC)

cURL-Beispiel:

curl -X GET "https://app.spiritflow.team/api/v1/receipts/42/attachments" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Anhang herunterladen

GET /api/v1/receipts/{id}/attachments/{attachmentId}/download

Lädt eine Anhang-Datei herunter.

Erforderlicher Scope: receipts:read

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Belegs
`attachmentId`	Long	ID des Anhangs

Antwort: Binäre Datei mit entsprechendem Content-Type-Header

Fehler-Codes:

HTTP-Status	Code	Beschreibung
404	`NOT_FOUND`	Beleg oder Anhang nicht gefunden

Anhang hochladen

POST /api/v1/receipts/{id}/attachments

Lädt eine Datei als Anhang für einen Beleg hoch. Die Datei wird auf Viren gescannt und in MinIO gespeichert.

Erforderlicher Scope: receipts:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Belegs

Request: Multipart Form-Data

Parameter	Typ	Pflicht	Standard	Beschreibung
`file`	multipart	Ja	-	Hochzuladende Datei
`isPrimary`	boolean	Nein	`false`	Ob dieser Anhang der Hauptbeleg ist

Antwort (201 Created): Erstelltes Anhang-Objekt (gleiche Felder wie bei der Anhang-Liste)

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Datei ungültig, zu groß oder infiziert
404	`NOT_FOUND`	Beleg nicht gefunden
422	`VIRUS_DETECTED`	Hochgeladene Datei als Schadsoftware erkannt

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/receipts/42/attachments" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/pfad/zur/rechnung.pdf" \
  -F "isPrimary=true"

Belegkategorien auflisten

GET /api/v1/receipt-categories

Gibt alle Belegkategorien des Mandanten zurück, sortiert nach sort_order. Kategorien können in spiritflow unter Einstellungen > Belege > Kategorien verwaltet werden.

Erforderlicher Scope: receipts:read

Antwort-Felder:

Feld	Typ	Beschreibung
`id`	number	ID der Kategorie
`name`	String	Name der Kategorie
`datevAccountNumber`	String?	DATEV-Kontonummer für Steuerexport
`color`	String?	Farbe der Kategorie (`#RRGGBB`)
`sortOrder`	number	Sortierposition

Antwort (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "Bürobedarf",
      "datevAccountNumber": "4930",
      "color": "#2196F3",
      "sortOrder": 1
    },
    {
      "id": 2,
      "name": "Reisekosten",
      "datevAccountNumber": "4670",
      "color": "#FF9800",
      "sortOrder": 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/receipt-categories" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"