API-Schlüssel & Authentifizierung
Die REST-API v1 ist unter https://www.claribill.com/api/v1 erreichbar. Die maschinenlesbare Beschreibung steht unter /openapi.json. Alle Endpunkte einschließlich ihrer Felder finden Sie in der API-Referenz.
Authentifizierung
Senden Sie den API-Key im Authorization-Header:
Authorization: Bearer sk_live_...
Erstellen Sie einen Schlüssel unter Einstellungen → API-Schlüssel. Dafür brauchen Sie das Recht „API-Schlüssel“ (standardmäßig Inhaber und Administrator).
Ein Schlüssel ist nicht an einen Benutzer, eine Rolle oder Dokumentkategorien gebunden: Im Rahmen seiner Scopes erreicht er alle Belege der Firma, unabhängig von Rolle und Kategorien der Person, die ihn anlegt.
Braucht eine Aktion einen handelnden Benutzer (z. B. als Ersteller eines Belegs), gilt der Inhaber der Firma, bei mehreren Inhabern der mit der ältesten Mitgliedschaft. Im Audit-Log sind solche Aktionen als API-Aktionen gekennzeichnet und nennen den verwendeten Schlüssel.
- Bearer-Header prüfen (401 bei fehlendem/ungültigem Header oder unbekanntem Schlüssel).
- Plan-Gate apiAccess prüfen und Monatskontingent als ApiLog-Reservierung buchen (403 code: "plan_no_access", 429 code: "quota_exceeded").
- Scope(s) der Route gegen die Scopes des Schlüssels prüfen (403 mit requiredScopes bei fehlendem Scope).
- Rate-Limit pro Schlüssel prüfen (429, nur mit konfiguriertem Upstash).
Plan-Zugang und Monatskontingent
API-Zugang benötigt das Feature apiAccess (STARTER, PROFESSIONAL, ENTERPRISE). Monatskontingent: STARTER: 10 000 Aufrufe/Monat, PROFESSIONAL: 50 000 Aufrufe/Monat, ENTERPRISE: 250 000 Aufrufe/Monat. Bei Erschöpfung antwortet die API mit 429 und code: "quota_exceeded".
Rate-Limit
100 Anfragen/Minute pro API-Key. Nur aktiv, wenn Upstash (Redis) konfiguriert ist. Verbrauchte Kontingent-Reservierungen werden bei 403/429 wieder freigegeben.
Antwortform
Alle v1-Endpunkte, die Daten liefern, verpacken die Nutzlast in { data: … }. Listen-Endpunkte liefern zusätzlich { data: [...], pagination: { total, limit, offset, hasMore } } (bzw. meta bei einigen Ressourcen). Erfolgreiche Aktionen ohne Rückgabeobjekt antworten { success: true }. Ausnahme sind die Blog-Routen unter /api/v1/blog/** (nur Plattform-Admins): Sie liefern Listen unter einem eigenen Schlüssel ({ posts }, { categories }, { tags }, { media }), Einzelobjekte ohne Hülle, KI-Jobs als { job } und Löschungen als { ok: true }.
Einzelobjekt: { data: { id, ... } }Liste: { data: [ { id, ... }, ... ], pagination: { total, limit, offset, hasMore } }Aktion ohne Rückgabeobjekt: { success: true }
Pagination
Alle Listen-Endpunkte unterstützen dieselbe Paginierung:
limit — Seitengröße (Standard: 50)offset — Versatz (Standard: 0)
Maximales limit: 100. { pagination: { total, limit, offset, hasMore } } (bei manchen älteren Ressourcen zusätzlich has_more bzw. unter dem Schlüssel meta statt pagination — siehe jeweiliger Endpunkt).
Fehlerformat
{ error: string, code?: string, allowedValues?: string[] }| Status | Bedeutung |
|---|
| 400 | Ungültige Eingabe (Pflichtfeld, Enum-Wert, Zahlen-/Datumsformat, Geschäftsregel). |
| 401 | Authorization-Header fehlt, ist kein Bearer-Header, oder der Schlüssel ist ungültig/deaktiviert. |
| 403 | Scope fehlt (requiredScopes in der Antwort), Plan ohne API-Zugang (code: "plan_no_access") oder ein Plan-Limit ist erschöpft. |
| 404 | Datensatz existiert nicht oder gehört zu einer anderen Firma — es werden nie Daten fremder Firmen ausgeliefert. |
| 409 | Zustandskonflikt: falscher Status für die Aktion, gleichzeitige Änderung, bereits vergebene Nummer/Referenz. |
| 429 | Monatskontingent erschöpft (code: "quota_exceeded") oder Rate-Limit erreicht. |
| 500 | Unerwarteter interner Fehler. |
| 502 | Ein abhängiger externer Dienst ist fehlgeschlagen (z. B. E-Mail-Versand, S3). |
Namenskonventionen
Request-Bodies akzeptieren praktisch überall sowohl camelCase als auch snake_case für dasselbe Feld (z. B. customerNumber = customer_number).
Antworten durchgehend camelCase: invoices (Kernrouten, Versionen, Berichtigung), quotes, order-confirmations, delivery-notes, orders, recurring-schedules, documents, products, company
Antworten aus Kompatibilitätsgründen (zusätzlich) snake_case: customers (camelCase mit einzelnen snake_case-Aliasen wie tax_id, created_at), credit-notes (durchgehend snake_case, neue Felder zusätzlich camelCase), invoice payments & dunning (snake_case, neue Felder zusätzlich camelCase), webhooks (snake_case)
Berechtigungen (Scopes)
Jeder API-Schlüssel erhält beim Anlegen einzelne Scopes:
| Scope | Bezeichnung | Beschreibung |
|---|
invoices:read | Rechnungen lesen | Rechnungen, Gutschriften, Zahlungen und Mahnstatus lesen, PDFs abrufen |
invoices:write | Rechnungen bearbeiten | Rechnungen und Gutschriften erstellen, ändern, versenden, Zahlungen und Mahnungen erfassen |
customers:read | Kunden lesen | Zugriff auf Kundenlisten und Details |
customers:write | Kunden bearbeiten | Kunden erstellen, ändern, archivieren und löschen |
products:read | Produkte lesen | Zugriff auf Produktlisten |
products:write | Produkte bearbeiten | Produkte erstellen und ändern |
quotes:read | Angebote lesen | Angebote und deren PDFs lesen |
quotes:write | Angebote bearbeiten | Angebote erstellen, ändern, versenden und umwandeln |
order-confirmations:read | Auftragsbestätigungen lesen | Auftragsbestätigungen und deren PDFs lesen |
order-confirmations:write | Auftragsbestätigungen bearbeiten | Auftragsbestätigungen erstellen, ändern, versenden und umwandeln |
delivery-notes:read | Lieferscheine lesen | Lieferscheine und deren PDFs lesen |
delivery-notes:write | Lieferscheine bearbeiten | Lieferscheine erstellen, ändern, versenden und in Rechnungen umwandeln |
orders:read | Aufträge lesen | Aufträge, Mengen und Statistiken lesen |
orders:write | Aufträge bearbeiten | Aufträge erstellen, ändern und Mengen pflegen |
recurring:read | Wiederkehrende Rechnungen lesen | Zeitpläne für wiederkehrende Rechnungen lesen |
recurring:write | Wiederkehrende Rechnungen bearbeiten | Zeitpläne anlegen, ändern, pausieren und Rechnungen daraus erzeugen |
documents:read | Belege lesen | Dokumentenablage lesen und Dateien herunterladen |
documents:write | Belege bearbeiten | Belege hochladen, ändern, archivieren und löschen |
exports:read | Exporte | Buchhaltungsexporte (CSV, DATEV, BMD, UStVA) und Kunden-CSV erzeugen |
direct-debits:write | SEPA-Lastschriften anlegen | SEPA-Sammelaufträge anlegen und ihre Lastschriftdatei (PAIN.008) erzeugen; die Rechnungen sind danach bis zum Verwerfen für weitere Exporte gesperrt |
company:read | Firmendaten lesen | Stammdaten, Nummernkreise und Plan-Funktionen der Firma lesen |
webhooks:read | Webhooks lesen | Webhook-Endpunkte und Zustellungen lesen |
webhooks:write | Webhooks verwalten | Webhook-Endpunkte erstellen, ändern und löschen |
Die zusätzlichen Scopes blog:read, blog:write, blog:publish, blog:moderate gehören zum internen Blog-CMS. Sie sind ausschließlich Plattform-Admins vorbehalten und können gewöhnlichen Firmen nicht zugewiesen werden.
Webhook-Ereignisse (Enterprise-Plan)
Webhook-Endpunkte können auf folgende Ereignisse abonniert werden; WEBHOOK_TEST entsteht nur beim Testversand und ist nicht abonnierbar. Details stehen bei der Ressource Webhooks in der API-Referenz.
| Ereignis | Auslöser |
|---|
| INVOICE_CREATED | Rechnung angelegt (Dashboard-Aktion, POST /api/v1/invoices). |
| INVOICE_UPDATED | Rechnung geändert, ohne Statuswechsel (PUT /api/v1/invoices/{id}). |
| INVOICE_SENT | Rechnung per E-Mail an den Kunden versendet. |
| INVOICE_PAID | Zahlung erfasst, die eine Rechnung vollständig ausgleicht. |
| INVOICE_OVERDUE | Rechnung überschreitet unbezahlt ihr Zahlungsziel. |
| INVOICE_CANCELLED | Rechnung oder Gutschrift storniert. |
| CREDIT_NOTE_CREATED | Gutschrift angelegt. |
| CREDIT_NOTE_PAID | Auszahlung einer Gutschrift ausgeführt. |
| PAYOUT_APPROVED | Auszahlung einer Gutschrift zur Ausführung freigegeben. |
| PAYOUT_EXECUTED | Auszahlung erfolgreich ausgeführt. |
| PAYOUT_FAILED | Ausführung der Auszahlung fehlgeschlagen. |
| PAYOUT_CANCELLED | Auszahlung vor der Ausführung storniert. |
| CUSTOMER_CREATED | Kunde angelegt. |
| CUSTOMER_UPDATED | Kunde geändert. |
| CUSTOMER_DELETED | Kunde gelöscht. |
| REMINDER_SENT | Zahlungserinnerung/Mahnung versendet. |
| REMINDER_ESCALATED | Mahnung auf die nächste Stufe eskaliert. |
| BLOG_POST_CREATEDPlattform | Blogpost angelegt (nur Plattform-Blog). |
| BLOG_POST_UPDATEDPlattform | Blogpost geändert (nur Plattform-Blog). |
| BLOG_POST_PUBLISHEDPlattform | Blogpost veröffentlicht bzw. geplante Veröffentlichung ausgelöst (nur Plattform-Blog). |
| BLOG_POST_UNPUBLISHEDPlattform | Blogpost zurückgezogen/archiviert (nur Plattform-Blog). |
| BLOG_COMMENT_CREATEDPlattform | Neuer Blog-Kommentar eingereicht (nur Plattform-Blog). |
| BLOG_COMMENT_APPROVEDPlattform | Blog-Kommentar freigegeben/moderiert (nur Plattform-Blog). |
| WEBHOOK_TEST | Testereignis über POST /api/v1/webhooks/{id}/test, ohne Geschäftsobjekt. Nicht abonnierbar; der Empfänger quittiert es ohne Verarbeitung. |
MCP / Codex-Plugin
Für KI-Assistenten wie Codex steht ein MCP-Plugin bereit, das Rechnungsentwürfe im Chat anlegt. Details unter Claribill in Codex.