API-Zugang

Info: API-Zugang ist im Business-Tarif verfügbar.

API-Schlüssel

API-Schlüssel können in den Organisationseinstellungen erstellt werden. Jeder Schlüssel ist einer einzelnen Organisation zugeordnet und gewährt programmatischen Zugriff auf die Rekivo-API.

Warning: Halten Sie Ihre API-Schlüssel geheim. Teilen Sie sie nicht in clientseitigem Code oder öffentlichen Repositories. Rotieren Sie Schlüssel sofort, wenn sie kompromittiert wurden.

Authentifizierung

Fügen Sie Ihren API-Schlüssel in den Authorization-Header jeder Anfrage ein:

Authorization: Bearer rek_ihr_api_schluessel

Alle API-Antworten sind JSON. Fehler geben einen { "message": "..." } Body mit dem entsprechenden HTTP-Statuscode zurück.

Granulare Berechtigungen

Beim Erstellen eines API-Schlüssels können Sie seine Berechtigungen auf bestimmte Scopes einschränken. Schlüssel ohne zugewiesene Scopes haben vollen Zugriff (abwärtskompatibel).

Scope	Beschreibung
invoices:read	Rechnungen auflisten, Details einsehen, XML/PDF herunterladen
invoices:write	Metadaten aktualisieren, Workflow-Status ändern, Kommentare hinzufügen
invoices:delete	Rechnungen löschen
upload:write	Neue Rechnungen hochladen
export:read	Exporte auflisten und Archive herunterladen
export:write	Neue Exporte erstellen

Tip: Verwenden Sie das Prinzip der minimalen Berechtigung — erstellen Sie Schlüssel nur mit den Scopes, die Ihre Integration benötigt. Eine reine Lese-Dashboard-Integration braucht beispielsweise nur invoices:read.

Verfügbare Endpunkte

Rechnungen

GET/api/invoicesAlle Rechnungen auflisten (paginiert)

GET/api/invoices/:idRechnungsdetails abrufen

GET/api/invoices/:id/xmlOriginal-XML herunterladen

GET/api/invoices/:id/pdfGenerierte PDF herunterladen

PATCH/api/invoices/:id/metadataRechnungsmetadaten aktualisieren

DELETE/api/invoices/:idRechnung löschen

Statusänderungen

POST/api/invoices/:id/approveRechnung freigeben

POST/api/invoices/:id/rejectRechnung ablehnen

POST/api/invoices/:id/mark-paidAls bezahlt markieren

POST/api/invoices/:id/archiveRechnung archivieren

Upload

POST/api/uploadNeue Rechnung hochladen (Multipart-Formular)

Export

GET/api/exportAktuelle Exporte auflisten

POST/api/exportNeuen Export erstellen

GET/api/export/:id/downloadExport-Archiv herunterladen

Rate-Limiting

API-Anfragen werden pro Schlüssel ratenbegrenzt. Bei Überschreitung erhalten Sie eine 429 Too Many Requests-Antwort. Die Antwort enthält Retry-After-Header, die angeben, wann Sie es erneut versuchen können.

Fehlercodes

Status	Bedeutung
400	Ungültige Anfrage — fehlerhafte Parameter
401	Nicht autorisiert — fehlender oder ungültiger API-Schlüssel
403	Unzureichende Berechtigungen oder Tarif
404	Nicht gefunden
429	Rate-Limit überschritten
500	Interner Serverfehler