REST-API für Entwickler

E-Rechnungen im Format ZUGFeRD/Factur-X (EN 16931) per HTTP prüfen und erzeugen. Server-zu-Server gedacht, nicht für Aufrufe aus dem Browser.

Authentifizierung

Jeder Aufruf braucht einen API-Key. Den erstellst du in deinem Konto unter finisma.de/konto (Abschnitt „API-Zugang"). Der Key wird als Bearer-Token gesendet:

Authorization: Bearer fnsm_…

Das Prüfen (/verify) ist kostenlos, verlangt aber ebenfalls einen Key. Das Erzeugen (/invoices) setzt ein aktives Abo voraus.

Rechnung prüfen

POST https://finisma.de/api/v1/verify mit der PDF als multipart-Feld pdf. Antwort ist ein JSON-Prüfbericht (Struktur, EN-16931-Regeln, PDF/A-3-Anbindung).

curl -X POST https://finisma.de/api/v1/verify \
  -H "Authorization: Bearer $FINISMA_KEY" \
  -F "pdf=@rechnung.pdf;type=application/pdf"

ZUGFeRD-Rechnung erzeugen

POST https://finisma.de/api/v1/invoices nimmt die visuelle PDF (pdf) und die strukturierten EN-16931-Daten (invoice, JSON) und bettet das CII-XML ein. Die Antwort ist standardmäßig die fertige PDF/A-3 binär. Mit Accept: application/json kommt stattdessen { pdf_base64, bytes }.

curl -X POST https://finisma.de/api/v1/invoices \
  -H "Authorization: Bearer $FINISMA_KEY" \
  -F "pdf=@rechnung.pdf;type=application/pdf" \
  -F "invoice=@invoice.json;type=application/json" \
  -F "filename=rechnung-zugferd.pdf" \
  -o rechnung-zugferd.pdf

Optionale Anhänge werden als weitere attachments-Felder angehängt (PDF, PNG, JPEG, CSV, XLSX, ODS, XML; je max. 10 MB).

Rechnungsdaten (invoice)

Die Datenstruktur folgt EN 16931. Vollständig und maßgeblich steht sie in der OpenAPI-Spezifikation (Schema Invoice). Ein minimales Beispiel:

{
  "invoiceNumber": "2026-001",
  "issueDate": "2026-07-22",
  "currency": "EUR",
  "seller": {
    "name": "Muster GmbH",
    "vatId": "DE123456789",
    "address": { "line1": "Hauptstr. 1", "city": "Hamburg", "postalCode": "20095", "countryCode": "DE" }
  },
  "buyer": {
    "name": "Kunde AG",
    "address": { "line1": "Marktplatz 5", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" }
  },
  "lines": [
    { "name": "Beratung", "quantity": 10, "unitCode": "HUR", "unitPriceNet": 100, "vatRatePercent": 19, "lineNetAmount": 1000 }
  ],
  "vatBreakdown": [
    { "ratePercent": 19, "basisAmount": 1000, "taxAmount": 190, "categoryCode": "S" }
  ],
  "totalNet": 1000,
  "totalVat": 190,
  "totalGross": 1190
}

Fehler

Fehler kommen als JSON { "error", "code", "details" } mit passendem HTTP-Status:

Status	code	Bedeutung
400	invalid_input	Datei oder Rechnungsdaten fehlerhaft.
401	auth_required / invalid_key	Kein Key mitgeschickt bzw. Key ungültig oder widerrufen.
403	subscription_required	Erzeugen ohne aktives Abo.
429	rate_limited	Zu viele Anfragen; Wartezeit im Header Retry-After.
502	upstream_error	Fehler in einem nachgelagerten Dienst.

Hinweise

Die API ist für Server-zu-Server-Aufrufe gedacht. Es werden keine CORS-Header gesetzt, Aufrufe direkt aus dem Browser sind nicht vorgesehen.
Hochgeladene Dateien werden nur für die Verarbeitung gehalten und nicht dauerhaft gespeichert.
Automatisierungen wie n8n nutzen den invoice-Teil als JSON und den pdf-Teil als Binär-Datei im selben multipart-Request.

Maschinenlesbare Spezifikation: https://finisma.de/api/v1/openapi.json