API für Entwickler

Die öffentliche REST-API von EUFactura (Scale-Tarif) ermöglicht es Ihren eigenen Tools — einem CRM, einem Online-Shop, einem eigenen Skript — Kunden anzulegen, Rechnungen und Angebote zu entwerfen und auszustellen, Zahlungen zu erfassen und über wichtige Ereignisse per Webhook benachrichtigt zu werden. Jeder Endpunkt nutzt exakt dieselbe Logik wie die EUFactura-Anwendung selbst, sodass sich über die API nichts anders verhält als in der Oberfläche.

Vollständige Referenz

Die vollständige API ist als OpenAPI-3.1-Spezifikation beschrieben — importieren Sie sie direkt in Postman, Insomnia oder ein beliebiges OpenAPI-fähiges Tool.

Authentifizierung

Erstellen Sie einen Schlüssel auf der Seite Einstellungen → Entwickler Ihrer Organisation (nur Inhaber/Administrator). Jeder Schlüssel ist auf eine Organisation beschränkt und trägt eine Rolle — member (Lesen und Schreiben) oder accountant (nur Lesen). Das vollständige Geheimnis wird nur einmal bei der Erstellung angezeigt; bewahren Sie es sicher auf.

curl https://app.eufactura.eu/api/v1/customers?companyId=<company-id> \
  -H "Authorization: Bearer eufk_..."

Einen Kunden anlegen und eine Rechnung ausstellen

curl -X POST https://app.eufactura.eu/api/v1/customers \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "<company-id>",
    "type": "business",
    "legalName": "Acme GmbH",
    "countryCode": "DE"
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a UUID you generate>" \
  -d '{
    "companyId": "<company-id>",
    "customerId": "<customer-id>",
    "currency": "EUR",
    "issueDate": "2026-01-01",
    "lines": [{ "description": "Consulting", "quantity": "1", "unitPriceNet": "500" }]
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices/<invoice-id>/issue \
  -H "Authorization: Bearer eufk_..."

Rechnungen werden immer zunächst als Entwurf angelegt und in einem separaten, expliziten Schritt ausgestellt — das Ausstellen weist die gesetzliche Rechnungsnummer zu und macht die Rechnung unveränderlich, genau wie in der App selbst.

Idempotenz

Senden Sie bei einer datenverändernden Anfrage einen Header Idempotency-Key (eine von Ihnen erzeugte Zeichenfolge, typischerweise eine UUID). Ein Wiederholen derselben Anfrage mit demselben Schlüssel liefert die ursprüngliche Antwort zurück, anstatt die Aktion ein zweites Mal auszuführen — sicher gegenüber Netzwerkwiederholungen und Doppelklicks.

Ratenlimits

Anfragen sind pro API-Schlüssel begrenzt. Eine Antwort über dem Limit liefert 429 mit einem zu Retry-After äquivalenten Feld retryAfter im Fehlertext.

Fehler

Jeder Fehler wird als {"error": {"code": "...", "message": "..."}} zurückgegeben. Eine Ressourcen-ID, die zu einer anderen Organisation gehört, liefert immer 404, niemals 403 — EUFactura bestätigt niemals, dass eine Ressource existiert, bevor bestätigt wird, dass Sie darauf zugreifen dürfen.

Webhooks

Registrieren Sie eine Endpunkt-URL und wählen Sie unter Einstellungen → Entwickler aus, welche Ereignisse Sie erhalten möchten: invoice.issued, invoice.payment_recorded, quote.converted und credit_note.issued. Jede Zustellung ist ein signierter HTTPS-POST:

POST <your endpoint>
Content-Type: application/json
X-EUFactura-Signature: t=1700000000,v1=<hex-encoded HMAC-SHA256>

{"id": "...", "type": "invoice.issued", "data": { ... }}

Prüfen Sie sie, indem Sie einen HMAC-SHA256 aus dem Zeitstempel, einem literalen Punkt und dem rohen Request-Body mit dem Geheimnis Ihres Endpunkts berechnen und das Ergebnis mit dem Wert v1 vergleichen — dasselbe Format t=...,v1=..., das Stripe selbst für seine Webhooks verwendet, sodass jeder bereits vorhandene Stripe-Webhook-Verifizierungscode ein guter Ausgangspunkt ist. Zustellungen werden bei Fehlschlag mit Backoff wiederholt (bis zu fünf Versuche über etwa 12 Stunden); Ihr Endpunkt sollte in Bezug auf die id der Nutzlast idempotent sein.

Fragen

Erreichen Sie uns unter hello@eufactura.eu.