Vollständige Dokumentation

Alle Hilfethemen und API-Details stehen auf dieser Seite ohne Themenauswahl bereit. Die Verfügbarkeit hängt von Rolle, Tarif und Firmenkonfiguration ab.

Aktualisiert:

Anmeldung

Claribill bietet zwei Anmeldemethoden: Magic Link (passwortlos per E-Mail) und Passkeys (Fingerabdruck, Gesichtserkennung oder Geräte-PIN).

So melden Sie sich per Magic Link an:

  1. Geben Sie Ihre E-Mail-Adresse auf der Login-Seite ein
  2. Klicken Sie auf "Magic Link senden"
  3. Öffnen Sie Ihre E-Mail und klicken Sie auf den Link
  4. Sie werden automatisch eingeloggt

Hinweise zum Magic Link:

  • Der Link ist 24 Stunden gültig und kann nur einmal verwendet werden
  • Falls Sie keine E-Mail erhalten, prüfen Sie Ihren Spam-Ordner
  • Bei erstmaliger Anmeldung wird automatisch ein Konto erstellt

Anmeldung mit Passkey:

Passkeys ermöglichen eine schnelle Anmeldung ganz ohne E-Mail. Ein Passkey ist an Ihr Gerät bzw. Ihren Passwort-Manager gebunden.

  • Einrichten und verwalten unter Einstellungen → Sicherheit
  • Mehrere Passkeys pro Konto möglich (z. B. für Laptop und Smartphone)
  • Der Magic Link bleibt als Rückfalloption immer verfügbar

Thema in der Hilfe öffnen

Firma einrichten

Nach der ersten Anmeldung führt Sie ein 3-stufiges Onboarding durch die Ersteinrichtung Ihrer Firma.

Schritt 1 - Firma:

  • Wählen Sie Rechtsform. Bei Einzelunternehmen geben Sie unter Inhaber Vorname und Nachname an; Geschäftsbezeichnung (optional) kann leer bleiben. Bei Eingetragenes Einzelunternehmen (e.U.) geben Sie zusätzlich den Firmenwortlaut ein. Bei anderen Rechtsformen ist der Firmenname erforderlich. Falls eine Absendervorschau angezeigt wird, prüfen Sie dort den Namen.
  • Straße, PLZ, Ort und Land (optional, kann später ergänzt werden)

Schritt 2 - Steuer & Währung:

  • UID-Nummer / USt-IdNr. (optional, für Reverse-Charge und die VIES-Prüfung)
  • Steuernummer (optional)
  • Währung: EUR, CHF, USD oder GBP

Schritt 3 - Bank:

  • IBAN und BIC (optional, erscheinen später auf Ihren Rechnungen)

Tipp:

Logo, Bankname sowie Kontaktdaten wie Telefon oder Website werden nicht im Onboarding abgefragt. Alle Angaben können Sie jederzeit unter Einstellungen → Firmendaten ergänzen oder ändern.

Thema in der Hilfe öffnen

Dashboard und Navigation

Das Dashboard zeigt Kennzahlen der aktiven Firma und Ihrer sichtbaren Belege: Umsatz, offene Forderungen, Stammdaten, wiederkehrende Umsätze, Monatsverlauf und Top-Kunden. Offene Forderungen berücksichtigen erfasste Teilzahlungen. Proformas zählen nicht als Rechnungsumsatz; eine umgewandelte Proforma fordert nicht ein zweites Mal Zahlung an.

Orientierung

Die Seitenleiste gruppiert Rechnungswesen, Finanzen, Stammdaten, Auswertung, Kommunikation und Verwaltung. Auf kleinen Bildschirmen öffnen Sie sie mit dem Navigationsschalter. Einstellungen besitzt einen eigenen Untermenü-Schalter. Postausgang steht direkt in der Seitenleiste. Öffnen Sie für Exporte Berichte → Exportieren, Dokumentenvorlagen über Einstellungen → Firmendaten. Die Entwurfsübersicht erreichen Sie unter /dashboard/drafts.

Im Kopfbereich wechseln Sie Sprache und gegebenenfalls Firma, öffnen Benachrichtigungen über die Glocke oder das Kontomenü. Abmelden beendet die Sitzung. Ein Sprachwechsel ändert keine Kunden- oder Belegtexte.

Fehlender Menüpunkt

Prüfen Sie aktive Firma, Mitgliedsrolle und Tarif. Sichtbarkeit und Aktionsrechte sind getrennt: Eine freigegebene Rechnung erlaubt einem Mitarbeiter nicht automatisch, eine Zahlung zu erfassen. Was Ihre Rolle umfasst, legt Ihre Firma unter Einstellungen → Rollen & Rechte fest; die Kategorien bei den einzelnen Rechten und die Grenze der Rolle („Diese Rolle arbeitet ausschließlich in bestimmten Kategorien“) können den Zugriff zusätzlich einschränken.

Helles und dunkles Design

Über das Design-Symbol im Kopfbereich wechseln Sie zwischen hellem und dunklem Design. Die Beschriftung lautet je nach aktuellem Zustand Zu hellem Design wechseln oder Zu dunklem Design wechseln. Diese Anzeigeeinstellung ändert keine Beleginhalte.

Support-Chat öffnen

Wählen Sie rechts unten Support-Chat öffnen (Sprechblase). Geben Sie Ihre Frage im Chat ein. Über Support-Chat schließen oder die Escape-Taste kehren Sie zur Seite zurück. Öffnen Sie den Chat im selben Bereich erneut, um das Gespräch fortzusetzen. Nach dem Neuladen der Seite beginnen Sie ein neues Gespräch.

Thema in der Hilfe öffnen

Rechnung erstellen

  1. Öffnen Sie Rechnungen und Neue Rechnung.
  2. Wählen Sie Dokumenttyp (Rechnung oder Proforma-Rechnung), Kunde, Rechnungsdatum und Fällig am. Über die Kundenauswahl ist auch die Schnellanlage möglich.
  3. Prüfen Sie Belegsprache, Kategorie, Steuerland und Umsatzsteuerbehandlung. Die Sprache des Belegs ist unabhängig von der Oberfläche.
  4. Erfassen Sie Positionen mit Beschreibung, Menge, Einheit, Einzelpreis und Steuersatz. Produkte übernehmen ihre Stammdaten; eigene Texte bleiben möglich.
  5. Ergänzen Sie bei Bedarf Einleitungstext (optional), Abschlusstext (optional) und Interne Anmerkungen (optional). Interne Anmerkungen erscheinen nicht auf dem PDF.
  6. Unter Erweiterte Optionen stehen ein individueller Dokumenttitel, PDF ohne Briefkopf, Rechnungsdatum = Leistungsdatum und Abweichende Lieferadresse zur Verfügung. Bei öffentlichen Auftraggebern können Sie Bestellnummer, Käuferreferenz/Leitweg-ID, Dienststelle, Format, Einreichkanal und Einreichstatus dokumentieren.
  7. Rechnung erstellen speichert einen Rechnungsentwurf; bei Proforma heißt die Schaltfläche Proforma erstellen. Erst auf der Belegseite folgen Fertigstellen oder der E-Mail-Versand. Das Anlageformular versendet nicht unmittelbar.

Zehn Positionstypen

Produkt, Dienstleistung, Rabatt (%), absoluter Rabatt, Versand, Anzahlung, Gutschrift, Text, Zwischensumme und Seitenumbruch. Text, Zwischensumme und Seitenumbruch strukturieren das PDF. Rabatte reduzieren die Steuerbasis anteilig nach Steuersatz. Anzahlungen sind Abzüge und ersetzen keine im Bereich Zahlungen erfasste Zahlung.

Fälligkeit

Das Zahlungsziel wird aus dem Kunden, sonst der Firma, sonst mit 14 Tagen ab Rechnungsdatum vorgeschlagen. Eine ausdrücklich geänderte Fälligkeit wird beibehalten.

Artikelnummer

Unter Einstellungen → Firmendaten → Dokumentenvorlagen lässt sich Artikelnummer anzeigen aktivieren. Produkt-SKUs werden übernommen und können im Beleg geändert werden. Ausblenden löscht gespeicherte Artikelnummern nicht.

Texte formatieren

In Textfeldern mit Formatierungsleiste markieren Sie den gewünschten Text und wählen Fett, Kursiv oder Unterstrichen. Aufzählung und Nummerierte Liste strukturieren längere Hinweise. Rückgängig und Wiederholen betreffen die Textbearbeitung. Prüfen Sie anschließend die Belegvorschau.

Thema in der Hilfe öffnen

Brutto- oder Nettopreise

Claribill rechnet Belege wahlweise mit Nettopreisen (zzgl. USt, üblich im Geschäft mit Unternehmen) oder mit Bruttopreisen (inkl. USt, üblich bei Privatkunden, B2C). Jeder Beleg und jeder Artikel speichert seine eigene Preisart.

Vorgabe der Firma

Unter Einstellungen → Firmendaten legen Sie im Abschnitt Steuerliche Einstellungen bei Preise eingeben als fest, mit welcher Preisart neue Belege, Wiederholungsrechnungen und Artikel beginnen. Eine spätere Änderung gilt nur für neue Belege; bestehende Belege behalten ihre Preisart.

Umschalter im Beleg

Unter Erweiterte Optionen am Ende des Belegs (bei Wiederholungsrechnungen unter Optionale Angaben) wählen Sie bei Preise zwischen Netto und Brutto; vorgewählt ist die Vorgabe der Firma. Beim Umschalten bleiben die eingegebenen Einzelpreise unverändert und gelten danach als Brutto- bzw. Nettopreise; USt und Summen werden neu berechnet. Bei Bruttopreisen sind auch Positionsrabatte und der Rabatt (€) Beträge inkl. USt, ein Rabatt (%) bezieht sich auf die Bruttosumme davor.

Artikel

Der Preis eines Artikels gilt in dessen Preisart. Übernehmen Sie einen Artikel in einen Beleg mit anderer Preisart, rechnet Claribill den Preis mit dem Steuersatz des Artikels auf den Cent genau um, etwa 100,00 € netto bei 20 % in 120,00 € brutto. Die Liste Artikel & Leistungen zeigt die Preise in der Preisart der Firma, darunter klein in der anderen Preisart.

Rundung

Bei Bruttopreisen zahlt der Kunde genau die Summe der Bruttopositionen. Die USt wird je Steuersatz aus dem Bruttobetrag herausgerechnet. Beispiel: 3 × 19,99 € brutto ergeben 59,97 €, darin 10,00 € USt (20 %) und 49,97 € netto. Eine Rechnung mit dem umgerechneten Nettopreis 16,66 € käme dagegen auf 59,98 €.

Ausweis auf dem PDF

Einzelpreise und Positionsbeträge stehen brutto auf dem Beleg. Der Summenblock nennt die enthaltene USt je Steuersatz (z. B. „enthaltene USt 20 %“), dazu steht der Hinweis „Alle Preise inkl. USt.“.

Steuerfreie Belege

Reverse Charge, Kleinunternehmerregelung und andere Befreiungen haben keine USt. Brutto und Netto sind dort gleich, beide Preisarten rechnen identisch.

Umwandeln und Folgebelege

Umwandlungen übernehmen die Preisart mitsamt den Preisen: Angebot → Auftragsbestätigung → Rechnung, Auftrag → Rechnung, Proforma → Rechnung, Duplikat, Storno und Gutschrift zur Rechnung. Rechnungen aus einer Wiederholungsrechnung übernehmen deren Preisart.

E-Rechnung, Exporte und Berichte

Die E-Rechnung (Factur-X/ZUGFeRD) bleibt nettobasiert: Sie enthält die Nettobeträge der Positionen und die USt je Steuersatz genau wie das PDF. Buchhaltungsexport, DATEV, BMD, USt-Report und die USt-Aufschlüsselung im Umsatzbericht arbeiten ebenfalls mit Nettobeträgen und übernehmen die USt je Steuersatz aus dem Beleg.

REST-API, MCP und KI-Assistent

Die REST-API kennt beim Anlegen und Ändern von Rechnungen, Gutschriften mit eigenen Positionen, Angeboten, Auftragsbestätigungen, Aufträgen, Wiederholungsrechnungen und Artikeln das Feld pricesIncludeTax (auch prices_include_tax, nur true oder false). Ohne Angabe legt die REST-API immer mit Nettopreisen an, auch wenn die Firma Bruttopreise vorgibt, denn bestehende Integrationen senden Nettopreise. Beim Ändern ohne Angabe bleibt die gespeicherte Preisart. Antworten und Webhooks enthalten pricesIncludeTax; der Positionsbetrag lineTotal ist immer netto. Die MCP-Verbindung und der KI-Assistent verwenden ohne Angabe die Vorgabe der Firma und zeigen die Preisart in Vorschau und Bestätigung.

Thema in der Hilfe öffnen

Rechnungsstatus

Jede Rechnung durchläuft verschiedene Status:

StatusBedeutung
EntwurfNoch nicht fertiggestellt, kann frei bearbeitet werden
FertiggestelltRechnungsnummer wurde vergeben, aber noch nicht versendet
VersendetAn den Kunden gesendet, wartet auf Zahlung
BezahltVollständig bezahlt
ÜberfälligZahlungsziel überschritten
StorniertRechnung wurde storniert

Statusübergänge:

  • Entwurf → Fertiggestellt, Versendet oder Storniert
  • Fertiggestellt → Versendet, zurück zu Entwurf oder Storniert
  • Versendet → Bezahlt, Überfällig oder Storniert
  • Überfällig → Bezahlt oder Storniert
  • Bezahlt und Storniert sind Endzustände - aus ihnen ist über einen Statuswechsel kein weiterer Übergang möglich

Bezahlte Rechnung korrigieren:

Eine bereits bezahlte Rechnung lässt sich nicht mehr direkt stornieren. Erstellen Sie stattdessen über "Gutschrift erstellen" eine Gutschrift, die den Betrag ausgleicht.

Versand fehlgeschlagen:

Beim Versenden eines Entwurfs vergibt Claribill die Rechnungsnummer, bevor die E-Mail rausgeht – PDF und E-Mail tragen sie. Scheitert der Versand (zum Beispiel beim Mailserver), bleibt die Nummer diesem Entwurf zugeordnet und wird beim nächsten Versuch wiederverwendet; sie wird nie ein zweites Mal vergeben. Ein solcher Entwurf lässt sich nicht mehr löschen, damit der Nummernkreis lückenlos bleibt: Versenden Sie ihn erneut oder stornieren Sie ihn. Beim Stornieren entsteht keine Storno-Rechnung, weil die Rechnung nie ausgestellt war; die Nummer bleibt als stornierte Rechnung dokumentiert.

Stornierte Rechnung versenden:

Eine stornierte Rechnung lässt sich weiterhin per E-Mail versenden, sofern sie zuvor tatsächlich ausgestellt wurde (kein direkt stornierter Entwurf). Sie bleibt dabei storniert, erhält aber - falls noch keines gesetzt war - ihr Versanddatum und erscheint im Audit-Log sowie im E-Mail-Postausgang.

Thema in der Hilfe öffnen

PDF herunterladen

Jede Rechnung kann als PDF heruntergeladen werden.

Enthaltene Informationen:

  • Ihre Firmendaten mit Logo
  • Kundenadresse
  • Rechnungsnummer und Datum
  • Bestellnummer und Käuferreferenz/Leitweg-ID, sofern gepflegt
  • Alle Positionen mit Steuersätzen
  • Summenblock (Netto, USt, Brutto)
  • EPC QR-Code für schnelle Banküberweisung
  • Bankverbindung
  • Zahlungsziel
  • Individuelle Fußzeile

Sonderfälle:

  • Kleinunternehmer: Hinweis auf §6 Abs 1 Z 27 UStG
  • Reverse-Charge: Hinweis auf Steuerschuldnerschaft
  • Steuerland EU-weit: Steuersätze aller EU-Mitgliedstaaten – bei steuerpflichtigen Umsätzen wird das Steuerland aus Liefer- bzw. Kundenland vorgeschlagen (z. B. DE 19% / 7%, FR 20% / 10% / 5,5%)
  • OSS (One-Stop-Shop): Weicht das EU-Steuerland vom Firmensitz ab, wird die Rechnung automatisch als OSS-relevant gekennzeichnet und im USt-Report getrennt ausgewiesen

Thema in der Hilfe öffnen

Wiederholungsrechnungen

Automatisieren Sie regelmäßige Rechnungen für Abos, Wartungsverträge oder Mieten.

Einrichtung:

  1. Gehen Sie zu Wiederkehrend → Neue Wiederholungsrechnung
  2. Wählen Sie den Kunden
  3. Definieren Sie die Positionen
  4. Wählen Sie das Intervall:
  • Wöchentlich
  • Alle 2 Wochen
  • Monatlich
  • Vierteljährlich
  • Halbjährlich
  • Jährlich
  1. Legen Sie Start- und optional Enddatum fest
  2. Wählen Sie, ob Rechnungen automatisch versendet werden sollen

Automatische Generierung:

Rechnungen werden automatisch zum festgelegten Zeitpunkt erstellt und optional per E-Mail versendet.

Verfügbarkeit:

Wiederkehrende Rechnungen sind ab dem Starter-Plan verfügbar und im Free-Plan nicht enthalten.

Thema in der Hilfe öffnen

E-Rechnung (Factur-X/ZUGFeRD)

Claribill erzeugt einen separaten XML-Export im Factur-X/ZUGFeRD-2.3-BASIC-Profil (CII). In der Rechnung öffnen Sie Aktionen → E-Rechnung (XML). Das normale PDF und die XML-Datei sind getrennte Downloads; eine PDF/A-3-Einbettung gehört derzeit nicht zum erzeugten Rechnungs-PDF.

Öffentliche Auftraggeber

Bestellnummer, Käuferreferenz/Leitweg-ID und weitere Angaben werden am Beleg gepflegt. Die Auswahl von XRechnung, PEPPOL oder einem Portal im Formular dokumentiert Format bzw. Einreichweg. Sie startet keinen XRechnungs-Export und keine automatische Portal- oder PEPPOL-Übermittlung. Prüfen Sie das vom Empfänger verlangte Format und reichen Sie die passende Datei selbst ein.

Eine bereits in eine Rechnung umgewandelte Proforma erzeugt keine erneute Zahlungsaufforderung und keinen E-Rechnungs-XML-Export.

Thema in der Hilfe öffnen

Versionierung & Berichtigung

Versendete bzw. fertiggestellte Rechnungen sind aus GoBD-Gründen unveränderlich (Festschreibung).

Festschreibung:

Versand und Fertigstellen sowie das erstmalige Öffnen eines verteilbaren PDFs können die Rechnung festschreiben. Eine reine Vorschau ist davon zu unterscheiden. Ab diesem Zeitpunkt ist "Bearbeiten" nicht mehr direkt möglich.

Berichtigung (§ 31 Abs. 5 UStDV / § 11 Abs. 12 UStG):

  • Über den Bearbeiten-Dialog einer festgeschriebenen Rechnung starten Sie eine Berichtigung
  • Sie müssen einen Grund mit mindestens 10 Zeichen angeben
  • Die Berichtigung legt eine neue, höhere Version an (v2, v3, ...) - die vorherige Version bleibt unverändert erhalten

Versionshistorie:

Auf der Rechnungsdetailseite können Sie alle bisherigen Versionen inklusive der jeweiligen Begründung einsehen.

Alternative:

Für eine reine Stornierung oder Preiskorrektur ist häufig eine Gutschrift der einfachere Weg.

Thema in der Hilfe öffnen

Proforma-Rechnungen

  1. Öffnen Sie Rechnungen → Neue Rechnung.
  2. Wählen Sie unter Dokumenttyp die Proforma-Rechnung.
  3. Erfassen Sie Kunde, Datum, Gültigkeit, Positionen und Sprache, dann Proforma erstellen.
  4. Prüfen Sie den Entwurf und stellen Sie ihn fertig oder versenden Sie ihn über die Belegaktionen.

Proformas besitzen einen PF-Nummernkreis. Sie sind vorläufige Belege und fließen nicht als Rechnungsumsatz in die Auswertungen ein. Zahlungen lassen sich nach den üblichen Zahlungsrechten erfassen.

Umwandlung

In Rechnung umwandeln erstellt einen verknüpften Rechnungsentwurf; die Proforma behält ihre PF-Nummer. Bereits erfasste Zahlungen und akzeptierte Bankzuordnungen werden übernommen. Der neue Entwurf erhält seine RE-Nummer erst beim Ausstellen. Eine vollständig bezahlte Rechnung wird beim Fertigstellen als bezahlt geführt.

Wurde die Proforma nur manuell als bezahlt markiert, ohne Zahlung, müssen Sie diese zuerst erfassen. Nach der Umwandlung arbeiten Sie mit der verknüpften Rechnung weiter. Die Proforma wird nicht erneut versendet, gemahnt, in einen anderen Status versetzt oder als offene Forderung behandelt.

Thema in der Hilfe öffnen

Suche, Sammelaktionen und Versand

In Rechnungen kombinieren Sie Suchtext, Zeitraum, Status, Dokumenttyp und Kategorie. Wählen Sie Zeilen über die Auswahlkästchen; die Sammelaktionen erscheinen für die Auswahl. Nicht gefundene Belege können durch aktive Filter oder Berechtigungen verborgen sein.

Downloads und Druck

Herunterladen erzeugt für mehrere ausgewählte Rechnungen eine ZIP-Datei. Drucken verwendet ein zusammengeführtes PDF. Ein einzelnes PDF öffnen Sie über PDF öffnen bzw. PDF herunterladen. Eine PDF-Vorschau im Detailbereich ist von der Ausgabe eines verteilbaren Dokuments zu unterscheiden.

Versand

Die Sammelversand-Vorschau nennt geeignete und übersprungene Belege samt Gründen und verfügbare Versandkapazität. Nach Bestätigung wird jede geeignete Rechnung einzeln über den regulären Versand verarbeitet. Bei Grenzen stoppt der Lauf; kontrollieren Sie das Ergebnis und den Postausgang, bevor Sie erneut senden. Fertigstellen oder Als versendet markieren ist nicht gleichbedeutend mit dem tatsächlichen E-Mail-Versand.

Weitere Sammelaktionen

Status ändern, Kategorie ändern, Löschen und SEPA-Lastschrift sind abhängig von Rolle, Auswahl und Belegzustand. Eine vergebene Rechnungsnummer verhindert das Löschen eines Entwurfs. Eine Aktion gewährt keinen Zugriff auf zuvor unsichtbare Belege.

Thema in der Hilfe öffnen

Angebote

Erstellen Sie unverbindliche Angebote für Ihre Kunden - mit Produkt-, Dienstleistungs-, Rabatt-, Versand- und Layoutpositionen (ohne Anzahlungs- und Gutschriftpositionen).

Status:

  • Entwurf → Versendet → manuell auf Angenommen oder Abgelehnt setzen
  • Abgelaufen wird nur angezeigt, sobald das Gültigkeitsdatum überschritten ist - der gespeicherte Status ändert sich dabei nicht

Gültigkeit:

Ein neues Angebot schlägt "Gültig bis" mit 30 Tagen ab dem Angebotsdatum vor - unabhängig vom Zahlungsziel der Firma.

Umwandeln:

Ein Angebot lässt sich in eine Rechnung oder eine Auftragsbestätigung umwandeln, solange es nicht abgelehnt oder bereits umgewandelt wurde. Besteht zu einem Angebot bereits eine Auftragsbestätigung, bleibt die Umwandlung in eine Rechnung möglich - Claribill nennt die bestehende Auftragsbestätigung aber vorher, damit dieselbe Leistung nicht doppelt abgerechnet wird.

Versand:

Angebote werden wie Rechnungen per E-Mail an den Kunden versendet.

Bei der Umwandlung in eine Rechnung wird die am Kunden hinterlegte Steuervorgabe einschließlich eines eigenen Befreiungshinweises übernommen. Prüfen Sie die Angaben im Rechnungsentwurf; ohne Kundenvorgabe gilt der vorgeschlagene Steuerkontext.

Thema in der Hilfe öffnen

Auftragsbestätigungen

Bestätigen Sie einem Kunden schriftlich die Annahme eines Auftrags - direkt oder aus einem Angebot heraus.

Erstellung:

  • Direkt neu anlegen, oder
  • Aus einem bestehenden Angebot übernehmen (Positionen und Kundendaten werden kopiert)

Umwandeln:

  • In eine Rechnung umwandeln, sobald die Leistung abgerechnet werden kann
  • Die aktuelle Detailansicht bietet In Rechnung umwandeln. Ein Auftrag ist ein eigener Beleg; eine Schaltfläche zum Umwandeln der Auftragsbestätigung in einen Auftrag wird dort nicht angeboten.

Bei der Umwandlung in eine Rechnung wird die am Kunden hinterlegte Steuervorgabe einschließlich eines eigenen Befreiungshinweises übernommen. Prüfen Sie die Angaben im Rechnungsentwurf; ohne Kundenvorgabe gilt der vorgeschlagene Steuerkontext.

Thema in der Hilfe öffnen

Aufträge

Für langfristige Projekte mit mehreren Teillieferungen und Teilrechnungen bietet Claribill einen eigenen Auftragstyp.

Anlage:

  • Über Aufträge → Neuer Auftrag anlegen
  • Gesamtbudget, Projektstart und geplantes Ende festlegen

Auftragsfortschritt:

Die Detailseite zeigt drei Fortschrittsbalken:

  • Budget: bereits abgerechneter Betrag im Verhältnis zum Gesamtbudget
  • Geliefert: Anzahl gelieferter Einheiten (aus verknüpften Lieferscheinen) im Verhältnis zur bestellten Menge
  • Abgerechnet: Anteil des Auftrags, der bereits in Rechnung gestellt wurde

Verknüpfung:

Lieferscheine und Rechnungen lassen sich einem Auftrag zuordnen, damit der Fortschritt automatisch aktuell bleibt.

Thema in der Hilfe öffnen

Lieferscheine

Dokumentieren Sie Warenlieferungen ohne Preisangaben.

Positionen:

Lieferscheine enthalten nur Beschreibung, Menge und Einheit - keine Preise.

Erstellung:

  1. Navigieren Sie zu Lieferscheine → Neuer Lieferschein
  2. Wählen Sie den Kunden und optional den zugehörigen Auftrag
  3. Erfassen Sie die gelieferten Positionen
  4. Speichern Sie als Entwurf oder versenden Sie den Lieferschein

In Rechnung umwandeln:

Aus einem Lieferschein lässt sich eine Rechnung erstellen - dabei ergänzen Sie die noch fehlenden Preise und Steuersätze.

Bei der Umwandlung in eine Rechnung wird die am Kunden hinterlegte Steuervorgabe einschließlich eines eigenen Befreiungshinweises übernommen. Prüfen Sie die Angaben im Rechnungsentwurf; ohne Kundenvorgabe gilt der vorgeschlagene Steuerkontext.

Thema in der Hilfe öffnen

Gutschriften & Storno

Gutschriften gleichen Rechnungsbeträge aus - als Korrektur, Storno oder freie Auszahlung.

Storno-Gutschrift:

Beim Stornieren einer bereits ausgestellten Rechnung können Sie im Dialog eine passende Storno-Gutschrift erstellen und ihren Versand auswählen. Prüfen Sie beide Optionen vor der Bestätigung. Ein direkt stornierter, nie ausgestellter Entwurf erzeugt keine Storno-Gutschrift.

Teilgutschrift aus einer Rechnung:

Öffnen Sie eine versendete, bezahlte oder überfällige Rechnung und klicken Sie auf "Gutschrift erstellen". Wählen Sie dabei einzelne Positionen und Mengen aus (Teilgutschrift) oder gutschreiben Sie die gesamte Rechnung.

Freie Gutschrift:

Für Fälle ohne zugehörige Rechnung - z. B. Provisionen oder Auszahlungen - legen Sie über "Neue Gutschrift" eine eigenständige Gutschrift an.

Begründung:

Jede Gutschrift verlangt einen Grund: Storno, Retoure, Preiskorrektur, Auszahlung, Provision, Kulanz oder Sonstiges.

Berechtigung:

Standardmäßig erstellen Inhaber, Admin und Buchhaltung Gutschriften. Unter Einstellungen → Rollen & Rechte lässt sich das je Rolle ändern.

Gutschriften zählen zu den Rechnungen: Welche Gutschriften ein Mitglied sieht, bestimmt das Recht Rechnungen: Ansehen seiner Rolle, samt den dort gewählten Kategorien.

Gutschrift bearbeiten

Eine freie Gutschrift übernimmt bei der Kundenauswahl die Steuervorgabe und gegebenenfalls den Befreiungshinweis des Kunden. Öffnen Sie eine bearbeitbare Gutschrift und wählen Sie Bearbeiten. Mengen und Preise geben Sie positiv ein; die Gutschrift wird mit negativem Vorzeichen ausgewiesen. Speichern Sie mit Änderungen speichern. Bei einer festgeschriebenen Gutschrift verwenden Sie den angebotenen Berichtigungsablauf und Berichtigung speichern.

Thema in der Hilfe öffnen

Kundenverwaltung

Verwalten Sie alle Ihre Geschäftskunden zentral.

Kundenanlage:

  1. Navigieren Sie zu Kunden → Neuer Kunde
  2. Geben Sie die Stammdaten ein:
  • Name / Firmenname
  • E-Mail-Adresse
  • Rechnungsadresse
  • Optional: Lieferadresse
  1. Für B2B-Kunden: UID-Nummer eingeben

UID-Validierung:

  • Klicken Sie auf "UID prüfen" um die Nummer zu validieren
  • Die Prüfung erfolgt über die EU VIES-Datenbank
  • Bei gültiger UID wird der passende Steuerkontext automatisch vorgeschlagen, z. B. Reverse Charge im EU-B2B-Fall
  • Ist VIES vorübergehend nicht erreichbar, zeigt Claribill "Prüfung derzeit nicht möglich" und behält den zuletzt bestätigten Status unverändert bei

DATEV-Integration:

Für den DATEV-Export können Sie jedem Kunden eine Debitorennummer zuweisen.

Standard-Dokumentkategorie:

Legen Sie am Kunden eine Standard-Dokumentkategorie fest, die neue Belege dieses Kunden automatisch vorbelegt (siehe Dokumentkategorien & Zugriff).

Thema in der Hilfe öffnen

Ansprechpartner

Hinterlegen Sie mehrere Kontaktpersonen pro Kunde.

Kontaktdaten:

  • Name
  • Funktion / Position
  • E-Mail
  • Telefon

Verwendung:

  • Auswahl beim Rechnungsversand
  • CC/BCC für Steuerberater oder Buchhaltung

Thema in der Hilfe öffnen

Artikel anlegen und verwenden

  1. Öffnen Sie Artikel & Leistungen → Neuer Artikel. Ist die Liste leer, führt auch Ersten Artikel anlegen zum Formular.
  2. Geben Sie Bezeichnung, bei Bedarf eine Beschreibung, den Preis, Steuersatz, Einheit und optional Artikelnummer (SKU) ein. Unter Art wählen Sie Produkt oder Dienstleistung. Für eine Pauschale können Sie die Einheit „pauschal“ verwenden.
  3. Wählen Sie Artikel anlegen. Klicken Sie in der Zeile des Artikels auf Bearbeiten, um die Vorlage zu ändern; Änderungen speichern übernimmt die Änderungen. Deaktivieren und anschließend Artikel deaktivieren entfernen sie aus der Auswahl für neue Positionen. Bereits gespeicherte Belege behalten ihre Werte.

Der Preis gilt netto oder brutto, je nach Preisart des Artikels; neue Artikel beginnen mit der Vorgabe der Firma (siehe Brutto- oder Nettopreise).

Artikel im Beleg verwenden

Wählen Sie über oder unter den Positionen Artikel und suchen Sie über Artikel oder Leistung suchen …. Der Artikel füllt eine noch leere letzte Position, sonst kommt er als neue Position dazu. Die Auswahl übernimmt Bezeichnung und hinterlegte Beschreibung sowie die für den Beleg passenden Werte, etwa Einheit, Artikelnummer und Preis. Prüfen Sie den Steuersatz am Beleg. Die Menge können Sie separat festlegen.

Freie Position wiederverwenden

Inhaber, Admin und Buchhaltung können an einer freien Produkt- oder Dienstleistungsposition Als Artikel speichern wählen. Geben Sie zuerst eine Beschreibung ein: Die erste Textzeile wird zur Bezeichnung, weitere Zeilen zur Beschreibung. Anschließend finden Sie den Artikel in der Auswahl. Eine Rabatt- oder Textzeile ist keine Artikelvorlage.

Thema in der Hilfe öffnen

Zahlung erfassen

Dokumentieren Sie eingehende Zahlungen zu Ihren Rechnungen.

So erfassen Sie eine Zahlung:

  1. Öffnen Sie die Rechnungsdetails
  2. Klicken Sie auf "Zahlung erfassen"
  3. Geben Sie ein:
  • Betrag
  • Datum
  • Zahlungsart: Überweisung, Bar, Kreditkarte, PayPal oder Sonstige
  • Referenz (optional, z.B. Transaktions-ID)

Teilzahlungen:

  • Mehrere Zahlungen pro Rechnung möglich
  • Status wechselt erst bei vollständiger Bezahlung auf "Bezahlt"

Überzahlungen:

Ein Betrag über dem noch offenen Rechnungsbetrag wird abgelehnt. Es gibt kein Guthaben-Konto - korrigieren Sie in diesem Fall die Zahlung oder erstellen Sie bei Bedarf eine Gutschrift.

Zahlung auf eine stornierte Rechnung:

Geht nach dem Storno noch Geld ein, lässt sich die Zahlung nachträglich erfassen - von Hand wie über den Bankabgleich. Die Rechnung bleibt storniert und wechselt dabei nicht auf "Bezahlt". Eine bereits erfasste Zahlung einer stornierten Rechnung lässt sich weiterhin nur löschen, nicht ändern.

Berechtigung:

Zahlungen erfassen, ändern und löschen dürfen standardmäßig Inhaber, Admin und Buchhaltung - unabhängig davon, wer die Rechnung erstellt hat. Unter Einstellungen → Rollen & Rechte lassen sich diese Rechte je Rolle ändern.

Thema in der Hilfe öffnen

Bankabgleich (finAPI)

Verbinden Sie Ihr Geschäftskonto und lassen Sie eingehende Zahlungen automatisch mit offenen Rechnungen abgleichen.

Einrichtung:

  1. Gehen Sie zu Einstellungen → Bankverbindung
  2. Verbinden Sie Ihr Konto über finAPI
  3. Claribill synchronisiert die Umsätze regelmäßig

Zahlungsabgleich:

Unter Zahlungsabgleich sehen Sie neue Kontobewegungen mit automatischen Vorschlägen:

  • Übernehmen - Vorschlag bestätigen, Zahlung wird automatisch erfasst
  • Ablehnen - Vorschlag verwerfen
  • Manuell zuordnen - Transaktion einer anderen offenen Rechnung zuweisen, auch einer bereits stornierten (dort entsprechend gekennzeichnet); die Rechnung bleibt storniert und wird dadurch nicht bezahlt

Zustimmung erneuern:

Die Bankzustimmung (Consent) läuft nach einer gewissen Zeit ab und muss unter Einstellungen → Bankverbindung erneuert werden.

Verfügbarkeit:

Die Bank-Integration ist ab dem Professional-Plan verfügbar.

Thema in der Hilfe öffnen

SEPA-Lastschrift

Claribill kann SEPA-Lastschriftaufträge im PAIN.008-XML-Format für den Import bei Ihrer Bank erzeugen.

Voraussetzungen:

  • Ihre Gläubiger-Identifikationsnummer (Creditor ID) steht unter Einstellungen bei den Bankdaten; Claribill prüft die Prüfziffer
  • Die IBAN Ihrer Firma ist hinterlegt
  • Der Kunde hat eine gültige IBAN (Claribill prüft auch die Prüfziffer) und ein aktives SEPA-Mandat (Kunde bearbeiten → Bankdaten: Mandatsreferenz, Datum der Unterschrift, Art CORE oder B2B). Standard ist die wiederkehrende Lastschrift; ein „Einmalmandat“ trägt genau eine Lastschrift

Sammelauftrag anlegen:

Wählen Sie in der Rechnungsliste die Rechnungen aus und klicken Sie auf „SEPA-Lastschrift“. Die Vorschau zeigt, was eingezogen wird und welche Rechnungen nicht enthalten sind, jeweils mit Grund. Nach Wahl des Einzugsdatums (frühestens morgen) legt Claribill einen Sammelauftrag an und lädt die PAIN.008-Datei herunter. Basislastschrift (CORE) und Firmenlastschrift (B2B) erhalten getrennte Sammelaufträge mit eigener Datei.

  • Eingezogen werden versendete und überfällige Rechnungen in Euro, jeweils mit dem noch offenen Betrag
  • Eine Rechnung in einem Sammelauftrag wird beim nächsten Export übersprungen („Bereits im Sammelauftrag …“)
  • Unter „Hinweise“ nennt die Vorschau Rechnungen, die zum Einzugsdatum noch nicht fällig sind, und archivierte Kunden; diese Rechnungen werden trotzdem eingezogen
  • Der Status der Rechnung bleibt unverändert; den Zahlungseingang erfassen Sie wie gewohnt oder über den Zahlungsabgleich
  • Die Rechnung zeigt unter „Zahlungen“, in welchem Sammelauftrag sie eingezogen wurde

Sammelaufträge verwalten:

Unter SEPA-Lastschriften (Seitenleiste oder Berichte) laden Sie eine Datei erneut herunter. Wurde eine Datei nie bei der Bank eingereicht, verwerfen Sie den Sammelauftrag; seine Rechnungen lassen sich dann erneut einziehen.

Berechtigungen:

Mandate pflegen und Lastschriften einziehen dürfen Inhaber, Admins und die Buchhaltung. Mitarbeiter sehen das Mandat nur.

Thema in der Hilfe öffnen

Mahnsystem

Claribill unterstützt ein 3-stufiges Mahnsystem.

Mahnstufen:

  1. Zahlungserinnerung - Freundliche Erinnerung nach Fälligkeit
  2. 1. Mahnung - Formelle Mahnung mit Fristsetzung
  3. 2. Mahnung - Letzte Mahnung vor rechtlichen Schritten

Konfiguration (unter Einstellungen):

  • Mahngebühren pro Stufe (in der Rechnungswährung)
  • Verzugszinsen (% p.a.)

Automatische Berechnung:

  • Verzugszinsen werden taggenau berechnet
  • Mahngebühren werden automatisch addiert

Mahnversand:

  • Per E-Mail mit angepasstem Text je nach Stufe
  • Mahnhistorie wird dokumentiert

Grenzen

Der automatische Lauf erkennt überfällige Rechnungen; er ist kein automatischer Mahnversand. Mahnung senden öffnet den Versanddialog. Gutschriften und bereits umgewandelte Proformas werden nicht gemahnt. Die Mahnung ist eine E-Mail mit Betragsaufstellung; ein eigener Mahnungs-PDF-Anhang wird derzeit nicht erzeugt.

Thema in der Hilfe öffnen

Belege & Dokumentenablage

Öffnen Sie Dokumente und den Upload-Dialog. Wählen Sie Datei, Dokumenttyp, Beschreibung und bei Bedarf Tags, Kunde oder Rechnung. Nach dem Hochladen können Sie suchen, filtern, herunterladen, archivieren, wiederherstellen und entsprechend Ihren Rechten löschen.

Dateien und Grenzen

Der direkte Upload unterstützt Dateien bis 100 MB innerhalb des Speicherkontingents. Falls die direkte Ablage nicht eingerichtet ist, erlaubt der kleine Server-Fallback in der Oberfläche höchstens 4 MB. Unterstützt werden PDF, PNG, JPEG, GIF, WebP, DOC/DOCX, XLS/XLSX, TXT und CSV.

Sichtbarkeit

Firma, Rolle, Ersteller, Freigaben und Kategorien bestimmen den Zugriff. Archivieren erhält die Datei; Löschen entfernt sie. Die Dokumentenablage garantiert keine unbegrenzte Aufbewahrung unabhängig von Löschung und Vertrag.

KI-Dateien

Dateien aus dem KI-Assistenten erscheinen getrennt im Ordner KI-Assistent und dessen Gesprächsordnern. Für Anhänge im Chat gelten eigene kleinere Grenzen. Beim Löschen des Gesprächs werden dessen Dateien ebenfalls entfernt.

Thema in der Hilfe öffnen

Dokumentkategorien & Zugriff

Unter Einstellungen → Dokumentkategorien verwalten Inhaber und Admin Kategorien mit Namen und Farbe, bearbeiten oder archivieren sie und prüfen Belege ohne Kategorie. Pro Beleg ist eine optionale Kategorie möglich. Listen lassen sich nach Kategorie, Zeitraum, Status und Suchtext filtern; die Filter sind kombinierbar.

Zugriff über Rollen

Kategorien hängen an der Rolle, nicht am einzelnen Mitglied. Unter Einstellungen → Rollen & Rechte legen Sie bei den Rechten mit Geltungsbereich die Stufe Kategorien fest und wählen direkt in der Zeile des Rechts die Kategorien, für die dieses Recht gilt. Jedes Recht hat seine eigene Auswahl: Sie können Rechnungen in den Kategorien A und B ansehen, aber nur in B bearbeiten. Details dazu stehen im Abschnitt „Rollen & Rechte“. Wer Rollen und Rechte verwalten darf, erreicht sie unter Einstellungen → Dokumentkategorien auch über die Schaltfläche Rollen & Rechte öffnen im Seitenkopf. Die Rollenübersicht zeigt an jeder Rolle, bei wie vielen Rechten Kategorien gewählt sind und ob die Rolle ausschließlich in bestimmten Kategorien arbeitet.

Belege ohne Kategorie erreicht ein Recht nur, wenn in seiner Auswahl der Eintrag Belege ohne Kategorie gewählt ist. Mit der Karte Arbeitsbereich der Rolle begrenzen und der Option Diese Rolle arbeitet ausschließlich in bestimmten Kategorien sind Belege außerhalb der Grenze gesperrt, auch eigene und freigegebene; eine Freigabe umgeht das nicht.

Bisheriger Zugriff je Teammitglied

Hat Ihre Firma noch Einstellungen aus der früheren Zugriffsverwaltung je Teammitglied, erscheint die Karte Bisheriger Zugriff je Teammitglied. Dieser Zugriff gilt unverändert weiter, lässt sich aber nicht mehr ändern. Wer Rollen und Rechte verwalten darf, überträgt ihn mit In Rollen überführen: Haben alle Mitglieder einer Rolle dieselbe Auswahl, übernimmt die Rolle sie; sonst entsteht je Auswahl eine eigene Rolle („Rolle – Kategorien“), und die Mitglieder wechseln dorthin. Niemand sieht danach mehr oder weniger als vorher.

Kundenvorgabe und Sammeländerung

Eine Standard-Dokumentkategorie am Kunden belegt neue Belege vor, solange noch keine eigene Kategorie gewählt wurde. In der Rechnungsliste können berechtigte Benutzer ausgewählten Belegen über Kategorie ändern gemeinsam eine Kategorie zuweisen. Archivierte Kategorien bleiben an bestehenden Belegen nachvollziehbar.

Thema in der Hilfe öffnen

Dokumentvorlagen

Öffnen Sie Einstellungen → Firmendaten und dort Dokumentenvorlagen. Inhaber und Admin bearbeiten hier die gedruckten Standardtexte für Rechnungen, getrennt nach Deutsch und Englisch. Die aktuelle Oberfläche enthält keine freie Auswahl aller Belegtypen.

  1. Wählen Sie die Inhaltssprache der Vorlage.
  2. Bearbeiten Sie Einleitungs- und Abschlusstext mit dem Rich-Text-Editor und der Platzhalterhilfe, etwa {rechnungsnummer}.
  3. Aktivieren Sie bei Bedarf Artikelnummer anzeigen für die Positionsspalte in Belegen und PDFs.
  4. Speichern Sie oder verwenden Sie Verwerfen. Vor einem Sprachwechsel müssen offene Änderungen gespeichert oder verworfen werden.

Eigene Texte werden nicht automatisch übersetzt. Bewusst leere Texte bleiben leer. Änderungen an Vorlagen schreiben bestehende Belege und archivierte Versions-PDFs nicht rückwirkend um. Die Artikelnummern werden aus Produkt-SKUs übernommen und bleiben bei ausgeblendeter Spalte gespeichert.

Thema in der Hilfe öffnen

Dateinamen-Konfiguration

Legen Sie fest, wie PDF-Dateien beim Herunterladen und beim E-Mail-Versand benannt werden.

Konfiguration:

  1. Gehen Sie zu Einstellungen → Dateinamen
  2. Definieren Sie pro Belegtyp ein Muster mit Platzhaltern, z. B. Rechnung-{rechnungsnummer}
  3. Eine Live-Vorschau zeigt den resultierenden Dateinamen anhand eines Beispiels

Standard:

Ohne eigenes Muster wird einfach die Belegnummer als Dateiname verwendet.

Thema in der Hilfe öffnen

Umsatzbericht

Unter Berichte finden Sie umfassende Auswertungen.

Periodenauswahl:

Wählen Sie flexibel den Auswertungszeitraum:

  • Jahr - Gesamtjahresübersicht
  • Quartal - Q1 (Jan-Mär), Q2 (Apr-Jun), Q3 (Jul-Sep), Q4 (Okt-Dez)
  • Monat - Einzelne Monate

Verfügbare Kennzahlen:

  • Rechnungsumsatz (brutto/netto)
  • Bezahlte Rechnungen
  • Offene Forderungen (abzüglich bereits erfasster Teilzahlungen)
  • Zahlungseingänge
  • Ø Rechnungswert
  • Zahlungsquote
  • Ø Zahlungsdauer (Tage bis zur ersten Zahlung)
  • Vorjahresvergleich (prozentuale Veränderung)

USt-Aufschlüsselung:

Aufschlüsselung nach Steuerland, Steuersätzen und steuerfreien Sonderfällen:

  • AT: 20%, 13%, 10%, 0%
  • DE: 19%, 7%, 0%
  • Übrige EU-Länder mit ihren jeweiligen Landessätzen (OSS-Umsätze getrennt ausgewiesen)
  • Steuerbefreite bzw. nicht steuerbare Fälle wie Reverse Charge oder Export

Monatliche Entwicklung:

Balkendiagramm mit 12-Monats-Übersicht (bei Jahresansicht).

Thema in der Hilfe öffnen

Exporte

Exportieren Sie Ihre Daten für die Buchhaltung.

Verfügbare Formate:

CSV Export

  • Universelles Format
  • Für Excel, Google Sheets
  • Alle Rechnungsdaten

DATEV Export

  • Buchungsstapel-Format
  • Direkt importierbar in DATEV
  • Inklusive Debitorennummern

BMD Export

  • Buchungen und Personenkonten für den Steuerberater (BMD NTCS)
  • Wird als ZIP-Datei bereitgestellt

USt-Report

  • Zusammenfassung nach Steuerland, Steuersätzen und Steuerbehandlung
  • Für die Steuererklärung
  • Netto, USt, Brutto pro Satz

Belege mit Bruttopreisen exportieren Nettobeträge und die USt je Steuersatz genau wie auf dem Beleg (siehe Brutto- oder Nettopreise).

Zeitraum:

Wählen Sie Monat, Quartal oder ganzes Jahr.

Verfügbarkeit:

CSV-Export und USt-Report stehen in jedem Plan zur Verfügung. DATEV- und BMD-Export sind ab dem Starter-Plan verfügbar.

Thema in der Hilfe öffnen

Audit-Log

Inhaber und Admin öffnen Audit-Log. Das Protokoll zeigt aufgezeichnete Aktionen mit Zeitpunkt, Benutzer, Gegenstand und - soweit für das Ereignis vorhanden - Details und Vorher-/Nachher-Werten. Nicht jedes Ereignis besitzt eine IP-Adresse oder einen vollständigen Feldvergleich.

Die Reiter filtern nach Gegenstandstyp, etwa Rechnungen, Kunden oder Zahlungen. Alle setzt den Typfilter zurück. Je Seite werden 50 Einträge angezeigt; die Seitennavigation führt zu älteren Ereignissen. Öffnen Sie vorhandene Details, um Änderungen zu vergleichen. API-Aktionen sind entsprechend bezeichnet. Protokolltexte mit Namen und Freitext bleiben in ihrer ursprünglichen Sprache.

Ein Audit-Log ist eine Nachvollziehbarkeitsfunktion; daraus folgt keine pauschale Zusicherung, dass sämtliche Handlungen unveränderlich oder vollständig protokolliert werden.

Thema in der Hilfe öffnen

Firmendaten

Unter Einstellungen verwalten Sie Ihre Unternehmensdaten.

Grunddaten:

  • Firmenname
  • Adresse
  • UID-Nummer
  • Währung (EUR, CHF, USD)
  • Zusatzzeilen im Rechnungskopf - bis zu 5 frei benannte Zeilen (Bezeichnung und Wert), die auf allen Belegen im Briefkopf unter Steuernummer und UID stehen, z. B. bei Biobetrieben „Bio-Kontrollstelle: AT-BIO-301“. Ohne Bezeichnung wird nur der Wert gedruckt.

Bankverbindung:

  • Kontoinhaber
  • IBAN
  • BIC
  • Bankname

Diese Daten erscheinen auf Ihren Rechnungen und werden für den EPC QR-Code verwendet.

Zahlungsbedingungen:

  • Standard-Zahlungsziel (Tage)
  • Skonto (%) und Skonto-Frist

Steuerliche Einstellungen:

  • Kleinunternehmer-Regelung aktivieren/deaktivieren

Weitere Einstellungen:

  • Branding-Farben - Primär- und Akzentfarbe für PDFs
  • Nummernkreise - Format und Startnummern konfigurieren
  • Individuelle Fußzeile - zusätzlicher Text für die Beleg-Fußzeile; sie fasst insgesamt 6 Zeilen, das Formular zeigt an, wie viele davon Ihre Firmenangaben belegen und wie viele für eigenen Text übrig bleiben

Wählen Sie Rechtsform. Bei Einzelunternehmen geben Sie unter Inhaber Vorname und Nachname an; Geschäftsbezeichnung (optional) kann leer bleiben. Bei Eingetragenes Einzelunternehmen (e.U.) geben Sie zusätzlich den Firmenwortlaut ein. Bei anderen Rechtsformen ist der Firmenname erforderlich. Falls eine Absendervorschau angezeigt wird, prüfen Sie dort den Namen.

Verwendet die Belegmail den Claribill-Standardabsender, gehen Antworten an die gültige externe Firmen-E-Mail aus Einstellungen → Firmendaten. Prüfen Sie dort die E-Mail-Adresse, wenn Kunden nicht an die gewünschte Adresse antworten können.

Thema in der Hilfe öffnen

Sprache und Belegvorlagen

Oberfläche und Belege

Die Sprache der Oberfläche und die Sprache eines Belegs sind unabhängig. Ein Wechsel zwischen Deutsch und Englisch übersetzt keine eigenen Positionstexte, Kundenangaben oder bereits ausgestellten Dokumente.

Sprache neuer Belege

Unter Einstellungen wählen Sie die Standardsprache neuer Belege. Ein Kunde kann eine eigene Belegsprache erhalten oder die Firmeneinstellung übernehmen.

Im Anlageformular können Sie Deutsch oder Englisch ausdrücklich auswählen. Ohne eigene Auswahl gilt zuerst die Kundenvorgabe, danach die Firmeneinstellung. Eine ausdrückliche Auswahl bleibt auch beim Kundenwechsel erhalten.

Folgebelege und Wiederholungen

Kopien, Umwandlungen, Stornos und verknüpfte Gutschriften übernehmen die Sprache des Ausgangsbelegs. Bestehende Wiederholungspläne behalten ihr gespeichertes Sprachprofil. Eine geänderte Firmen- oder Kundenvorgabe ändert diese Dokumente nicht rückwirkend.

Eigene Texte

Gedruckte Rechnungsvorlagen und E-Mail-Vorlagen werden für Deutsch und Englisch getrennt gepflegt. Prüfen Sie vor dem ersten englischen Versand Ihre englischen Vorlagen. Eigene Texte werden nicht automatisch übersetzt; absichtlich leere Rechnungstexte bleiben leer.

Beim Versand bestimmen die gespeicherte Belegsprache und die passende Vorlage den Inhalt. Die Sprache der Person, die auf Senden klickt, ändert die Belegsprache nicht.

Thema in der Hilfe öffnen

Logo hochladen

Laden Sie Ihr Logo für professionelle Rechnungen hoch.

Anforderungen:

  • Format: PNG, JPEG oder SVG
  • Maximale Größe: 500 KB
  • Empfohlene Abmessungen: 300 × 100 Pixel

Verwendung:

  • Erscheint oben links auf allen PDFs
  • Wird automatisch skaliert

Thema in der Hilfe öffnen

Branding-Farben

Passen Sie die Farben Ihrer Dokumente an Ihr Corporate Design an.

Verfügbare Farben:

  • Primärfarbe - Für Überschriften und wichtige Elemente
  • Akzentfarbe - Für sekundäre Elemente und Beträge

Konfiguration:

  1. Gehen Sie zu Einstellungen
  2. Scrollen Sie zum Abschnitt "Branding-Farben"
  3. Wählen Sie Farben per Color-Picker oder geben Sie Hex-Codes ein
  4. Die Live-Vorschau zeigt, wie Ihre Rechnungen aussehen werden

Verwendung:

Die gewählten Farben werden auf allen generierten PDFs angewendet:

  • Rechnungen
  • Angebote
  • Lieferscheine

Thema in der Hilfe öffnen

Nummernkreise

Konfigurieren Sie das Format und die Nummerierung Ihrer Belege.

Einstellungen unter Einstellungen → Nummernkreise:

Nummernformat:

Wählen Sie aus 6 Formaten oder definieren Sie ein eigenes Format:

  • RE-2025-0001 (Prefix-Jahr-Nummer)
  • RE20250001 (Kompakt ohne Trennzeichen)
  • 2025-0001 (Nur Jahr und Nummer)
  • RE/2025/0001 (Mit Schrägstrichen)
  • 202501-0001 (Jahr-Monat-Nummer)
  • 25010001 (Kurzjahr-Monat-Nummer)
  • Eigenes Format - frei definierbares Muster

Nummernlänge:

  • 3 bis 8 Stellen wählbar (von 001 bis 00000001)
  • Standard: 4 Stellen (0001)

Jährlicher Reset:

Bei aktivierter Option beginnt die Nummerierung jedes Jahr wieder bei der Startnummer. Empfohlen für österreichische Unternehmen.

Belegarten:

Konfigurieren Sie die Startnummern separat für:

  • RE - Rechnungen
  • GS - Gutschriften und Stornos
  • PF - Proforma-Rechnungen
  • AN - Angebote
  • AB - Auftragsbestätigungen
  • AU - Aufträge
  • LS - Lieferscheine

Vorschau:

Die Live-Vorschau zeigt Ihnen die nächste Belegnummer für jeden Typ.

Thema in der Hilfe öffnen

API-Schlüssel & Authentifizierung

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.

  1. Bearer-Header prüfen (401 bei fehlendem/ungültigem Header oder unbekanntem Schlüssel).
  2. Plan-Gate apiAccess prüfen und Monatskontingent als ApiLog-Reservierung buchen (403 code: "plan_no_access", 429 code: "quota_exceeded").
  3. Scope(s) der Route gegen die Scopes des Schlüssels prüfen (403 mit requiredScopes bei fehlendem Scope).
  4. 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[] }
StatusBedeutung
400Ungültige Eingabe (Pflichtfeld, Enum-Wert, Zahlen-/Datumsformat, Geschäftsregel).
401Authorization-Header fehlt, ist kein Bearer-Header, oder der Schlüssel ist ungültig/deaktiviert.
403Scope fehlt (requiredScopes in der Antwort), Plan ohne API-Zugang (code: "plan_no_access") oder ein Plan-Limit ist erschöpft.
404Datensatz existiert nicht oder gehört zu einer anderen Firma — es werden nie Daten fremder Firmen ausgeliefert.
409Zustandskonflikt: falscher Status für die Aktion, gleichzeitige Änderung, bereits vergebene Nummer/Referenz.
429Monatskontingent erschöpft (code: "quota_exceeded") oder Rate-Limit erreicht.
500Unerwarteter interner Fehler.
502Ein 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:

ScopeBezeichnungBeschreibung
invoices:readRechnungen lesenRechnungen, Gutschriften, Zahlungen und Mahnstatus lesen, PDFs abrufen
invoices:writeRechnungen bearbeitenRechnungen und Gutschriften erstellen, ändern, versenden, Zahlungen und Mahnungen erfassen
customers:readKunden lesenZugriff auf Kundenlisten und Details
customers:writeKunden bearbeitenKunden erstellen, ändern, archivieren und löschen
products:readProdukte lesenZugriff auf Produktlisten
products:writeProdukte bearbeitenProdukte erstellen und ändern
quotes:readAngebote lesenAngebote und deren PDFs lesen
quotes:writeAngebote bearbeitenAngebote erstellen, ändern, versenden und umwandeln
order-confirmations:readAuftragsbestätigungen lesenAuftragsbestätigungen und deren PDFs lesen
order-confirmations:writeAuftragsbestätigungen bearbeitenAuftragsbestätigungen erstellen, ändern, versenden und umwandeln
delivery-notes:readLieferscheine lesenLieferscheine und deren PDFs lesen
delivery-notes:writeLieferscheine bearbeitenLieferscheine erstellen, ändern, versenden und in Rechnungen umwandeln
orders:readAufträge lesenAufträge, Mengen und Statistiken lesen
orders:writeAufträge bearbeitenAufträge erstellen, ändern und Mengen pflegen
recurring:readWiederkehrende Rechnungen lesenZeitpläne für wiederkehrende Rechnungen lesen
recurring:writeWiederkehrende Rechnungen bearbeitenZeitpläne anlegen, ändern, pausieren und Rechnungen daraus erzeugen
documents:readBelege lesenDokumentenablage lesen und Dateien herunterladen
documents:writeBelege bearbeitenBelege hochladen, ändern, archivieren und löschen
exports:readExporteBuchhaltungsexporte (CSV, DATEV, BMD, UStVA) und Kunden-CSV erzeugen
direct-debits:writeSEPA-Lastschriften anlegenSEPA-Sammelaufträge anlegen und ihre Lastschriftdatei (PAIN.008) erzeugen; die Rechnungen sind danach bis zum Verwerfen für weitere Exporte gesperrt
company:readFirmendaten lesenStammdaten, Nummernkreise und Plan-Funktionen der Firma lesen
webhooks:readWebhooks lesenWebhook-Endpunkte und Zustellungen lesen
webhooks:writeWebhooks verwaltenWebhook-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.

EreignisAuslöser
INVOICE_CREATEDRechnung angelegt (Dashboard-Aktion, POST /api/v1/invoices).
INVOICE_UPDATEDRechnung geändert, ohne Statuswechsel (PUT /api/v1/invoices/{id}).
INVOICE_SENTRechnung per E-Mail an den Kunden versendet.
INVOICE_PAIDZahlung erfasst, die eine Rechnung vollständig ausgleicht.
INVOICE_OVERDUERechnung überschreitet unbezahlt ihr Zahlungsziel.
INVOICE_CANCELLEDRechnung oder Gutschrift storniert.
CREDIT_NOTE_CREATEDGutschrift angelegt.
CREDIT_NOTE_PAIDAuszahlung einer Gutschrift ausgeführt.
PAYOUT_APPROVEDAuszahlung einer Gutschrift zur Ausführung freigegeben.
PAYOUT_EXECUTEDAuszahlung erfolgreich ausgeführt.
PAYOUT_FAILEDAusführung der Auszahlung fehlgeschlagen.
PAYOUT_CANCELLEDAuszahlung vor der Ausführung storniert.
CUSTOMER_CREATEDKunde angelegt.
CUSTOMER_UPDATEDKunde geändert.
CUSTOMER_DELETEDKunde gelöscht.
REMINDER_SENTZahlungserinnerung/Mahnung versendet.
REMINDER_ESCALATEDMahnung auf die nächste Stufe eskaliert.
BLOG_POST_CREATEDPlattformBlogpost angelegt (nur Plattform-Blog).
BLOG_POST_UPDATEDPlattformBlogpost geändert (nur Plattform-Blog).
BLOG_POST_PUBLISHEDPlattformBlogpost veröffentlicht bzw. geplante Veröffentlichung ausgelöst (nur Plattform-Blog).
BLOG_POST_UNPUBLISHEDPlattformBlogpost zurückgezogen/archiviert (nur Plattform-Blog).
BLOG_COMMENT_CREATEDPlattformNeuer Blog-Kommentar eingereicht (nur Plattform-Blog).
BLOG_COMMENT_APPROVEDPlattformBlog-Kommentar freigegeben/moderiert (nur Plattform-Blog).
WEBHOOK_TESTTestereignis ü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.

Thema in der Hilfe öffnen

E-Mail-Templates

Passen Sie die Texte Ihrer automatisch versendeten E-Mails individuell an.

Verfügbare Templates:

TemplateVerwendung
Rechnungs-E-MailBeim Versenden von Rechnungen
Gutschrift-E-MailBeim Versenden von Gutschriften
Proforma-E-MailBeim Versenden von Proforma-Rechnungen
Angebots-E-MailBeim Versenden von Angeboten
Auftragsbestätigungs-E-MailBeim Versenden von Auftragsbestätigungen
Lieferschein-E-MailBeim Versenden von Lieferscheinen
ZahlungserinnerungErste freundliche Erinnerung
1. MahnungFormelle Mahnung
2. MahnungLetzte Mahnung vor rechtlichen Schritten

Jedes dieser Templates wird beim Versand der jeweiligen Belegart verwendet - im Dashboard, über die REST-API und bei wiederkehrenden Rechnungen. Ohne eigene Anpassung gilt der Standardtext.

Bei den Mahnstufen steht der Text vor der Aufstellung der Rechnung, der Abschlusstext danach. Rechnungsdaten, Gebühren, Bankverbindung und die Hinweise „Falls Sie die Zahlung bereits veranlasst haben …“ und „Bei Fragen stehen wir Ihnen gerne zur Verfügung.“ setzt Claribill selbst.

Auch Team-Einladungen verwenden eine eigene Vorlage. Storno-Mails verwenden die Vorlage der Gutschrift. Vorlagen werden für Deutsch und Englisch getrennt gepflegt; die gespeicherte Beleg- bzw. Einladungssprache bestimmt die Auswahl. Inaktive Vorlagen fallen auf den Standard derselben Sprache zurück.

Platzhalter:

Verwenden Sie dynamische Platzhalter, die automatisch ersetzt werden:

  • {companyName} - Ihr Firmenname
  • {invoiceNumber} - Rechnungsnummer
  • {grossTotal} - Bruttobetrag
  • {dueDate} - Fälligkeitsdatum
  • {customerName} - Kundenname
  • {daysPastDue} - Tage überfällig (für Mahnungen)

Welche Platzhalter für welches Template zur Verfügung stehen, zeigt die Einstellungsseite beim Bearbeiten.

Bearbeiten:

  1. Gehen Sie zu Einstellungen → E-Mail Templates
  2. Wählen Sie ein Template
  3. Passen Sie Betreff, Grußformel, Text und Signatur an
  4. Speichern Sie die Änderungen

Jedes Template kann jederzeit auf den Standard zurückgesetzt werden.

Betreffregel:

Ein eigener Betreff muss die Belegnummer enthalten (Platzhalter {invoiceNumber} bzw. {documentNumber}, je nach Belegart) - so bleibt jede E-Mail als Beleg Ihrer Firma erkennbar.

Versandgrenzen:

Zum Schutz vor Missbrauch begrenzt Claribill den Versand an fremde Empfänger: 10 E-Mails/Stunde und 30/Tag in den ersten 30 Tagen einer neuen Firma, danach 50/Stunde und 200/Tag. Mails an Ihr eigenes, verifiziertes Team zählen nicht mit. Wird die Grenze erreicht, schlägt der Versand mit einer entsprechenden Meldung fehl.

Thema in der Hilfe öffnen

Eigene E-Mail-Domain

Versenden Sie E-Mails von Ihrer eigenen Domain statt von claribill.com.

Verfügbarkeit:

Eigene Domain und eigener SMTP-Server sind ab dem Professional-Plan verfügbar. Ohne diese Plan-Funktion versendet Claribill weiterhin über den eigenen Absender.

Vorteile:

  • Professioneller Auftritt mit Ihrer Firmendomain
  • Bessere Zustellbarkeit durch DKIM-Signatur
  • Kunden erkennen Ihre E-Mails sofort als vertrauenswürdig

Einrichtung:

  1. Gehen Sie zu Einstellungen → E-Mail Domain
  2. Geben Sie Ihre Domain ein (z.B. musterfirma.at)
  3. Wählen Sie Absendername und E-Mail-Adresse (z.B. rechnung)
  4. Klicken Sie auf "Domain einrichten"
  5. Fügen Sie die angezeigten DNS-Einträge bei Ihrem Domain-Provider hinzu

DNS-Einträge im Detail

Nach dem Einrichten werden Ihnen 5 DNS-Einträge angezeigt, die Sie bei Ihrem Domain-Provider (z.B. Hetzner, IONOS, all-inkl, Cloudflare) setzen müssen:

1. Domain-Verifizierung (TXT-Eintrag)

FeldWert
TypTXT
Name/Host_amazonses.ihredomain.at
Wert/InhaltDer angezeigte Verifizierungstoken (lange Zeichenkette)
TTL300 oder Standard

Beispiel:

Name:  _amazonses.musterfirma.at
Wert:  abc123def456xyz789...

2. DKIM-Signatur (3 CNAME-Einträge)

DKIM stellt sicher, dass E-Mails wirklich von Ihrer Domain stammen. Sie erhalten 3 separate CNAME-Einträge:

FeldWert
TypCNAME
Name/Host[token1]._domainkey.ihredomain.at
Ziel/Wert[token1].dkim.amazonses.com

Beispiel für alle 3 Einträge:

Name:  abc123._domainkey.musterfirma.at
Ziel:  abc123.dkim.amazonses.com

Name:  def456._domainkey.musterfirma.at
Ziel:  def456.dkim.amazonses.com

Name:  ghi789._domainkey.musterfirma.at
Ziel:  ghi789.dkim.amazonses.com

3. SPF-Eintrag (optional, aber empfohlen)

FeldWert
TypTXT
Name/Hostihredomain.at (oder @)
Wert/Inhaltv=spf1 include:amazonses.com ~all

Hinweis: Falls Sie bereits einen SPF-Eintrag haben, fügen Sie include:amazonses.com vor dem ~all oder -all hinzu:

Vorher: v=spf1 include:_spf.google.com ~all
Nachher: v=spf1 include:_spf.google.com include:amazonses.com ~all

Wo finde ich die DNS-Einstellungen?

ProviderPfad
HetznerDNS Console → Zone auswählen → Records
IONOSDomains → DNS-Einstellungen
all-inklKAS → Domain → DNS-Einstellungen
CloudflareDNS → Records
StratoDomain-Verwaltung → DNS-Verwaltung
HostpointControl Panel → DNS Zone

Verifizierung prüfen

  • DNS-Änderungen können bis zu 48 Stunden dauern (meist schneller)
  • Klicken Sie auf "Status prüfen" um den aktuellen Stand zu sehen
  • ✅ Domain verifiziert + ✅ DKIM verifiziert = E-Mails werden von Ihrer Domain versendet

Häufige Fehler:

  • Tippfehler bei Copy/Paste (unsichtbare Leerzeichen)
  • Falscher Eintragstyp (TXT statt CNAME oder umgekehrt)
  • Punkte am Ende des Hostnamens (manche Provider brauchen sie, manche nicht)
  • TTL zu hoch eingestellt (Standard ist meist ok)

Thema in der Hilfe öffnen

CSV-Import

Importieren Sie Kunden und Produkte aus CSV-Dateien.

Unterstützte Importe:

  • Kunden: rund 30 Spalten, u. a. Kundennummer, Name/Firma, Anrede, Adresse, UID-Nummer, Steuernummer, Bankdaten, Zahlungsziel, Skonto, Notiz und Gruppe
  • Artikel & Leistungen: Name, Preis, Steuersatz, Einheit, SKU, Dienstleistungs-Flag

CSV-Format:

  • UTF-8 Encoding
  • Erste Zeile enthält Spaltennamen
  • Trennzeichen: Komma (,) oder Semikolon (;) - wird automatisch erkannt
  • Texte mit Sonderzeichen in Anführungszeichen

Spaltenzuordnung:

Nach dem Hochladen ordnen Sie die Spalten Ihrer Datei manuell den Claribill-Feldern zu, bevor der Import gestartet wird.

Hinweise:

  • Maximum 1.000 Zeilen pro Import
  • Duplikate werden übersprungen (basierend auf E-Mail bzw. SKU)
  • Fehler werden detailliert angezeigt

Verfügbarkeit:

Der CSV-Import ist ab dem Starter-Plan verfügbar. Beim Kundenimport wird nur so weit importiert, wie es das Kunden-Limit Ihres Plans zulässt - überzählige Zeilen erscheinen als Fehler.

Für Artikel wählen Sie Artikel & Leistungen. Nach der Vorschau startet Artikel importieren den Import; Artikelliste öffnen führt zu den übernommenen Artikeln.

Thema in der Hilfe öffnen

API-Referenz

API-Referenz

API-Explorer

Alle Ressourcen, Endpunkte, Felder und Seiteneffekte der REST-API v1 stammen aus demselben Katalog wie das OpenAPI-Dokument.

Rechnungen24 Endpunkte · invoices:read, invoices:write

Rechnungen und Proformas inkl. Zahlungen, Mahnwesen, Berichtigung, Versionierung und Factur-X/ZUGFeRD-Export.

MethodePfadScopeKurzbeschreibung
POST/api/v1/invoices/prepareinvoices:read, customers:readREST-Erstellungsabsicht lesend vorbereiten
GET/api/v1/invoicesinvoices:readRechnungen auflisten (inkl. Gutschriften und Proformas)
POST/api/v1/invoicesinvoices:writeRechnung (oder Proforma) als Entwurf anlegen
GET/api/v1/invoices/{id}invoices:readRechnungsdetails lesen
PUT/api/v1/invoices/{id}invoices:writeRechnung ändern und/oder Status wechseln
DELETE/api/v1/invoices/{id}invoices:writeRechnungsentwurf löschen
GET/api/v1/invoices/{id}/pdfinvoices:readRechnungs-PDF laden
GET/api/v1/invoices/send-capabilityinvoices:writeOpt-in-Versandfähigkeit prüfen
GET/api/v1/invoices/{id}/send-statusinvoices:writeHistorischen Opt-in-Versandstatus lesen
POST/api/v1/invoices/{id}/sendinvoices:writeRechnung per E-Mail versenden
POST/api/v1/invoices/{id}/cancelinvoices:writeRechnung stornieren (mit optionaler Storno-Gutschrift)
POST/api/v1/invoices/{id}/stornoinvoices:writeNachträgliche Storno-Gutschrift zu einer bereits stornierten Rechnung
POST/api/v1/invoices/{id}/duplicateinvoices:writeRechnung als neuen Entwurf duplizieren
POST/api/v1/invoices/{id}/convertinvoices:writeProforma in eine reguläre Rechnung umwandeln
GET/api/v1/invoices/{id}/paymentsinvoices:readZahlungen einer Rechnung auflisten
POST/api/v1/invoices/{id}/paymentsinvoices:writeZahlung zu einer Rechnung erfassen
PUT/api/v1/invoices/{id}/payments/{paymentId}invoices:writeZahlung ändern
DELETE/api/v1/invoices/{id}/payments/{paymentId}invoices:writeZahlung löschen
GET/api/v1/invoices/{id}/dunninginvoices:readMahnstatus und Mahnhistorie lesen
POST/api/v1/invoices/{id}/dunninginvoices:writeMahnwesen pausieren/fortsetzen oder eine Mahnstufe versenden
POST/api/v1/invoices/{id}/correctinvoices:writeBerichtigung nach § 31 Abs. 5 UStDV anlegen (neue Version)
GET/api/v1/invoices/{id}/versionsinvoices:readVersionshistorie einer Rechnung lesen
GET/api/v1/invoices/{id}/versions/{version}/pdfinvoices:readArchiviertes PDF einer bestimmten Version laden
GET/api/v1/invoices/{id}/facturxinvoices:readFactur-X/ZUGFeRD-XML herunterladen
POST/api/v1/invoices/prepare— REST-Erstellungsabsicht lesend vorbereiten

Scope: invoices:readcustomers:read

Body-Felder

FeldTypPflichtStandardBeschreibung
preparation_versionnumbernein–Nur für create_body aus POST /invoices/prepare: Version 1 bindet die vollständige Erstellungsabsicht; unbekannte Version → 409. Ohne Feld bleibt der bisherige Create-Vertrag.
documentTextVersionnumbernein–Bei preparation_version: verpflichtend 1; andere Textversion → 409.
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–Muss zur Firma gehören
linesLineInput[]ja–Mindestens eine Position
invoiceType / invoice_typestring (Enum)neinINVOICECREDIT_NOTE → 400, Verweis auf POST /api/v1/credit-notesINVOICE | PROFORMA
issueDateISO-DatumneinheuteRechnungsdatum
dueDateISO-Datumneincustomer.paymentTermDays ?? company.paymentTermDays ?? 14 TageFälligkeit
servicePeriodStart / servicePeriodEndISO-Datum | nullnein–Leistungszeitraum
currencystringneinEURWährungscode
reverseChargebooleanneinfalseSteuerschuldnerschaft des Leistungsempfängers
pricesIncludeTax / prices_include_taxbooleanneinfalsePreisart: true = Einzelpreise und Rabattbeträge inkl. USt (Bruttopreise, B2C), false = Nettopreise. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.
taxExemptionReasonstring (Enum)nein–Ungültig → 400NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
taxExemptionNotestringnein–Freitext zur Befreiung
taxCountry / deliveryCountrystring (ISO-2)nein–Steuer- bzw. Lieferland
ossApplicable / oss_applicablebooleannein–Ohne Angabe wird OSS aus dem Steuerkontext abgeleitet
ossCountry / oss_countrystring (ISO-2)nein–OSS-Bestimmungsland
notesstringnein–Interne Anmerkung, nicht gedruckt
footerstringnein–Schlusstext (gedruckt)
headerText / header_textstring (HTML)nein–Einleitungstext (gedruckt)
customTitle / custom_titlestringnein–Eigener Belegtitel statt „Rechnung“
pdfWithoutLetterhead / pdf_without_letterheadbooleanneinfalsePDF ohne Briefkopf
invoiceDateIsServiceDate / invoice_date_is_service_datebooleanneinfalseRechnungsdatum = Leistungsdatum
useShippingAddress / use_shipping_addressbooleanneinfalseAktiviert shippingName/-Street/-ZipCode/-City/-Country
documentCategoryId / document_category_idstring | nullnein–Dokumentkategorie
orderNumber / order_numberstringnein–Bestellnummer/Auftragsreferenz
buyerReference / buyer_referencestringnein–Käuferreferenz bzw. Leitweg-ID
eInvoiceAudit / e_invoiceobjectnein–Auditdaten für Format, Einreichkanal, Portal-URL, Status
metadataobjectnein–Freies JSON-Objekt
lines[].descriptionstringnein–Positionsbeschreibung
lines[].quantitynumbernein1Menge
lines[].unitPrice / unit_pricenumbernein0Einzelpreis in der Preisart des Belegs (netto bzw. bei pricesIncludeTax brutto)
lines[].taxRate / tax_ratenumberneinStandardsatz des SteuerlandsSteuersatz in %
lines[].discountnumbernein0Absoluter Rabattbetrag (kein Prozentsatz!)
lines[].unitstring | nullnein–Nur im vorbereiteten Body ausgewertet: bindet die Einheit einschließlich der bisherigen Spaltenvorgabe Stk. Gewöhnliche Create-Bodys behalten ihr bisheriges Verhalten.
lines[].lineType / line_typestring (Enum)neinPRODUCTPositionstypPRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK

Antwort: 200 { data: InvoicePreparation }

  • Gleicher REST-Parser und Create-Kern, konsistenter Repeatable-Read-Snapshot von Kunde, Firma und INVOICE-Sprachvorlagen. POST hält private Belegtexte aus URL-Logs; Antwort Cache-Control: no-store.
  • create_body einmal vor dem ersten Create speichern: Sprache/Textversion, Texte/null/leer, Datum/Fälligkeit, EUR-Vorgabe, Positionen, Steuer und OSS sind ausdrücklich gebunden. Dieselben JSON-Bytes mit OriginalKey wiederverwenden; kein erneutes prepare für einen alten Claim.
  • Keine Rechnung, Nummer, Audit, Auszahlung, Mail, PDF, S3- oder Geschäfts-Webhook-Aktion. Bestehende API-Key-Nutzung und ApiLog-/Monatskontingent bleiben Betriebswirkungen. Berechtigungen, Plan, Kategorie und Kundenbesitz werden beim Create erneut geprüft; Vorbereitung reserviert nichts.
  • Kein Snapshot späterer PDF-/Maildarstellung oder Stammdatenadressen und keine Send-Idempotenz. Bestehender Create-Key mindestens 30 Tage, konservatives CMM-Wiederaufnahmefenster höchstens 24 Stunden; Altclaims ohne Originalbody bleiben unklar.
GET/api/v1/invoices— Rechnungen auflisten (inkl. Gutschriften und Proformas)

Scope: invoices:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–Filtert nach Status, Groß-/Kleinschreibung egalDRAFT | FINAL | SENT | PAID | OVERDUE | CANCELLED
invoice_type / invoiceTypestring (Enum)nein–Filtert nach BelegartINVOICE | CREDIT_NOTE | PROFORMA
customer_id / customerIdstringnein–Filtert nach Kunde
searchstringnein–Case-insensitive Teiltreffer in Belegnummer oder Kundenname
fromISO-Datumnein–issueDate ≥ from
toISO-Datumnein–issueDate ≤ to
category_idstring | "uncategorized"nein–Filtert nach Dokumentkategorie
limitnumbernein50Seitengröße
offsetnumbernein0Versatz

Antwort: { data: Invoice[], pagination }. Ohne invoice_type sind auch Gutschriften und Proformas enthalten. Sortierung issueDate absteigend.

  • Alle Abfragen sind auf die Firma des API-Keys gefiltert.
  • Ungültiger status/invoice_type → 400 mit allowedValues.
POST/api/v1/invoices— Rechnung (oder Proforma) als Entwurf anlegen

Scope: invoices:write

HTTP-Header

FeldTypPflichtStandardBeschreibung
Idempotency-Keystringnein–Optional, 8–200 Zeichen aus A–Z, a–z, 0–9, . _ : -. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert dieselbe Rechnung in ihrem aktuellen Stand (201, Header Idempotent-Replayed: true) statt einer zweiten; derselbe Schlüssel mit anderem Body → 422 idempotency_key_reused. Verglichen wird der ganze Body, auch Felder, die der Server nicht auswertet. Gilt pro Firma; parallele Aufrufe mit demselben Schlüssel ergeben genau eine Rechnung. Ein Schlüssel wirkt mindestens 30 Tage; danach wird er gelöscht, und derselbe Schlüssel legt wieder eine neue Rechnung an.

Body-Felder

FeldTypPflichtStandardBeschreibung
preparation_versionnumbernein–Nur für create_body aus POST /invoices/prepare: Version 1 bindet die vollständige Erstellungsabsicht; unbekannte Version → 409. Ohne Feld bleibt der bisherige Create-Vertrag.
documentTextVersionnumbernein–Bei preparation_version: verpflichtend 1; andere Textversion → 409.
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–Muss zur Firma gehören
linesLineInput[]ja–Mindestens eine Position
invoiceType / invoice_typestring (Enum)neinINVOICECREDIT_NOTE → 400, Verweis auf POST /api/v1/credit-notesINVOICE | PROFORMA
issueDateISO-DatumneinheuteRechnungsdatum
dueDateISO-Datumneincustomer.paymentTermDays ?? company.paymentTermDays ?? 14 TageFälligkeit
servicePeriodStart / servicePeriodEndISO-Datum | nullnein–Leistungszeitraum
currencystringneinEURWährungscode
reverseChargebooleanneinfalseSteuerschuldnerschaft des Leistungsempfängers
pricesIncludeTax / prices_include_taxbooleanneinfalsePreisart: true = Einzelpreise und Rabattbeträge inkl. USt (Bruttopreise, B2C), false = Nettopreise. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.
taxExemptionReasonstring (Enum)nein–Ungültig → 400NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
taxExemptionNotestringnein–Freitext zur Befreiung
taxCountry / deliveryCountrystring (ISO-2)nein–Steuer- bzw. Lieferland
ossApplicable / oss_applicablebooleannein–Ohne Angabe wird OSS aus dem Steuerkontext abgeleitet
ossCountry / oss_countrystring (ISO-2)nein–OSS-Bestimmungsland
notesstringnein–Interne Anmerkung, nicht gedruckt
footerstringnein–Schlusstext (gedruckt)
headerText / header_textstring (HTML)nein–Einleitungstext (gedruckt)
customTitle / custom_titlestringnein–Eigener Belegtitel statt „Rechnung“
pdfWithoutLetterhead / pdf_without_letterheadbooleanneinfalsePDF ohne Briefkopf
invoiceDateIsServiceDate / invoice_date_is_service_datebooleanneinfalseRechnungsdatum = Leistungsdatum
useShippingAddress / use_shipping_addressbooleanneinfalseAktiviert shippingName/-Street/-ZipCode/-City/-Country
documentCategoryId / document_category_idstring | nullnein–Dokumentkategorie
orderNumber / order_numberstringnein–Bestellnummer/Auftragsreferenz
buyerReference / buyer_referencestringnein–Käuferreferenz bzw. Leitweg-ID
eInvoiceAudit / e_invoiceobjectnein–Auditdaten für Format, Einreichkanal, Portal-URL, Status
metadataobjectnein–Freies JSON-Objekt
lines[].descriptionstringnein–Positionsbeschreibung
lines[].quantitynumbernein1Menge
lines[].unitPrice / unit_pricenumbernein0Einzelpreis in der Preisart des Belegs (netto bzw. bei pricesIncludeTax brutto)
lines[].taxRate / tax_ratenumberneinStandardsatz des SteuerlandsSteuersatz in %
lines[].discountnumbernein0Absoluter Rabattbetrag (kein Prozentsatz!)
lines[].unitstring | nullnein–Nur im vorbereiteten Body ausgewertet: bindet die Einheit einschließlich der bisherigen Spaltenvorgabe Stk. Gewöhnliche Create-Bodys behalten ihr bisheriges Verhalten.
lines[].lineType / line_typestring (Enum)neinPRODUCTPositionstypPRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK

Antwort: 201 { data: Invoice }, wie GET-Detail ohne payments.

  • Legt einen Entwurf mit Platzhalternummer ENTWURF-… an; die echte Nummer vergibt erst der Statuswechsel auf FINAL/SENT bzw. POST …/send.
  • Mit Idempotency-Key lässt sich ein Aufruf nach Timeout oder Verbindungsabbruch gefahrlos wiederholen. Ungültiges Format → 422 invalid_idempotency_key; wurde die Rechnung zum Schlüssel inzwischen gelöscht → 409 idempotency_key_invoice_deleted. Eine Wiederholung prüft kein Belegelimit und löst keinen Webhook aus — bricht schon der erste Aufruf nach dem Anlegen ab, kann dessen INVOICE_CREATED-Webhook fehlen. Ein mitgeschickter, aber ungültiger Idempotency-Key wird abgelehnt statt ignoriert.
  • Summen über prepareInvoiceTaxPayload — identisch zum Dashboard: absoluter Positionsrabatt, Normalisierung der Steuersätze auf das Steuerland, automatische OSS-Ableitung, sofern kein Kennzeichen mitgeschickt wird.
  • Bruttopreise (pricesIncludeTax: true): Die USt wird je Steuersatz aus dem Brutto herausgerechnet, die Belegsumme ist die Summe der Brutto-Positionen (3 × 19,99 € = 59,97 €). lineTotal bleibt netto, ebenso alle Exporte und die E-Rechnung.
  • 400 bei Pflichtfeld/Enum/Rabatt über dem Positionsbetrag (lineIndex in der Antwort); 404 Customer/Company/Document category not found.
  • Audit INVOICE_CREATED_VIA_API. Webhook INVOICE_CREATED.
GET/api/v1/invoices/{id}— Rechnungsdetails lesen

Scope: invoices:read

Antwort: { data: Invoice } inkl. footer, sentAt, paidAt, lockedAt, customer (mit Adresse/UID), lines[], payments[], paidAmount.

  • 404 Invoice not found, auch für fremde Firmen.
PUT/api/v1/invoices/{id}— Rechnung ändern und/oder Status wechseln

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–Statuswechsel, ungültig → 400 mit allowedValuesDRAFT | FINAL | SENT | PAID | OVERDUE | CANCELLED
documentCategoryId, dueDate, servicePeriodStart, servicePeriodEnd, reverseCharge, taxExemptionReason, taxExemptionNote, taxCountry, deliveryCountry, ossApplicable, ossCountry, headerText, notes, footer, orderNumber, buyerReference, customTitle, pdfWithoutLetterhead, invoiceDateIsServiceDate, useShippingAddress + shipping*, eInvoiceAudit/e_invoicegemischtnein–Alle optional, jeweils auch snake_case; nur Inhaltsfelder — siehe Hinweise für die Sperre
pricesIncludeTax / prices_include_taxbooleannein–Preisart ändern: USt und Summen werden aus den Preisen neu berechnet, die Preise selbst bleiben. Ohne Angabe bleibt die gespeicherte Preisart. Nur true/false, sonst 400.
linesLineInput[]nein–Ersetzt alle Positionen (mind. 1)

Antwort: 200 { data: { id, invoiceNumber, status, netTotal, taxTotal, grossTotal, pricesIncludeTax, orderNumber, buyerReference, e_invoice, updatedAt, [stornoInvoiceId, stornoInvoiceNumber] } }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403 plan_limit_reached (Stornieren eines Entwurfs bleibt möglich).
  • Statuswechsel über lib/invoice-status-transitions.ts: DRAFT→FINAL|SENT|CANCELLED, FINAL→SENT|DRAFT|CANCELLED, SENT→PAID|OVERDUE|CANCELLED, OVERDUE→PAID|CANCELLED; PAID/CANCELLED sind Endzustände. Ungültig → 400 mit allowedTransitions.
  • Gutschriften können nicht auf OVERDUE gesetzt werden: 400 mit code credit_note_overdue, auch wenn ein historischer Beleg bereits OVERDUE ist. allowedTransitions berücksichtigt die Belegart; Rechnungen und nicht umgewandelte Proformas bleiben unverändert.
  • DRAFT→FINAL/SENT vergibt die echte Nummer atomar (Nummernkreis nach Belegart, keine Lücken); →SENT setzt sentAt und schreibt fest (lockedAt, v1-Snapshot); FINAL bleibt bewusst ungesperrt; →PAID setzt paidAt.
  • →CANCELLED erzeugt für ausgestellte Rechnungen automatisch die Storno-Gutschrift (wie POST …/cancel mit createStorno: true), ohne E-Mail.
  • Inhaltliche Änderungen nur an bearbeitbaren Rechnungen (DRAFT oder FINAL und nicht festgeschrieben, lib/invoice-lock.ts) — sonst 400 mit lockedFields und Verweis auf die Berichtigung. Ein unveränderter Read-Modify-Write-Body stört den Statuswechsel nicht.
  • Webhooks INVOICE_SENT/INVOICE_PAID/INVOICE_CANCELLED beim Statuswechsel, sonst INVOICE_UPDATED; zusätzlich CREDIT_NOTE_CREATED bei automatischem Storno. Audit INVOICE_UPDATED_VIA_API. Konflikte → 409.
DELETE/api/v1/invoices/{id}— Rechnungsentwurf löschen

Scope: invoices:write

Antwort: 200 { success: true }

  • Nur Entwürfe (DRAFT), sonst 400. Löscht Positionen und Beleg in einer Transaktion und gibt verknüpfte Ursprungsbelege (Angebot, AB, Lieferschein) wieder frei.
  • Trägt der Entwurf schon eine echte Nummer (etwa nach fehlgeschlagenem Versand) → 409 { code: "invoice_number_issued", invoiceNumber }: Damit der Nummernkreis lückenlos bleibt, lässt er sich nur erneut versenden oder per Status CANCELLED stornieren (ohne Storno-Gutschrift).
  • Audit INVOICE_DELETED_VIA_API.
GET/api/v1/invoices/{id}/pdf— Rechnungs-PDF laden

Scope: invoices:read

Antwort: 200 PDF-Binary, Content-Type application/pdf, Content-Disposition inline, Header X-PDF-Source: generated|s3-cache.

  • Rendert über lib/invoice-pdf-bundle.ts (gleiches Layout wie das Dashboard), bewusst ohne S3-Cache.
  • 404 Invoice not found. Audit PDF_DOWNLOADED_VIA_API nur bei Treffer.
GET/api/v1/invoices/send-capability— Opt-in-Versandfähigkeit prüfen

Scope: invoices:write

Antwort: 200 { data: InvoiceSendCapability }

  • Authentifiziert und ungecacht. supported=false bei deaktiviertem Feature, fehlendem Schema/Firmengate oder Recovery-Epoch-Abweichung. Keine Versandprobe.
GET/api/v1/invoices/{id}/send-status— Historischen Opt-in-Versandstatus lesen

Scope: invoices:write

HTTP-Header

FeldTypPflichtStandardBeschreibung
Idempotency-Keystringja–Ursprünglicher unveränderter Send-Key; niemals als URL-Parameter.

Antwort: 200 { data: InvoiceSendStatus }

  • Liest ausschließlich vorhandenen Zustand: 202 laufend/unbestätigt, 409 Klärung oder sicher nicht eingereicht, 404 ohne Receipt ist kein Nichtannahmebeweis. Gespeicherte Zustände bleiben nach POST-Ablauf und bei deaktiviertem Versand lesbar. API-Auth/Nutzungslogging bleibt erhalten.
  • resolution_decision enthält nur das explizite Klärungsergebnis (oder null), ohne Operator-/Belegreferenzen. UNKNOWN bleibt historisch UNKNOWN; CONFIRMED_ACCEPTED bestätigt die Annahme, nicht die Zustellung.
POST/api/v1/invoices/{id}/send— Rechnung per E-Mail versenden

Scope: invoices:write

HTTP-Header

FeldTypPflichtStandardBeschreibung
Idempotency-Keystringnein–Opt-in invoice_send_v1; ohne aktive Capability 503, niemals Legacy-Fallback.

Body-Felder

FeldTypPflichtStandardBeschreibung
recipientEmail / recipient_emailstringneinE-Mail des KundenEmpfänger
ccstringnein–Kopie
bccstringnein–Blindkopie

Antwort: 200 { data: { invoiceId, invoiceNumber, status (klein geschrieben), sentTo, cc, bcc, sentAt } } (jeweils auch snake_case)

  • Opt-in-Vorschlag #719, standardmäßig deaktiviert: zuerst GET /api/v1/invoices/send-capability mit invoices:write prüfen. Nur supported=true erlaubt den neuen Vertrag; OpenAPI allein ist kein Aktivierungsbeleg.
  • Mit Key cb-send-v1.<13-stellige Unix-Millisekunden>.<kleine UUID-v4>: recipient_email und expected_updated_at (UTC-ISO mit Millisekunden) erforderlich, cc/bcc sind Arrays nackter ASCII-Mailboxen. Ohne Key gilt unverändert der bisherige Body mit String-CC/BCC und Kundenfallback.
  • Opt-in: 24h bis Erstannahme UND erstem Transport, 30 Tage historisches Replay, 5min Zukunftstoleranz; feste Fristen ab Key-Zeit. 202 bedeutet vorhandenen Vorgang, 200 ACCEPTED nur Providerannahme, 409 UNKNOWN/Teilannahme verlangt Klärung, 410 abgelaufen, 422 ungültiger Key/Body. Niemals automatisch Key erneuern oder ohne Key ausweichen.
  • Versand eines Entwurfs bei erschöpftem Dokumentenkontingent → 403 plan_limit_reached (vor der Nummernvergabe).
  • Fachkern lib/invoice-api-email.ts. Entwürfe mit Platzhalter bekommen vorher die echte Nummer (Zähler, Rechnung und Audit INVOICE_NUMBER_ISSUED in einer Transaktion). Scheitert der Versand, bleibt die Nummer am Entwurf und wird beim nächsten Versuch wiederverwendet, nie zurückgegeben. PDF + E-Mail-Text wie im Dashboard.
  • Erst nach erfolgreichem Versand: Status DRAFT/FINAL → SENT, sentAt, Festschreibung (lockedAt, v1). Audit INVOICE_SENT_VIA_API, Webhook INVOICE_SENT.
  • Eine stornierte Rechnung lässt sich versenden und bleibt storniert: Vermerkt werden sentAt (falls noch leer), Audit und Webhook INVOICE_SENT mit dem tatsächlichen Status.
  • Ein Entwurf oder eine fertige Rechnung ist während des Versands reserviert, wie im Dashboard: Ein gleichzeitiger zweiter Versand derselben Rechnung (API, Einzel- oder Massen-Versand) bekommt 409 send_in_progress, ohne Mail und ohne Nummernvergabe. Die Reservierung verfällt nach einem Absturz nach zehn Minuten.
  • Fehler: 404 unbekannt, 400 keine Empfängeradresse oder nie ausgestellter Entwurf mit Platzhalternummer, 409 umgewandelte Proforma oder Versand läuft bereits (send_in_progress), 500 Versand fehlgeschlagen.
  • 409 umgewandelte Proforma: { error, invoice_id, invoice_number } nennt die Rechnung, die zu versenden ist. invoiceId/invoiceNumber (gleiche Werte) sind veraltet und entfallen in einer späteren Version.
POST/api/v1/invoices/{id}/cancel— Rechnung stornieren (mit optionaler Storno-Gutschrift)

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
createStorno / create_stornobooleanneintrueStorno-Gutschrift erzeugen
sendStornoToCustomer / send_storno_to_customerbooleanneinfalseStorno-Gutschrift per E-Mail versenden
recipientEmail / recipient_emailstringnein–Nur mit Versand relevant

Antwort: 200 { data: { id, invoiceNumber, status: "CANCELLED", stornoInvoiceId, stornoInvoiceNumber, stornoEmailSent, [warning] } }

  • Fachkern cancelInvoiceCore (lib/invoices/cancel.ts, gemeinsam mit Dashboard und KI-Assistent; Schreibvorgang cancelInvoiceWithOptionalStorno in lib/storno.ts). Ein Gegenbeleg entsteht nur für ausgestellte Rechnungen vom Typ INVOICE (isStornoEligible): Gutschrift Grund CANCELLATION, eigene GS-Nummer, Status FINAL, negative Beträge — atomar mit dem Statuswechsel.
  • Entwürfe/Proformas/Gutschriften werden nur auf CANCELLED gesetzt. Stornierbar aus DRAFT, FINAL, SENT, OVERDUE; sonst 409. Paralleler Statuswechsel → 409.
  • Trägt die Rechnung Zahlungen aus einer Proforma, gehen sie beim Stornieren an die Proforma zurück. Fehlt die Proforma oder ist sie storniert (Altdaten), wird nichts geschrieben → 409 mit Hinweis, zuerst die Zahlungen zu entfernen (wie PUT mit status CANCELLED).
  • Optionaler E-Mail-Versand ist nicht fatal (→ warning), Storno bleibt bestehen. Webhooks INVOICE_CANCELLED und CREDIT_NOTE_CREATED (+ INVOICE_SENT bei Versand).
  • Audit INVOICE_CANCELLED_VIA_API (Urheber: Inhaber der Firma, bei mehreren der mit der ältesten Mitgliedschaft).
  • 409 umgewandelte Proforma: { error, invoice_id, invoice_number } nennt die Rechnung, die zu stornieren ist. invoiceId/invoiceNumber (gleiche Werte) sind veraltet und entfallen in einer späteren Version.
POST/api/v1/invoices/{id}/storno— Nachträgliche Storno-Gutschrift zu einer bereits stornierten Rechnung

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
sendToCustomer / send_to_customerbooleanneinfalseStorno-Gutschrift versenden
recipientEmail / recipient_emailstringnein–Empfänger

Antwort: 201 { data: { id, invoiceNumber, invoiceType: "CREDIT_NOTE", creditNoteReason: "CANCELLATION", status: "FINAL", parentInvoiceId, issueDate, currency, netTotal, taxTotal, grossTotal, stornoEmailSent, [warning] } }

  • Spiegelt createRetroactiveStorno für Rechnungen, die bereits CANCELLED sind, aber noch keine Storno-Gutschrift haben. Kein Statuswechsel.
  • 404 unbekannt; 409 Rechnung nicht CANCELLED (Verweis auf …/cancel) oder Storno existiert bereits; 400 kein stornofähiger Beleg (z. B. Proforma/Entwurf).
  • Webhook CREDIT_NOTE_CREATED (+ INVOICE_SENT bei Versand). Audit INVOICE_STORNO_CREATED_VIA_API.
POST/api/v1/invoices/{id}/duplicate— Rechnung als neuen Entwurf duplizieren

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
customerId / customer_idstringnein–Anderer Kunde als das Original
adjustDates / adjust_datesbooleanneintrueRechnungsdatum = heute, Zahlungsziel bleibt in Tagen gleich

Antwort: 201 { data: { id, invoiceNumber, invoiceType: "INVOICE", status: "DRAFT", sourceInvoiceId, customerId, documentCategoryId, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, createdAt } }

  • Fachkern lib/invoice-duplicate.ts. Kopie ist immer eine reguläre Rechnung als Entwurf mit Platzhalternummer; Mengen/Summen werden positiv übernommen (auch bei Kopie einer Gutschrift), Leistungszeitraum wird nicht kopiert.
  • 404 Invoice/Customer not found; 403 plan_limit_reached, wenn das Dokumentenkontingent des Plans erreicht ist (die Kopie zählt wie ein neuer Beleg). Audit INVOICE_DUPLICATED_VIA_API. Kein Webhook (wie im Dashboard).
POST/api/v1/invoices/{id}/convert— Proforma in eine reguläre Rechnung umwandeln

Scope: invoices:write

Antwort: 201 { data: { id, invoiceNumber, invoiceType: "INVOICE", status: "DRAFT", proformaInvoiceId, proformaInvoiceNumber, customerId, documentCategoryId, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, createdAt } }

  • Kein Body. Fachkern convertProformaCore (lib/invoices/proforma.ts, gemeinsam mit Dashboard und KI-Assistent; Schreibvorgang in lib/proforma-conversion.ts). Die Proforma behält Nummer/Belegart/Status und wird über metadata.convertedToInvoiceId verknüpft (umgekehrt metadata.convertedFromProformaId).
  • Einleitungs-/Abschlusstext kommen aus den Rechnungsvorlagen der Firma, nicht von der Proforma. Umwandelbar aus DRAFT, FINAL, SENT, OVERDUE.
  • 404 unbekannt; 400 kein Proforma-Beleg; 403 plan_limit_reached bei erreichtem Dokumentenkontingent; 409 bereits umgewandelt (nennt die Rechnung) oder Status nicht mehr umwandelbar.
  • Audit CONVERT_TO_INVOICE (an der Proforma) und CREATE_FROM_PROFORMA (an der Rechnung). Webhook INVOICE_CREATED.
GET/api/v1/invoices/{id}/payments— Zahlungen einer Rechnung auflisten

Scope: invoices:read

Antwort: { data: { invoice_id, invoice_number, gross_total, total_paid, amount_due, currency, payments: [{ id, amount, payment_date/paymentDate, payment_method/paymentMethod, reference, notes, created_at/createdAt }] } }, Zahlungen nach date absteigend.

  • 404 Invoice not found für fremde/unbekannte Rechnung.
POST/api/v1/invoices/{id}/payments— Zahlung zu einer Rechnung erfassen

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
amountnumberja–Betrag, muss > 0 sein
payment_method / paymentMethodstring (Enum)neinBANK_TRANSFERGroß-/Kleinschreibung und „-“ egalBANK_TRANSFER | CASH | CREDIT_CARD | PAYPAL | OTHER
payment_date / paymentDateISO-DatumneinjetztZahlungsdatum
referencestringnein–z. B. Transaktions-ID
notesstringnein–Freitext

Antwort: 201 { data: { …Zahlung, invoice_id/invoiceId, invoice_number/invoiceNumber, invoice_status/invoiceStatus (klein), total_paid/totalPaid, amount_due/amountDue } }

  • Rechnung wird bei vollständiger Zahlung auf PAID gesetzt inkl. paidAt (= Zahlungsdatum) und löst Webhook INVOICE_PAID aus. Audit PAYMENT_RECORDED_VIA_API.
  • 400 amount fehlt/≤0; 400 ungültige payment_method (mit allowedValues); 400 ungültiges payment_date; 400 (code invoice_status) wenn Rechnung nicht FINAL/SENT/OVERDUE ist; 409 (code amount_exceeds_remaining) über offenem Rest + 0,01 €; 404 Rechnung fremd/unbekannt.
PUT/api/v1/invoices/{id}/payments/{paymentId}— Zahlung ändern

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
amountnumbernein–> 0, Default = bisheriger Betrag
payment_method / paymentMethodstring (Enum)neinbisherige ZahlungsartWie POSTBANK_TRANSFER | CASH | CREDIT_CARD | PAYPAL | OTHER
payment_date / paymentDateISO-Datumneinbisheriges Datum
referencestring | nullnein–
notesstring | nullnein–

Antwort: 200 { data: { …Zahlung, invoice_id/invoiceId, invoice_number/invoiceNumber, invoice_status/invoiceStatus, total_paid/totalPaid, amount_due/amountDue } }

  • Statusnachführung: vollständig bezahlt → PAID + paidAt + Webhook INVOICE_PAID; wieder offen → zurück auf SENT, paidAt geleert. Audit PAYMENT_UPDATED_VIA_API.
  • 404 Payment not found (auch bei fremder Rechnung/Firma); 400 amount ≤0 / ungültige Zahlungsart / ungültiges Datum; 409 (code invoice_cancelled) bei stornierter Rechnung; 409 (code amount_exceeds_remaining) über dem offenen Rest ohne diese Zahlung.
DELETE/api/v1/invoices/{id}/payments/{paymentId}— Zahlung löschen

Scope: invoices:write

Antwort: 200 { data: { id, deleted: true, invoice_id/invoiceId, invoice_number/invoiceNumber, invoice_status/invoiceStatus, total_paid/totalPaid, amount_due/amountDue } }

  • War die Rechnung PAID und ist nach dem Löschen wieder offen, fällt sie auf SENT zurück und verliert paidAt. Auf stornierten Rechnungen bewusst erlaubt (Fehlbuchung entfernen).
  • Audit PAYMENT_DELETED_VIA_API. 404 Payment not found.
GET/api/v1/invoices/{id}/dunning— Mahnstatus und Mahnhistorie lesen

Scope: invoices:read

Antwort: { data: { invoice_id, invoice_number, status, due_date, days_overdue, gross_total, customer, dunning: { is_paused, paused_at, paused_reason, current_level, next_level/nextLevel, max_level_reached, total_reminders, total_fees, total_interest, total_outstanding }, reminders: [...] } }

  • next_level/nextLevel/max_level_reached sind neu; next_level ist die Stufe, die action: "send" als Nächstes verschickt (Stufe 3 bleibt Stufe 3).
POST/api/v1/invoices/{id}/dunning— Mahnwesen pausieren/fortsetzen oder eine Mahnstufe versenden

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
actionstring (Enum)ja–pause | resume | sendpause | resume | send
reasonstringnein–Nur bei pause gespeichert
recipient_email / recipientEmailstringneinE-Mail des KundenNur bei send
custom_reminder_fee / customReminderFeenumberneinCompany.reminderFee1/2/3 je StufeNur bei send, ≥ 0
include_interest / includeInterestbooleanneinfalseNur bei send; Zinssatz aus Company.defaultInterestRate, einfache Verzinsung Restbetrag × Satz × Tage/365

Antwort: pause/resume: 200 { data: { invoice_id, invoice_number, dunning_paused, dunning_paused_at, dunning_paused_reason } }. send: 201 { data: { id, invoice_id/invoiceId, level, sent_at/sentAt, sent_to/sentTo, fee, interest_rate/interestRate, interest_amount/interestAmount, total_amount/totalAmount, days_overdue/daysOverdue, remaining_amount/remainingAmount } }

  • pause/resume: setzt dunningPaused/-At/-Reason, Audit DUNNING_PAUSED_VIA_API / DUNNING_RESUMED_VIA_API.
  • send: verschickt die gebrandete Mahn-E-Mail (Stufe 1 Erinnerung, 2 = 1. Mahnung, 3 = letzte Mahnung), legt eine Reminder-Zeile an, setzt SENT → OVERDUE (Webhook INVOICE_OVERDUE) und löst REMINDER_SENT sowie ab Stufe 2 REMINDER_ESCALATED aus. Audit REMINDER_SENT_VIA_API.
  • 400 ungültige action/Feldtypen; 400 (code invoice_status) wenn Rechnung nicht SENT/OVERDUE; 400 (code no_recipient) ohne Kundenmailadresse; 409 dunning_paused/max_level_reached/already_paid; 502 (code email_failed) bei fehlgeschlagenem Versand (keine Reminder-Zeile).
  • send ist für Gutschriften gesperrt: 400 mit code credit_note_dunning vor Versand, Reminder-Zeile oder Statuswechsel, unabhängig von Betrag oder historischem OVERDUE-Status. Mahnhistorie lesen sowie pause/resume bleiben unverändert.
POST/api/v1/invoices/{id}/correct— Berichtigung nach § 31 Abs. 5 UStDV anlegen (neue Version)

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
change_reason / changeReasonstringja–Mindestens MIN_CHANGE_REASON_LENGTH Zeichen
customer_id / customerIdstringnein–Kundenwechsel
issue_date, due_date, service_period_start, service_period_endISO-Datumnein–
reverse_chargebooleannein–
tax_exemption_reasonstring (Enum)nein–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
tax_exemption_note, tax_country, delivery_country, oss_countrystringnein–
oss_applicablebooleannein–
header_text, notes, footer, order_number, buyer_referencestringnein–
linesLineInput[]nein–Ersetzt die komplette Positionsliste; je Position description (Pflicht), quantity (Default 1), unit_price (Default 0), tax_rate (Default 0), discount (absolut, Default 0), line_type (Default PRODUCT)PRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK

Antwort: 200 { data: { invoiceId, invoiceNumber, versionNumber, changeReason, lazyInitialVersion } }

  • Rechnungsnummer bleibt, neue DocumentVersion (CORRECTION) mit vollständigem Snapshot, Steuerlogik und Summen neu berechnet, PDF wird neu erzeugt und archiviert; bei Bestandsrechnungen ohne lockedAt wird v1 nachträglich erzeugt (lazyInitialVersion: true).
  • Audit DOCUMENT_CORRECTED, Webhook INVOICE_UPDATED. 400 fehlender/zu kurzer change_reason; 400 (code not_locked) — dann PUT verwenden; 400 ungültiges Enum/Datum/Zahl oder leere lines; 404 Rechnung/Kunde unbekannt/fremd.
GET/api/v1/invoices/{id}/versions— Versionshistorie einer Rechnung lesen

Scope: invoices:read

Antwort: { data: { invoiceId, currentVersion, versions: [{ id, versionNumber, changeType, changeReason, hasPdf, createdAt, createdBy }] } }, absteigend nach versionNumber.

  • Gleiche Felder wie die Dashboard-Route /api/documents/invoice/{id}/versions. 404 Invoice not found.
GET/api/v1/invoices/{id}/versions/{version}/pdf— Archiviertes PDF einer bestimmten Version laden

Scope: invoices:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
versionnumber (Pfadparameter)ja–Versionsnummer ≥ 1

Antwort: 200 PDF-Bytes, Content-Disposition inline; filename="{Belegnummer}-v{n}.pdf", Cache-Control private, max-age=3600, immutable.

  • Liefert ausschließlich das archivierte PDF, nie neu gerendert (GoBD). Audit DOCUMENT_VERSION_PDF_DOWNLOADED.
  • 400 Invalid version number; 404 Invoice/Version not found bzw. PDF für diese Version nicht verfügbar/nicht im Storage.
GET/api/v1/invoices/{id}/facturx— Factur-X/ZUGFeRD-XML herunterladen

Scope: invoices:read

Antwort: 200 XML, Content-Type application/xml; charset=utf-8, Content-Disposition attachment.

  • Factur-X/ZUGFeRD 2.3 (EN 16931, CII, Profil BASIC) — identisch zum Dashboard-Download. Entwürfe, Gutschriften (TypeCode 381) und Proformas (325) liefern XML; bereits in Rechnungen umgewandelte Proformas liefern 409 mit Verweis auf die Rechnung.
  • Interne notes bleiben draußen, Steuerhinweis und Schlusstext sind enthalten. Audit EINVOICE_XML_DOWNLOADED_VIA_API. 404 Invoice not found.
Gutschriften6 Endpunkte · invoices:read, invoices:write

Freie und mit einer Rechnung verknüpfte Gutschriften sowie deren Auszahlung. Gutschriften sind Invoice-Zeilen und teilen sich die invoices:read/invoices:write-Scopes.

MethodePfadScopeKurzbeschreibung
GET/api/v1/credit-notesinvoices:readGutschriften auflisten
POST/api/v1/credit-notesinvoices:writeGutschrift anlegen (frei oder verknüpft mit einer Rechnung)
GET/api/v1/credit-notes/{id}invoices:readGutschriftsdetails lesen
PUT/api/v1/credit-notes/{id}invoices:writeGutschrift im Entwurf ändern
POST/api/v1/credit-notes/{id}/executeinvoices:writeAuszahlung ausführen (Gutschrift → PAID)
PUT/api/v1/credit-notes/{id}/executeinvoices:writeAuszahlung freigeben/abbrechen/als fehlgeschlagen markieren
GET/api/v1/credit-notes— Gutschriften auflisten

Scope: invoices:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
limitnumbernein50Seitengröße
offsetnumbernein0Versatz
recipient_id / customer_idstringnein–Filtert nach Empfänger
statusstring (Enum InvoiceStatus)nein–DRAFT | FINAL | SENT | PAID | OVERDUE | CANCELLED
payout_statusstring (Enum)nein–Filtert in der Abfrage (payout.is.status)PENDING | APPROVED | EXECUTED | FAILED | CANCELLED
category_idstring | "uncategorized"nein–

Antwort: { data: CreditNoteListItem[], pagination: { total, limit, offset, hasMore, has_more } }

  • payout_status filtert jetzt in der Datenbankabfrage statt nach der Seitenbildung — total/has_more passen zum Ergebnis.
  • Ungültiges status/payout_status → 400 mit allowedValues (vorher 500 aus Prisma). Sortierung issueDate absteigend.
POST/api/v1/credit-notes— Gutschrift anlegen (frei oder verknüpft mit einer Rechnung)

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
recipient_id / recipientIdstringnein–Pflicht außer parent_invoice_id ist gesetzt
reasonstring (Enum)neinPAYOUTCANCELLATION ist nicht erlaubt (→ 400)PAYOUT | COMMISSION | GOODWILL | RETURN | PRICE_CORRECTION | OTHER
linesLineInput[]nein–Pflicht außer im verknüpften Modus (parent_invoice_id ohne lines)
parent_invoice_id / parentInvoiceIdstringnein–Verknüpfter Modus
partial_lines / partialLinesArray<{line_id/lineId, quantity}>nein–Nur im verknüpften Modus ohne lines; sonst werden alle Positionen gutgeschrieben
issue_date / issueDateISO-Datumneinheute
currencystringneinWährung der Ursprungsrechnung bzw. EUR
reverse_charge / reverseChargebooleannein–
tax_exemption_reason / taxExemptionReasonstring (Enum)nein–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
prices_include_tax / pricesIncludeTaxbooleanneinfalseNur mit eigenen lines: true = Einzelpreise inkl. USt, false = netto; ohne Angabe netto. Eine Gutschrift zur Rechnung (parent_invoice_id ohne lines) übernimmt deren Preisart, eine Angabe dort → 400.
notesstringnein–Wird unverändert gespeichert; erzeugt keinen Text aus dem Grund
footerstring | nullnein–Fehlt/null → notes wird zusätzlich als Schlusstext verwendet; leerer String setzt bewusst keinen
metadataobjectnein–
create_payout / createPayoutbooleanneinfalse
payout_iban, payout_bic, payout_account_holder, payout_bank_name, payout_referencestringnein–Ohne IBAN (weder Body noch Kunde) → 400

Antwort: 201 { data: { id, invoice_number/invoiceNumber, numberIssued, credit_note_reason/creditNoteReason, status, issue_date, recipient, currency, net_total, tax_total, gross_total, prices_include_tax/pricesIncludeTax, lines[], notes, footer, metadata, parent_invoice_id, payout, created_at } }

  • Neue Gutschrift ist immer ein Entwurf mit Platzhalternummer ENTWURF-…; die echte GS-Nummer vergibt erst das Ausstellen (PUT-Statuswechsel, POST …/send oder POST /credit-notes/{id}/execute).
  • Verknüpfter Modus (parent_invoice_id ohne lines) spiegelt createCreditNote: nur für Rechnungen im Status SENT/PAID/OVERDUE (sonst 409); Steuerangaben und Belegkategorie kommen von der Ursprungsrechnung.
  • Ohne reverse_charge und tax_exemption_reason gilt die Steuerbehandlung der Ursprungsrechnung (parent_invoice_id), sonst die Steuer-Vorgabe des Empfängers (defaultTaxExemptionReason samt defaultTaxExemptionNote), sonst NONE.
  • Beträge und Mengen sind negativ gespeichert (wie im Dashboard); payout.amount ist positiv.
  • 404 fremde/fehlende Ursprungsrechnung oder Empfänger. Audit CREDIT_NOTE_CREATED_VIA_API, Webhook CREDIT_NOTE_CREATED.
GET/api/v1/credit-notes/{id}— Gutschriftsdetails lesen

Scope: invoices:read

Antwort: { data: { id, invoice_number/invoiceNumber, numberIssued, credit_note_reason/creditNoteReason, status, issue_date, due_date, recipient (mit Bankdaten), currency, net_total, tax_total, gross_total, prices_include_tax/pricesIncludeTax, reverse_charge, tax_exemption_reason, lines[], notes, footer, metadata, parent_invoice, payout, created_at, updated_at } }

  • 404 bei fremder/fehlender Gutschrift.
PUT/api/v1/credit-notes/{id}— Gutschrift im Entwurf ändern

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
notesstringnein–
footerstring | nullnein–
metadataobjectnein–
reasonstring (Enum)nein–Ohne CANCELLATIONPAYOUT | COMMISSION | GOODWILL | RETURN | PRICE_CORRECTION | OTHER
issue_date / issueDateISO-Datumnein–
currencystringnein–
reverse_charge / reverseChargebooleannein–
tax_exemption_reason / taxExemptionReasonstring (Enum)nein–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
linesLineInput[]nein–Ersetzt die Positionen; Summen über calculateDocumentTotals neu berechnet (negativ)
prices_include_tax / pricesIncludeTaxbooleannein–Nur zusammen mit lines (sonst 400): Preisart der neuen Positionen. Ohne Angabe bleibt die gespeicherte Preisart.

Antwort: { data: { id, invoice_number/invoiceNumber, numberIssued, credit_note_reason/creditNoteReason, status, currency, issue_date, net_total, tax_total, gross_total, prices_include_tax/pricesIncludeTax, lines[], notes, footer, metadata, updated_at } }

  • Nur im Status DRAFT (sonst 400). Positionsaustausch und Summen laufen in einer Transaktion.
  • Audit CREDIT_NOTE_UPDATED_VIA_API.
POST/api/v1/credit-notes/{id}/execute— Auszahlung ausführen (Gutschrift → PAID)

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
transaction_id / transactionIdstringnein–
executed_at / executedAtISO-Datumneinjetzt
notesstringnein–Wird an payout.description angehängt

Antwort: 200 { data: { id, credit_note_id, credit_note_number, status, amount, currency, reference, iban, bic, transaction_id, executed_at, credit_note_status } }

  • Setzt die Auszahlung auf EXECUTED und die Gutschrift auf PAID. Trägt die Gutschrift noch die Platzhalternummer, wird dabei die echte GS-Nummer vergeben (Transaktion); eine Platzhalter-payout.reference wird auf die GS-Nummer gesetzt.
  • Ein Entwurf wird dabei ausgestellt und zählt danach zum Dokumenten-Kontingent: Ist es ausgeschöpft, 403 { error, code: "plan_limit_reached" } — ohne Nummer und ohne Buchung (#696). Bereits ausgestellte Gutschriften sind nicht betroffen.
  • 400 ohne Auszahlung/bereits ausgeführt/abgebrochen; 409 parallel ausgestellt. Audit PAYOUT_EXECUTED_VIA_API, Webhooks PAYOUT_EXECUTED + CREDIT_NOTE_PAID. Fachkern executeCreditNoteCore (lib/credit-notes.ts).
PUT/api/v1/credit-notes/{id}/execute— Auszahlung freigeben/abbrechen/als fehlgeschlagen markieren

Scope: invoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
actionstring (Enum)ja–approve nur aus PENDING, fail nur aus APPROVED, cancel nicht aus EXECUTEDapprove | cancel | fail
failure_reason / failureReasonstringnein–
approved_by / approvedBystringnein"API"

Antwort: { data: { id, credit_note_id, status, amount, approved_at, approved_by, failure_reason } }

  • cancel setzt die Gutschrift auf CANCELLED — ein Entwurf bekommt dabei bewusst keine Belegnummer.
  • Audit PAYOUT_APPROVE|CANCEL|FAIL_VIA_API, Webhooks PAYOUT_APPROVED / PAYOUT_CANCELLED / PAYOUT_FAILED.
Kunden10 Endpunkte · customers:read, customers:write

Kundenstammdaten inkl. Adressen, Bankdaten, SEPA-Mandat, UID-Validierung über VIES und Duplikatsuche.

MethodePfadScopeKurzbeschreibung
GET/api/v1/customerscustomers:readKunden auflisten
POST/api/v1/customerscustomers:writeKunde anlegen
GET/api/v1/customers/{id}customers:readKundendetails lesen
PUT/api/v1/customers/{id}customers:writeKunde ändern
DELETE/api/v1/customers/{id}customers:writeKunde löschen
POST/api/v1/customers/{id}/archivecustomers:writeKunde archivieren
POST/api/v1/customers/{id}/unarchivecustomers:writeKunde aus dem Archiv zurückholen
POST/api/v1/customers/{id}/validate-vatcustomers:writeUID über VIES prüfen und am Kunden speichern
GET/api/v1/customers/duplicatescustomers:readÄhnliche Kunden anhand des Namens finden
GET/api/v1/customers/by-email/{email}customers:readKunde per E-Mail-Adresse finden
GET/api/v1/customers— Kunden auflisten

Scope: customers:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
limitnumbernein501–100
offsetnumbernein0
searchstringnein–Case-insensitiver Treffer in name, email, customerNumber
include_archived / includeArchivedboolean (true|1|yes)nein–Archivierte Kunden zusätzlich anzeigen
archivedbooleannein–true = nur archivierte, false = nur aktive

Antwort: { data: Customer[], pagination }

  • Archivierte Kunden fehlen ohne include_archived/archived jetzt in der Liste (wie in der Dashboard-Kundenliste). Sortierung name aufsteigend.
POST/api/v1/customers— Kunde anlegen

Scope: customers:write

Body-Felder

FeldTypPflichtStandardBeschreibung
namestringja–Nicht leer
customerNumberstringnein–Leer/fehlend = automatische Vergabe (lib/customer-number.ts)
salutation, title, firstName, lastName, departmentstringnein–
email, phone, mobile, websitestringnein–
taxIdstringnein–
taxNumber, registryCourt, registryNumberstringnein–
bmdAccountNumber, bmdRevenueAccountstringnein–Nur Ziffern, max. 9 Stellen
datevIdstringnein–
documentLocalestring | nullnein–Belegsprache für neue Belege; null übernimmt die Firmeneinstellung. Auch document_locale möglich. Bestehende Belege/Wiederholungen bleiben unverändert.de | en
defaultTaxExemptionReasonstring (Enum) | nullnein–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
defaultTaxExemptionNotestringnein–
street, zipCode, city, state, countryCodestringnein–Rechnungsadresse
countrystringneinÖsterreichLeerer Wert ändert nichts
shippingName, shippingCompany, shippingStreet, shippingZipCode, shippingCity, shippingState, shippingCountry, shippingCountryCodestringnein–Lieferadresse
bankAccountHolder, bankName, iban, bicstringnein–
sepaMandateReferencestringnein–
sepaMandateDateISO-Datumnein–
sepaMandateTypestring (Enum)nein–CORE | B2B
sepaMandateStatusstring (Enum)nein–ACTIVE | REVOKED | EXPIRED
sepaSequenceTypestring (Enum)nein–FRST | RCUR | OOFF | FNAL
paymentTermDaysnumbernein–≥ 0
discountPercentnumbernein–0–100
discountDaysnumbernein–≥ 0
notes, categorystringnein–
contacts, billingPrefs, metadataobject | arraynein–null leert das Feld
address, shippingAddressstringnein–Freitext; wird aus den strukturierten Feldern abgeleitet, wenn welche übergeben wurden

Antwort: 201 { data: Customer }

  • Plan-Gate checkCustomerLimit → 403 { code: "plan_limit_reached", limit, current }.
  • Doppelte E-Mail → 409 { customerId } mit dem ältesten vorhandenen Kunden (auch archiviert). Verglichen wird die ganze Adresse ohne Groß-/Kleinschreibung; Zeichen wie _ oder % gelten wörtlich. Auch gleichzeitige POST-Aufrufe mit derselben Adresse ergeben genau einen Kunden. Vergebene customerNumber → 409 { code: "CUSTOMER_NUMBER_TAKEN" }, erschöpfter Nummernraum → 409 { code: "CUSTOMER_NUMBER_UNAVAILABLE" }.
  • taxIdValidated kommt nie aus der Eingabe: nur gesetzt, wenn dieselbe Firma dieselbe UID innerhalb der letzten Stunde erfolgreich über VIES geprüft hat.
  • Audit CUSTOMER_CREATED_VIA_API, Webhook CUSTOMER_CREATED.
GET/api/v1/customers/{id}— Kundendetails lesen

Scope: customers:read

Antwort: { data: Customer & { invoiceCount, recentInvoices: [...] } } (letzte 10 Belege)

  • 404 bei fremdem/fehlendem Kunden.
PUT/api/v1/customers/{id}— Kunde ändern

Scope: customers:write

Body-Felder

FeldTypPflichtStandardBeschreibung
(alle Felder von POST)gemischtnein–Alle optional, PATCH-Semantik: nur mitgeschickte Felder werden geschrieben. customerNumber: ""/null entfernt die Nummer (keine automatische Neuvergabe).

Antwort: { data: Customer }

  • Verhaltensänderung: die Route schrieb bisher nur 6 Felder (name, email, taxId, address, shippingAddress, contacts) und verwarf den Rest — jetzt volle Formularparität.
  • Geänderte E-Mail, die schon ein anderer Kunde trägt (ohne Groß-/Kleinschreibung) → 409 { customerId }; geprüft unter derselben Sperre wie beim Anlegen. Vergebene Kundennummer → 409 { code: "CUSTOMER_NUMBER_TAKEN" }. Geänderte taxId setzt taxIdValidated zurück (bzw. übernimmt eine ≤1h alte VIES-Prüfung).
  • Audit CUSTOMER_UPDATED_VIA_API, Webhook CUSTOMER_UPDATED.
DELETE/api/v1/customers/{id}— Kunde löschen

Scope: customers:write

Antwort: { success: true }

  • Nur ungenutzte Kunden (lib/customer-lifecycle.ts). Jede Verknüpfung → 409 { code: "CUSTOMER_IN_USE" }, Empfehlung: archivieren.
  • Webhook CUSTOMER_DELETED.
POST/api/v1/customers/{id}/archive— Kunde archivieren

Scope: customers:write

Antwort: 200 { data: Customer }

  • Body wird ignoriert. Setzt isArchived=true + archivedAt=now. Audit CUSTOMER_ARCHIVED_VIA_API, Webhook CUSTOMER_UPDATED. 404 bei fremdem Kunden.
POST/api/v1/customers/{id}/unarchive— Kunde aus dem Archiv zurückholen

Scope: customers:write

Antwort: 200 { data: Customer }

  • Body wird ignoriert. Setzt isArchived=false + archivedAt=null. Audit CUSTOMER_UNARCHIVED_VIA_API, Webhook CUSTOMER_UPDATED.
POST/api/v1/customers/{id}/validate-vat— UID über VIES prüfen und am Kunden speichern

Scope: customers:write

Body-Felder

FeldTypPflichtStandardBeschreibung
vatNumber / vat_numberstringnein–
taxId / tax_idstringnein–Fehlen beide, wird die gespeicherte UID geprüft

Antwort: 200 { data: { valid, unavailable, countryCode, vatNumber, requestDate, name, address, errorMessage, customer: Customer } }

  • Ruft VIES (lib/vies.ts), schreibt eine VatValidation-Zeile und speichert taxId (normalisiert), taxIdValidated, taxIdValidatedAt am Kunden.
  • Ohne UID → 400. Audit CUSTOMER_VAT_VALIDATED_VIA_API, Webhook CUSTOMER_UPDATED. Ergebnis gilt eine Stunde als Grundlage für ein nachfolgendes POST/PUT mit derselben UID.
  • unavailable=true bedeutet, dass VIES nicht erreichbar war (Zeitüberschreitung, Wartung, Netzfehler). valid=false sagt dann nichts über die UID aus; der gespeicherte Stand des Kunden bleibt unverändert, sofern er zur geprüften UID gehört.
GET/api/v1/customers/duplicates— Ähnliche Kunden anhand des Namens finden

Scope: customers:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
namestringja–Max. 200 Zeichen; unter 3 Zeichen liefert {data:[]}
exclude_id / excludeIdstringnein–

Antwort: { data: [{ id, name, customerNumber, city, isArchived, similarity }] } (max. 5, absteigend nach similarity)

  • Unscharfer Vergleich ≥ 0,65 (lib/customer-duplicates.ts), archivierte Kunden zählen mit. Reine Leseabfrage.
GET/api/v1/customers/by-email/{email}— Kunde per E-Mail-Adresse finden

Scope: customers:read

Antwort: { data: Customer & { invoiceCount } }

  • Ganze Adresse, ohne Groß-/Kleinschreibung; _ und % gelten wörtlich (keine Platzhalter). 404 wenn kein Treffer. Teilen sich mehrere Kunden die Adresse, kommt der älteste — derselbe wie in der 409-Antwort von POST /customers. Archivierte Kunden werden weiterhin gefunden.
Produkte5 Endpunkte · products:read, products:write

Produkt- und Leistungskatalog für die Vorbelegung von Positionen.

MethodePfadScopeKurzbeschreibung
GET/api/v1/productsproducts:readProdukte auflisten
POST/api/v1/productsproducts:writeProdukt anlegen
GET/api/v1/products/{id}products:readProduktdetails lesen
PUT/api/v1/products/{id}products:writeProdukt ändern
DELETE/api/v1/products/{id}products:writeProdukt deaktivieren (Soft-Delete)
GET/api/v1/products— Produkte auflisten

Scope: products:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
searchstringnein–Trifft name/sku, case-insensitiv
isService / is_serviceboolean ("true"|"false")nein–
include_inactiveboolean ("true"|"false")neintrueBewusste Abweichung: Default true, damit bestehende Integrationen weiter alle Produkte sehen (die Route filterte vorher nie nach isActive)
limitnumbernein50
offsetnumbernein0

Antwort: { data: Product[], pagination }

  • Kein Plan-Gate.
  • include_inactive=false ist der neue Opt-in für nur aktive Produkte.
POST/api/v1/products— Produkt anlegen

Scope: products:write

Body-Felder

FeldTypPflichtStandardBeschreibung
namestringja–
descriptionstringnein–
skustringnein–Eindeutig je Firma → 409 wenn vergeben
isService / is_servicebooleanneinfalse
pricenumberja–Muss ≥ 0 sein
taxRate / tax_ratenumbernein20Muss 0–100 sein
pricesIncludeTax / prices_include_taxbooleanneinfalsetrue = price ist ein Bruttopreis inkl. USt, false = netto. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.
unitstringnein"Stück"
isActive / is_activebooleanneintrue

Antwort: 201 { data: { id, name, description, sku, isService, price, taxRate, pricesIncludeTax, unit, isActive, createdAt, updatedAt } }

  • Audit PRODUCT_CREATED_VIA_API. Antwort enthält seit diesem Umbau zusätzlich updatedAt.
GET/api/v1/products/{id}— Produktdetails lesen

Scope: products:read

Antwort: { data: { id, name, description, sku, isService, price, taxRate, pricesIncludeTax, unit, isActive, createdAt, updatedAt } }

  • 404 wenn nicht gefunden. Deaktivierte Produkte bleiben per ID lesbar.
PUT/api/v1/products/{id}— Produkt ändern

Scope: products:write

Body-Felder

FeldTypPflichtStandardBeschreibung
(alle Felder von POST)gemischtnein–Alle optional/partiell, snake_case-Aliase via pickField. price/taxRate werden wie bei POST validiert.

Antwort: 200 { data: { id, name, description, sku, isService, price, taxRate, pricesIncludeTax, unit, isActive, createdAt, updatedAt } }

  • 404 wenn nicht gefunden, 409 bei SKU-Kollision mit einem anderen Produkt. Audit PRODUCT_UPDATED_VIA_API. Antwort enthält seit diesem Umbau zusätzlich createdAt.
  • pricesIncludeTax ändert nur die Preisart, price wird dabei nicht umgerechnet. Ohne Angabe bleibt die gespeicherte Preisart.
DELETE/api/v1/products/{id}— Produkt deaktivieren (Soft-Delete)

Scope: products:write

Antwort: 200 { success: true }

  • Setzt isActive: false, die Zeile bleibt erhalten. Audit PRODUCT_DEACTIVATED_VIA_API. 404 wenn nicht gefunden.
Angebote9 Endpunkte · quotes:read, quotes:write

Angebote inkl. Versand, Statuswechsel und Umwandlung in Rechnung oder Auftragsbestätigung.

MethodePfadScopeKurzbeschreibung
GET/api/v1/quotesquotes:readAngebote auflisten
POST/api/v1/quotesquotes:writeAngebot anlegen
GET/api/v1/quotes/{id}quotes:readAngebotsdetails lesen
PUT/api/v1/quotes/{id}quotes:writeAngebotsentwurf ändern
DELETE/api/v1/quotes/{id}quotes:writeAngebotsentwurf löschen
POST/api/v1/quotes/{id}/statusquotes:writeAngebot annehmen oder ablehnen
POST/api/v1/quotes/{id}/sendquotes:writeAngebot per E-Mail versenden
GET/api/v1/quotes/{id}/pdfquotes:readAngebots-PDF laden
POST/api/v1/quotes/{id}/convertquotes:write, invoices:writeAngebot in Rechnung oder Auftragsbestätigung umwandeln
GET/api/v1/quotes— Angebote auflisten

Scope: quotes:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–Filtert den gespeicherten StatusDRAFT | SENT | ACCEPTED | REJECTED | EXPIRED | CONVERTED
customer_id / customerIdstringnein–
searchstringnein–Case-insensitiv in Angebotsnummer und Kundenname
from, toISO-Datumnein–Bereich über issueDate
category_idstring | "uncategorized"nein–
limitnumbernein50
offsetnumbernein0

Antwort: { data: Quote[], pagination }

  • Sortierung issueDate desc. EXPIRED entsteht nie in der Datenbank, nur in displayStatus.
POST/api/v1/quotes— Angebot anlegen

Scope: quotes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–
validUntilISO-Datumja–
issueDateISO-Datumneinjetzt
servicePeriodStart, servicePeriodEndISO-Datum | nullnein–
documentCategoryIdstring | nullnein–
reverseChargebooleanneinfalse
pricesIncludeTax / prices_include_taxbooleanneinfalsePreisart: true = Einzelpreise und Rabattbeträge inkl. USt (Bruttopreise, B2C), false = Nettopreise. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.
headerTextstring (HTML)nein–Wird gedruckt
notesstringnein–Intern, nicht auf dem PDF
footerstring (HTML)nein–Wird gedruckt
linesLineInput[]ja–Mindestens 1 Position; discount ist ein Prozentwert (0–100)

Antwort: 201 { data: Quote }

  • Dokumentkategorie-Prüfung (403/400), Plan-Limit checkDocumentLimit (403), Kunde muss zur Firma gehören (404).
  • Angebotsnummer atomar aus dem Nummernkreis AN, Summen über calculateDocumentTotals (Prozent-Rabatte). Audit QUOTE_CREATED_VIA_API. Status immer DRAFT.
  • Bruttopreise (pricesIncludeTax: true): Die USt wird je Steuersatz aus dem Brutto herausgerechnet, die Belegsumme ist die Summe der Brutto-Positionen (3 × 19,99 € = 59,97 €). lineTotal bleibt netto, ebenso alle Exporte und die E-Rechnung.
GET/api/v1/quotes/{id}— Angebotsdetails lesen

Scope: quotes:read

Antwort: { data: Quote }

  • 404 "Quote not found" für unbekannte/fremde IDs.
PUT/api/v1/quotes/{id}— Angebotsentwurf ändern

Scope: quotes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
customerId, documentCategoryId, issueDate, validUntil, servicePeriodStart, servicePeriodEnd, reverseCharge, headerText, notes, footergemischtnein–Alle optional; null bei documentCategoryId/servicePeriod* löscht das Feld
pricesIncludeTax / prices_include_taxbooleannein–Preisart ändern: USt und Summen werden aus den Preisen neu berechnet, die Preise selbst bleiben. Ohne Angabe bleibt die gespeicherte Preisart. Nur true/false, sonst 400.
linesLineInput[]nein–Ersetzt alle Positionen

Antwort: { data: Quote }

  • Nur Entwürfe: DRAFT, lockedAt = null, convertedToInvoiceId = null — sonst 409. Das Dashboard hat keinen eigenen Bearbeiten-Pfad für Angebote, diese Route füllt die Lücke unter denselben Zustandsregeln wie das Löschen.
  • Kopf und Positionen werden bedingt in einer Transaktion geschrieben; eine zwischenzeitliche Änderung ergibt 409. Audit QUOTE_UPDATED_VIA_API.
DELETE/api/v1/quotes/{id}— Angebotsentwurf löschen

Scope: quotes:write

Antwort: { data: { id, deleted: true } }

  • Nur DRAFT, nicht festgeschrieben, nicht umgewandelt (bedingtes deleteMany); sonst 409. Audit QUOTE_DELETED_VIA_API.
POST/api/v1/quotes/{id}/status— Angebot annehmen oder ablehnen

Scope: quotes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
statusstring (Enum)ja–Nur ACCEPTED und REJECTED erlaubtACCEPTED | REJECTED

Antwort: 200 { data: Quote }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403.
  • CONVERTED ist nicht setzbar (400, „In Rechnung entsteht nur durch Umwandeln“); EXPIRED existiert nur als Anzeige.
  • Bereits umgewandeltes Angebot → 409; unzulässiger Wechsel (z. B. ACCEPTED → ACCEPTED) → 409; unbekannter Wert → 400 mit allowedValues. Audit QUOTE_STATUS_CHANGED_VIA_API.
POST/api/v1/quotes/{id}/send— Angebot per E-Mail versenden

Scope: quotes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
recipientEmail / recipient_emailstringneinE-Mail des Kunden
cc, bccstringnein–

Antwort: 200 { data: { quoteId, quoteNumber, status, sentTo, cc, bcc } }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403.
  • PDF über lib/quote-pdf.ts, E-Mail-Typ QUOTE mit Anhang; erst nach erfolgreichem Versand DRAFT → SENT (bedingt).
  • lockDocument("QUOTE") + archiveDistributedPdfAsInitialVersion legen den versendeten Anhang als Version 1 ab. Kein Empfänger → 400; Versandfehler → 500. Audit QUOTE_SENT_VIA_API.
GET/api/v1/quotes/{id}/pdf— Angebots-PDF laden

Scope: quotes:read

Antwort: application/pdf (Binär), Content-Disposition inline, X-PDF-Source: s3-cache | generated.

  • Derselbe Renderer wie Dashboard und E-Mail (loadOrGenerateQuotePdf). Fingerprint-Cache aktiv, Entwürfe werden nie gecacht. Audit PDF_DOWNLOADED_VIA_API. 404 "Quote not found".
POST/api/v1/quotes/{id}/convert— Angebot in Rechnung oder Auftragsbestätigung umwandeln

Scope: quotes:writeinvoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
targetstring (Enum)ja–"invoice" oder "order-confirmation"invoice | order-confirmation

Antwort: 201 { data: { target, quoteId, invoice: {…} } } bzw. { target, quoteId, orderConfirmation } }

  • Benötigt zusätzlich zu quotes:write den Ziel-Scope: invoices:write für target "invoice", order-confirmations:write für target "order-confirmation" (Prüfung per hasScope mit der jeweiligen Konstante im Routen-Code). Fehlender Ziel-Scope → 403 mit requiredScopes.
  • invoice: wie convertQuoteToInvoice — Angebot wird atomar beansprucht (CONVERTED + convertedToInvoiceId), Rechnungsentwurf mit Platzhalternummer, Fälligkeit nach Zahlungsziel, Prozentrabatt → absoluter Rechnungsrabatt, Texte aus den Rechnungsvorlagen (nicht vom Angebot).
  • order-confirmation: wie createOrderConfirmationFromQuote — neue AB mit Positionen/Prozentrabatten des Angebots, notes = Abschlusstext des Angebots; das Angebot bleibt unverändert und weiter umwandelbar.
  • Bereits umgewandelt/abgelehnt → 409. Audit QUOTE_CONVERTED_VIA_API + INVOICE_CREATED_FROM_QUOTE_VIA_API bzw. ORDER_CONFIRMATION_CREATED_VIA_API. Webhook INVOICE_CREATED (nur beim Ziel invoice).
Auftragsbestätigungen9 Endpunkte · order-confirmations:read, order-confirmations:write

Auftragsbestätigungen inkl. Versand, Statuswechsel und Umwandlung in Rechnung oder Auftrag.

MethodePfadScopeKurzbeschreibung
GET/api/v1/order-confirmationsorder-confirmations:readAuftragsbestätigungen auflisten
POST/api/v1/order-confirmationsorder-confirmations:writeAuftragsbestätigung anlegen
GET/api/v1/order-confirmations/{id}order-confirmations:readAuftragsbestätigungsdetails lesen
PUT/api/v1/order-confirmations/{id}order-confirmations:writeAuftragsbestätigung im Entwurf ändern
DELETE/api/v1/order-confirmations/{id}order-confirmations:writeAuftragsbestätigungsentwurf löschen
POST/api/v1/order-confirmations/{id}/statusorder-confirmations:writeStatus einer Auftragsbestätigung setzen
POST/api/v1/order-confirmations/{id}/sendorder-confirmations:writeAuftragsbestätigung per E-Mail versenden
GET/api/v1/order-confirmations/{id}/pdforder-confirmations:readAuftragsbestätigungs-PDF laden
POST/api/v1/order-confirmations/{id}/convertorder-confirmations:write, invoices:writeAuftragsbestätigung in Rechnung oder Auftrag umwandeln
GET/api/v1/order-confirmations— Auftragsbestätigungen auflisten

Scope: order-confirmations:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–DRAFT | SENT | CONFIRMED | IN_PROGRESS | COMPLETED | CANCELLED
customer_id / customerIdstringnein–
searchstringnein–AB-Nummer und Kundenname
from, toISO-Datumnein–Über issueDate
category_idstring | "uncategorized"nein–
limitnumbernein50
offsetnumbernein0

Antwort: { data: OrderConfirmation[], pagination }

  • Sortierung issueDate desc. Ungültiger status → 400 mit allowedValues.
POST/api/v1/order-confirmations— Auftragsbestätigung anlegen

Scope: order-confirmations:write

Body-Felder

FeldTypPflichtStandardBeschreibung
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–
issueDateISO-Datumneinjetzt
deliveryDate, validUntilISO-Datum | nullnein–
documentCategoryIdstring | nullnein–
reverseChargebooleanneinfalse
pricesIncludeTax / prices_include_taxbooleanneinfalsePreisart: true = Einzelpreise und Rabattbeträge inkl. USt (Bruttopreise, B2C), false = Nettopreise. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.
notesstringnein–Wird gedruckt
footer, deliveryTerms, paymentTermsstringnein–
quoteId / quote_idstringnein–Optionaler Angebotsbezug
linesLineInput[]ja–Mindestens 1 Position, discount als Prozentwert

Antwort: 201 { data: OrderConfirmation }

  • Dokumentkategorie-Prüfung, Kunde muss zur Firma gehören (404), AB-Nummer aus dem Nummernkreis AB, Summen über calculateDocumentTotals (Prozent).
  • Prüft das Dokumentenkontingent mit checkDocumentLimit (403), wie im Dashboard. Audit ORDER_CONFIRMATION_CREATED_VIA_API. Status immer DRAFT.
  • Bruttopreise (pricesIncludeTax: true): Die USt wird je Steuersatz aus dem Brutto herausgerechnet, die Belegsumme ist die Summe der Brutto-Positionen (3 × 19,99 € = 59,97 €). lineTotal bleibt netto, ebenso alle Exporte und die E-Rechnung.
GET/api/v1/order-confirmations/{id}— Auftragsbestätigungsdetails lesen

Scope: order-confirmations:read

Antwort: { data: OrderConfirmation }

  • 404 "Order confirmation not found".
PUT/api/v1/order-confirmations/{id}— Auftragsbestätigung im Entwurf ändern

Scope: order-confirmations:write

Body-Felder

FeldTypPflichtStandardBeschreibung
customerId, documentCategoryId, issueDate, deliveryDate, validUntil, reverseCharge, notes, footer, deliveryTerms, paymentTermsgemischtnein–Alle optional; null bei documentCategoryId/deliveryDate/validUntil löscht das Feld
pricesIncludeTax / prices_include_taxbooleannein–Preisart ändern: USt und Summen werden aus den Preisen neu berechnet, die Preise selbst bleiben. Ohne Angabe bleibt die gespeicherte Preisart. Nur true/false, sonst 400.
linesLineInput[]nein–Ersetzt alle Positionen

Antwort: { data: OrderConfirmation }

  • Nur Entwürfe (DRAFT), sonst 409. Audit ORDER_CONFIRMATION_UPDATED_VIA_API.
DELETE/api/v1/order-confirmations/{id}— Auftragsbestätigungsentwurf löschen

Scope: order-confirmations:write

Antwort: { data: { id, deleted: true } }

  • Nur DRAFT, sonst 409. Audit ORDER_CONFIRMATION_DELETED_VIA_API.
POST/api/v1/order-confirmations/{id}/status— Status einer Auftragsbestätigung setzen

Scope: order-confirmations:write

Body-Felder

FeldTypPflichtStandardBeschreibung
statusstring (Enum)ja–Nur erlaubte Übergänge gemäß Dokumentstatus-Regeln; COMPLETED nicht direkt setzbarDRAFT | SENT | CONFIRMED | IN_PROGRESS | COMPLETED | CANCELLED

Antwort: 200 { data: OrderConfirmation }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403 (Stornieren eines Entwurfs bleibt möglich).
  • Bedingter Statuswechsel nur solange der gelesene Status und der fehlende Rechnungsverweis unverändert sind; Konflikt oder bereits umgewandelt → 409. COMPLETED entsteht ausschließlich durch Umwandlung. Audit ORDER_CONFIRMATION_STATUS_CHANGED_VIA_API.
POST/api/v1/order-confirmations/{id}/send— Auftragsbestätigung per E-Mail versenden

Scope: order-confirmations:write

Body-Felder

FeldTypPflichtStandardBeschreibung
recipientEmail / recipient_emailstringneinE-Mail des Kunden
cc, bccstringnein–

Antwort: 200 { data: { orderConfirmationId, confirmationNumber, status, sentTo, cc, bcc } }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403.
  • PDF über lib/order-confirmation-pdf.ts, E-Mail-Typ ORDER_CONFIRMATION; DRAFT → SENT erst nach erfolgreichem Versand (bedingt).
  • lockDocument("ORDER_CONFIRMATION") + Archivierung des versendeten Anhangs als Version 1. Kein Empfänger → 400; Versandfehler → 500. Audit ORDER_CONFIRMATION_SENT_VIA_API.
GET/api/v1/order-confirmations/{id}/pdf— Auftragsbestätigungs-PDF laden

Scope: order-confirmations:read

Antwort: application/pdf (Binär), Content-Disposition inline, X-PDF-Source.

  • Derselbe Renderer wie Dashboard/E-Mail. Fingerprint-Cache, Entwürfe ungecacht. Audit PDF_DOWNLOADED_VIA_API.
POST/api/v1/order-confirmations/{id}/convert— Auftragsbestätigung in Rechnung oder Auftrag umwandeln

Scope: order-confirmations:writeinvoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
targetstring (Enum)ja–"invoice" oder "order"invoice | order

Antwort: 201 { data: { target, orderConfirmationId, invoice: {…} } } bzw. { target, orderConfirmationId, order: {…} } }

  • Benötigt zusätzlich zu order-confirmations:write den Ziel-Scope: invoices:write für target "invoice", orders:write für target "order" (per hasScope-Prüfung im Routen-Code). Fehlender Ziel-Scope → 403.
  • invoice: wie convertOrderConfirmationToInvoice — Dokumentkategorie, mind. eine Position, Plan-Limit checkDocumentLimit (403); die AB wird atomar beansprucht (Status → COMPLETED), Rechnungsentwurf mit Platzhalternummer, Prozentrabatt → absoluter Rechnungsrabatt, notes = „Erstellt aus Auftragsbestätigung <Nr.>“.
  • order: über den gemeinsamen Auftragskern createOrderFromOrderConfirmation (lib/orders.ts) — Auftrag mit Nummer AU, Positionen/Prozentrabatten der AB, Verweise auf AB und Ursprungsangebot; die AB bleibt unverändert.
  • Bereits umgewandelt → 409. Audit ORDER_CONFIRMATION_CONVERTED_VIA_API + INVOICE_CREATED_FROM_ORDER_CONFIRMATION_VIA_API. Webhook INVOICE_CREATED nach Commit (nur beim Ziel invoice).
Lieferscheine9 Endpunkte · delivery-notes:read, delivery-notes:write

Lieferscheine ohne Preisangaben inkl. Versand und Umwandlung in eine Rechnung mit nachträglicher Preisangabe.

MethodePfadScopeKurzbeschreibung
GET/api/v1/delivery-notesdelivery-notes:readLieferscheine auflisten
POST/api/v1/delivery-notesdelivery-notes:writeLieferschein anlegen
GET/api/v1/delivery-notes/{id}delivery-notes:readLieferscheindetails lesen
PUT/api/v1/delivery-notes/{id}delivery-notes:writeLieferscheinentwurf ändern
DELETE/api/v1/delivery-notes/{id}delivery-notes:writeLieferscheinentwurf löschen
POST/api/v1/delivery-notes/{id}/statusdelivery-notes:writeStatus eines Lieferscheins setzen
POST/api/v1/delivery-notes/{id}/senddelivery-notes:writeLieferschein per E-Mail versenden
GET/api/v1/delivery-notes/{id}/pdfdelivery-notes:readLieferschein-PDF laden
POST/api/v1/delivery-notes/{id}/convertdelivery-notes:write, invoices:writeLieferschein in eine Rechnung umwandeln (Preise ergänzen)
GET/api/v1/delivery-notes— Lieferscheine auflisten

Scope: delivery-notes:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–DRAFT | SENT | DELIVERED | CONVERTED
customer_id / customerIdstringnein–
searchstringnein–Lieferscheinnummer oder Kundenname
from, toISO-Datumnein–issueDate ≥/≤
category_idstring | "uncategorized"nein–
limitnumbernein50
offsetnumbernein0

Antwort: 200 { data: DeliveryNote[], pagination }

  • Sortierung issueDate absteigend. Ungültiger status → 400 mit allowedValues.
POST/api/v1/delivery-notes— Lieferschein anlegen

Scope: delivery-notes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–
linesLineInput[]ja–Mindestens 1; nur Beschreibung/Menge/Einheit, keine Preise
lines[].descriptionstringnein–Pflicht außer wenn productId gesetzt ist
lines[].quantitynumbernein1
lines[].unitstringneinProdukteinheit bzw. "Stk"
lines[].productIdstringnein–Füllt Bezeichnung/Einheit wie der Produktwähler im Dashboard
deliveryDateISO-Datumnein–
shippingAddressstringnein–
notesstringnein–
documentCategoryIdstring | nullnein–
orderIdstring | nullnein–Verknüpft mit einem Auftrag

Antwort: 201 { data: DeliveryNote }

  • Vergibt die Nummer LS-{JAHR}-{0001}. Prüft das Dokumentenkontingent des Plans (→ 403 plan_no_access).
  • Kunde/Auftrag müssen zur Firma gehören (→ 404), unbekannte productId → 400. Audit DELIVERY_NOTE_CREATED_VIA_API. Status startet als DRAFT.
GET/api/v1/delivery-notes/{id}— Lieferscheindetails lesen

Scope: delivery-notes:read

Antwort: 200 { data: DeliveryNote }

  • 404, wenn der Lieferschein nicht zur Firma gehört.
PUT/api/v1/delivery-notes/{id}— Lieferscheinentwurf ändern

Scope: delivery-notes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
customerId, documentCategoryId, deliveryDate, shippingAddress, notes, orderIdgemischtnein–Alle optional; null bei documentCategoryId/deliveryDate/orderId löscht das Feld
linesLineInput[]nein–Ersetzt alle Positionen, nummeriert sie neu ab 1

Antwort: 200 { data: DeliveryNote }

  • Nur Entwürfe (sonst 409). Das Dashboard hat keine Bearbeitungsseite für Lieferscheine — die Regel folgt der Löschregel. Audit DELIVERY_NOTE_UPDATED_VIA_API.
DELETE/api/v1/delivery-notes/{id}— Lieferscheinentwurf löschen

Scope: delivery-notes:write

Antwort: 200 { data: { id, deleted: true } }

  • Nur Entwürfe (sonst 409). Audit DELIVERY_NOTE_DELETED_VIA_API.
POST/api/v1/delivery-notes/{id}/status— Status eines Lieferscheins setzen

Scope: delivery-notes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
statusstring (Enum)ja–CONVERTED ist nicht manuell setzbar → 400 mit Verweis auf /convertDRAFT | SENT | DELIVERED

Antwort: 200 { data: DeliveryNote }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403.
  • Audit DELIVERY_NOTE_STATUS_CHANGED_VIA_API mit { status: { old, new } }.
POST/api/v1/delivery-notes/{id}/send— Lieferschein per E-Mail versenden

Scope: delivery-notes:write

Body-Felder

FeldTypPflichtStandardBeschreibung
recipientEmailstringneinE-Mail des Kunden
cc, bccstringnein–

Antwort: 200 { data: { deliveryNoteId, status, sentTo, cc, bcc, sentAt } }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403.
  • PDF-Anhang (EmailType.DELIVERY), legt eine SentEmail-Zeile an. Danach DRAFT → SENT (nur solange nicht umgewandelt), lockDocument + archiveDistributedPdfAsInitialVersion legt v1 an.
  • Weder Kunden-E-Mail noch recipientEmail → 400. Fehlgeschlagener Versand → 500, kein Statuswechsel.
GET/api/v1/delivery-notes/{id}/pdf— Lieferschein-PDF laden

Scope: delivery-notes:read

Antwort: 200 Binärdaten, Content-Type application/pdf, X-PDF-Source: s3-cache|generated.

  • Gleicher Renderer wie im Dashboard (lib/delivery-note-pdf.ts) inkl. Fingerprint-Cache; Entwürfe nie gecacht. Audit PDF_DOWNLOADED_VIA_API nur bei Treffer.
POST/api/v1/delivery-notes/{id}/convert— Lieferschein in eine Rechnung umwandeln (Preise ergänzen)

Scope: delivery-notes:writeinvoices:write

Body-Felder

FeldTypPflichtStandardBeschreibung
linesPricingArray<{position, unitPrice, taxRate}>ja–Mindestens 1; position bezieht sich auf DeliveryNoteLine.position
dueDateISO-DatumneinZahlungsziel des Kunden, sonst der Firma, sonst 14 Tage
pricesIncludeTaxbooleanneinfalsetrue = unitPrice in linesPricing sind Bruttopreise (inkl. USt); die Rechnung übernimmt diese Preisart

Antwort: 201 { data: { deliveryNoteId, invoiceId, invoice: { id, invoiceNumber, status, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, customer, lines[] } } }

  • Beansprucht den Lieferschein atomar (20s Budget): Status → CONVERTED, convertedToInvoiceId gesetzt; eine parallele Umwandlung erhält 409.
  • Rechnung entsteht als Entwurf mit Platzhalternummer ENTWURF-…; Texte aus den Rechnungsvorlagen, notes = „Erstellt aus Lieferschein {Nummer}“. Positionen ohne passendes linesPricing bekommen unitPrice 0 / taxRate 20.
  • Zwei Audit-Zeilen: DELIVERY_NOTE_CONVERTED_VIA_API (DeliveryNote) und INVOICE_CREATED_FROM_DELIVERY_NOTE_VIA_API (Invoice).
Aufträge8 Endpunkte · orders:read, orders:write

Langlaufende Aufträge mit Budget, Teillieferungen und Teilrechnungen.

MethodePfadScopeKurzbeschreibung
GET/api/v1/ordersorders:readAufträge auflisten
POST/api/v1/ordersorders:writeAuftrag anlegen
GET/api/v1/orders/{id}orders:readAuftragsdetails inkl. Statistiken lesen
PUT/api/v1/orders/{id}orders:writeAuftrag ändern
DELETE/api/v1/orders/{id}orders:writeAuftragsentwurf löschen
POST/api/v1/orders/{id}/statusorders:writeStatus eines Auftrags setzen
PUT/api/v1/orders/{id}/lines/{lineId}orders:writeGelieferte oder abgerechnete Menge einer Auftragsposition pflegen
GET/api/v1/orders/{id}/pdforders:readAuftrags-PDF laden
GET/api/v1/orders— Aufträge auflisten

Scope: orders:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–DRAFT | ACTIVE | ON_HOLD | COMPLETED | CANCELLED
customer_id / customerIdstringnein–
searchstringnein–Auftragsnummer, Bezeichnung oder Kundenname
category_idstring | "uncategorized"nein–
limitnumbernein50
offsetnumbernein0

Antwort: 200 { data: Order[], pagination }

  • Sortierung createdAt absteigend.
POST/api/v1/orders— Auftrag anlegen

Scope: orders:write

Body-Felder

FeldTypPflichtStandardBeschreibung
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–
namestringja–Auftragsbezeichnung
linesLineInput[]ja–Mindestens 1
lines[].descriptionstringnein–Pflicht außer mit productId
lines[].quantitynumbernein1
lines[].unitstringneinProdukteinheit bzw. "Stk"
lines[].unitPricenumberneinProduktpreis bzw. 0
lines[].taxRatenumberneinProduktsteuersatz bzw. 20
lines[].discountnumbernein0Prozent, 0–100
lines[].lineTypestring (Enum)neinPRODUCTPRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK
lines[].productIdstringnein–
description, notesstringnein–
documentCategoryIdstring | nullnein–
startDate, endDateISO-Datum | nullnein–
quoteId, orderConfirmationIdstringnein–Müssen zur Firma gehören (→ 404)
pricesIncludeTax / prices_include_taxbooleanneinfalsePreisart: true = Einzelpreise und Rabattbeträge inkl. USt (Bruttopreise, B2C), false = Nettopreise. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.

Antwort: 201 { data: Order }

  • Vergibt die Nummer AU-{JAHR}-{0001}. totalBudget wird aus den Positionen über calculateDocumentTotals (Modus percent) als Nettosumme berechnet — Abzugspositionen mindern das Budget.
  • Mit productId und ohne unitPrice wird der Artikelpreis in die Preisart des Auftrags umgerechnet, wenn der Artikel eine andere hat (Steuersatz des Artikels, auf Cent).
  • Prüft das Dokumentenkontingent mit checkDocumentLimit, wie im Dashboard. Audit ORDER_CREATED_VIA_API. Status startet als DRAFT, deliveredQty/invoicedQty bei 0.
GET/api/v1/orders/{id}— Auftragsdetails inkl. Statistiken lesen

Scope: orders:read

Antwort: 200 { data: Order & { stats: OrderStats, invoices: [...], deliveryNotes: [...] } }

  • stats entspricht getOrderStats der Detailseite: Abzugs-, Text- und Zwischensummenpositionen zählen nicht in die Mengenfortschritte.
PUT/api/v1/orders/{id}— Auftrag ändern

Scope: orders:write

Body-Felder

FeldTypPflichtStandardBeschreibung
name, description, notesstringnein–
documentCategoryIdstring | nullnein–
startDate, endDateISO-Datum | nullnein–
pricesIncludeTax / prices_include_taxbooleannein–Preisart ändern: USt und Summen werden aus den Preisen neu berechnet, die Preise selbst bleiben. Ohne Angabe bleibt die gespeicherte Preisart. Nur true/false, sonst 400.
linesLineInput[]nein–Ersetzt alle Positionen (deliveredQty/invoicedQty starten wieder bei 0); totalBudget wird neu berechnet

Antwort: 200 { data: Order }

  • Nur DRAFT und ACTIVE (sonst 409). Kunde ist nicht änderbar. Audit ORDER_UPDATED_VIA_API.
DELETE/api/v1/orders/{id}— Auftragsentwurf löschen

Scope: orders:write

Antwort: 200 { data: { id, deleted: true } }

  • Nur Entwürfe (sonst 409). Audit ORDER_DELETED_VIA_API.
POST/api/v1/orders/{id}/status— Status eines Auftrags setzen

Scope: orders:write

Body-Felder

FeldTypPflichtStandardBeschreibung
statusstring (Enum)ja–DRAFT | ACTIVE | ON_HOLD | COMPLETED | CANCELLED

Antwort: 200 { data: Order }

  • Verlässt der Beleg dabei den Entwurf, zählt er aufs Dokumentenkontingent des Plans: bei erschöpftem Kontingent 403 (Stornieren eines Entwurfs bleibt möglich).
  • Verlässt der Auftrag zum ersten Mal DRAFT, wird er festgeschrieben (lockDocument: lockedAt + v1-Snapshot). Idempotent — Re-Aktivierung aus ON_HOLD/COMPLETED erzeugt keine zweite v1.
  • Audit ORDER_STATUS_CHANGED_VIA_API.
PUT/api/v1/orders/{id}/lines/{lineId}— Gelieferte oder abgerechnete Menge einer Auftragsposition pflegen

Scope: orders:write

Body-Felder

FeldTypPflichtStandardBeschreibung
deliveredQuantitynumbernein–≥ 0
invoicedQuantitynumbernein–≥ 0; mindestens eines von beiden ist Pflicht

Antwort: 200 { data: { id, orderId, position, description, quantity, unit, unitPrice, taxRate, discount, discountMode: "percent", lineType, lineTotal, deliveredQty, invoicedQty } }

  • Entspricht updateOrderLineDeliveredQty/updateOrderLineInvoicedQty der Detailseite. Position muss zu diesem Auftrag und zur Firma gehören (sonst 404). Keine Menge gesendet → 400.
  • Audit ORDER_LINE_QUANTITY_UPDATED_VIA_API (auf dem Auftrag, mit lineId).
GET/api/v1/orders/{id}/pdf— Auftrags-PDF laden

Scope: orders:read

Antwort: 200 Binärdaten, Content-Type application/pdf, X-PDF-Source.

  • Gleicher Renderer wie im Dashboard (lib/order-pdf.ts) inkl. Fingerprint-Cache; zeigt Bestellt-/Geliefert-/Abgerechnet-Mengen und Fortschritt. Audit PDF_DOWNLOADED_VIA_API nur bei Treffer.
Wiederkehrende Rechnungen10 Endpunkte · recurring:read, recurring:write

Zeitpläne für automatisch generierte Rechnungen (Abos, Wartungsverträge, Mieten).

MethodePfadScopeKurzbeschreibung
GET/api/v1/recurring-schedulesrecurring:readZeitpläne auflisten
POST/api/v1/recurring-schedulesrecurring:writeZeitplan für wiederkehrende Rechnungen anlegen
GET/api/v1/recurring-schedules/{id}recurring:readZeitplandetails inkl. erzeugter Rechnungen lesen
PUT/api/v1/recurring-schedules/{id}recurring:writeZeitplan ändern
DELETE/api/v1/recurring-schedules/{id}recurring:writeZeitplan löschen
POST/api/v1/recurring-schedules/{id}/statusrecurring:writeStatus eines Zeitplans setzen
POST/api/v1/recurring-schedules/{id}/archiverecurring:writeZeitplan archivieren
POST/api/v1/recurring-schedules/{id}/restorerecurring:writeArchivierten Zeitplan wiederherstellen
POST/api/v1/recurring-schedules/{id}/generaterecurring:writeRechnung aus dem Zeitplan sofort erzeugen
POST/api/v1/recurring-schedules/{id}/recalculaterecurring:writeNächstes Generierungsdatum neu berechnen
GET/api/v1/recurring-schedules— Zeitpläne auflisten

Scope: recurring:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–ACTIVE | PAUSED | ENDED | ARCHIVED
customer_idstringnein–
include_archivedbooleanneinfalse
limitnumbernein50
offsetnumbernein0

Antwort: { data: Schedule[], meta: { total, limit, offset, hasMore } }

  • Ohne status und ohne include_archived=true werden archivierte Pläne ausgeblendet. Sortierung nextGenerationDate aufsteigend, dann createdAt absteigend.
POST/api/v1/recurring-schedules— Zeitplan für wiederkehrende Rechnungen anlegen

Scope: recurring:write

Plan-Feature: recurringInvoices

Body-Felder

FeldTypPflichtStandardBeschreibung
documentLocale / document_localestring (Enum)nein–Nur bei Neuanlage: ausdrückliche Belegsprache vor Kunden-/Firmenvorgabe, zuletzt Deutsch. Folgebelege behalten die Quellsprache. Die Antwort enthält documentLocale und documentTextVersion; Bearbeitung verändert das gespeicherte Profil nicht.de | en
customerIdstringja–
frequencystring (Enum)ja–WEEKLY | BIWEEKLY | MONTHLY | QUARTERLY | SEMIANNUALLY | ANNUALLY
startDateISO-Datumja–
linesLineInput[]ja–Mindestens 1; je Position description (Pflicht), quantity, unitPrice, taxRate (Pflicht), discount (absolut), lineType, articleNumber
namestringnein„{Kunde} - {Frequenz} - {Startdatum}“
descriptionstringnein–
intervalMultipliernumbernein11–99
dayOfMonthnumbernein–1–31
dayOfWeeknumbernein–0–6, wird gespeichert, verschiebt das Datum nicht
useLastDayOfMonthbooleanneinfalseSetzt dayOfMonth auf null
endDateISO-Datumnein–
maxOccurrencesnumbernein–≥ 1
createAsDraftbooleanneinfalse
autoSendEmailbooleanneintrue
notifyOnCreatebooleanneinfalse
markAsPaidbooleanneinfalse
emailCc, emailBccstringnein–Kommagetrennte Adressen, werden normalisiert
taxExemptionReasonstring (Enum)neinNONENONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
taxExemptionNotestringnein–
taxCountrystring (ISO)neinaus den Steuersätzen erkanntNur EU-Codes (AT, DE, …). Ein anderer Wert wird nicht übernommen: Dann gilt das aus den Steuersätzen erkannte Land, sonst keines. Die Antwort enthält den gespeicherten Wert.
headerText, notes, footerstringnein–
paymentTermDaysnumbernein–0–365
discountPercentnumbernein–0–100
discountDaysnumbernein–0–365
orderNumber, buyerReference, externalIdstringnein–
totalDiscountPercentnumbernein–0–100
isOSS, showServiceDateNoticebooleannein–
documentCategoryIdstring | nullnein–
pricesIncludeTax / prices_include_taxbooleanneinfalsePreisart: true = Einzelpreise und Rabattbeträge inkl. USt (Bruttopreise, B2C), false = Nettopreise. Ohne Angabe netto — auch wenn die Firma Bruttopreise vorgibt. Nur true/false, sonst 400.

Antwort: 201 { data: Schedule }

  • Plan-Gate recurringInvoices (403). Prüft Kunde (404) und Dokumentkategorie (400). nextGenerationDate = Startdatum (falls Zukunft), sonst aus dem Rhythmus berechnet.
  • Audit RECURRING_SCHEDULE_CREATED_VIA_API.
GET/api/v1/recurring-schedules/{id}— Zeitplandetails inkl. erzeugter Rechnungen lesen

Scope: recurring:read

Antwort: { data: Schedule & { generatedInvoices: [{ id, invoiceNumber, status, issueDate, grossTotal }] } }

  • nextGenerationDate und generatedCount sind Teil von Schedule.
PUT/api/v1/recurring-schedules/{id}— Zeitplan ändern

Scope: recurring:write

Body-Felder

FeldTypPflichtStandardBeschreibung
(alle Felder von POST)gemischtnein–Alle optional, nur gesendete Felder ändern sich. null löscht endDate, maxOccurrences, dayOfMonth, dayOfWeek, paymentTermDays, discountDays, discountPercent, totalDiscountPercent. status wird hier nicht akzeptiert.

Antwort: { data: Schedule }

  • Ändert sich der Rhythmus (frequency, intervalMultiplier, dayOfMonth, dayOfWeek, useLastDayOfMonth, startDate), wird nextGenerationDate neu berechnet. Kundenwechsel wird geprüft (404), Kategorie validiert (400).
  • pricesIncludeTax ohne Angabe: Die gespeicherte Preisart bleibt. Erzeugte Rechnungen übernehmen die Preisart des Zeitplans.
  • taxCountry gilt wie beim Anlegen nur mit einem EU-Code; ein anderer Wert wird auf das aus den Steuersätzen erkannte Land zurückgeführt — ohne mitgesendete lines aus den gespeicherten Positionen des Zeitplans. Die Antwort enthält den gespeicherten Wert, die Korrektur ist dort also sichtbar.
  • Audit RECURRING_SCHEDULE_UPDATED_VIA_API.
DELETE/api/v1/recurring-schedules/{id}— Zeitplan löschen

Scope: recurring:write

Antwort: { data: { id, deleted: true } }

  • Nur wenn noch keine Rechnung erzeugt wurde; sonst 409 mit archiveEndpoint. Audit RECURRING_SCHEDULE_DELETED_VIA_API.
POST/api/v1/recurring-schedules/{id}/status— Status eines Zeitplans setzen

Scope: recurring:write

Body-Felder

FeldTypPflichtStandardBeschreibung
statusstring (Enum)ja–ACTIVE | PAUSED | ENDED

Antwort: 200 { data: Schedule }

  • ENDED → ACTIVE ist gesperrt (409). Beim Aktivieren gewinnt ein zukünftiges Startdatum, aus PAUSED wird ab heute neu gerechnet; ENDED löscht nextGenerationDate. ARCHIVED läuft über /archive.
  • Audit RECURRING_SCHEDULE_STATUS_CHANGED_VIA_API.
POST/api/v1/recurring-schedules/{id}/archive— Zeitplan archivieren

Scope: recurring:write

Antwort: 200 { data: Schedule }

  • Setzt ARCHIVED und löscht nextGenerationDate. Bereits archiviert → 409. Audit RECURRING_SCHEDULE_ARCHIVED_VIA_API.
POST/api/v1/recurring-schedules/{id}/restore— Archivierten Zeitplan wiederherstellen

Scope: recurring:write

Antwort: 200 { data: Schedule }

  • Nur aus ARCHIVED (sonst 409), immer nach PAUSED; nextGenerationDate bleibt leer, bis aktiviert wird. Audit RECURRING_SCHEDULE_RESTORED_VIA_API.
POST/api/v1/recurring-schedules/{id}/generate— Rechnung aus dem Zeitplan sofort erzeugen

Scope: recurring:write

Plan-Feature: recurringInvoices

Body-Felder

FeldTypPflichtStandardBeschreibung
forcebooleanneinfalseErzeugt auch, wenn das Startdatum noch in der Zukunft liegt

Antwort: 201 { data: { id, invoiceNumber, status, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, customerId }, schedule: { id, status, generatedCount, lastGeneratedAt, nextGenerationDate }, warnings?: string[] }

  • Entsteht die Rechnung nicht als Entwurf, zählt sie sofort aufs Dokumentenkontingent: bei erschöpftem Kontingent 403 plan_limit_reached, ohne Nummer zu verbrauchen.
  • Plan-Gate recurringInvoices (403). Erzeugt über denselben Fachkern wie das Dashboard: Nummernvergabe (Entwürfe ENTWURF-…), Status je nach createAsDraft/autoSendEmail/markAsPaid, E-Mail-Versand mit PDF bei autoSendEmail (inkl. emailCc/emailBcc; scheitert der Versand, steht die Meldung in warnings), In-App-Benachrichtigung RECURRING_GENERATED bei notifyOnCreate.
  • Erreicht der Plan maxOccurrences, wird er auf ENDED gesetzt. 409 bei: Plan nicht ACTIVE (NOT_ACTIVE), Startdatum in der Zukunft ohne force (BEFORE_START_DATE), Maximum erreicht (MAX_OCCURRENCES), Plan ohne gültige Positionen.
  • Audit RECURRING_SCHEDULE_GENERATED_VIA_API.
POST/api/v1/recurring-schedules/{id}/recalculate— Nächstes Generierungsdatum neu berechnen

Scope: recurring:write

Antwort: 200 { data: Schedule }

  • Setzt nextGenerationDate neu (zukünftiges Startdatum gewinnt, sonst ab heute). ENDED/ARCHIVED → 409. Audit RECURRING_SCHEDULE_RECALCULATED_VIA_API.
Belege (Dokumentenablage)10 Endpunkte · documents:read, documents:write

Zentrale Dokumentenablage für beliebige Belege inkl. Direkt-Upload über S3.

MethodePfadScopeKurzbeschreibung
GET/api/v1/documentsdocuments:readBelege auflisten
POST/api/v1/documentsdocuments:writeBeleg direkt hochladen (Base64)
POST/api/v1/documents/upload-urldocuments:writePresigned S3-Upload-URL anfordern
POST/api/v1/documents/confirmdocuments:writeDirekt-Upload abschließen und Beleg anlegen
GET/api/v1/documents/{id}documents:readBelegmetadaten lesen
GET/api/v1/documents/{id}/downloaddocuments:readBeleginhalt herunterladen
PUT/api/v1/documents/{id}documents:writeBelegmetadaten ändern
POST/api/v1/documents/{id}/archivedocuments:writeBeleg archivieren
POST/api/v1/documents/{id}/unarchivedocuments:writeBeleg aus dem Archiv zurückholen
DELETE/api/v1/documents/{id}documents:writeBeleg löschen
GET/api/v1/documents— Belege auflisten

Scope: documents:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
typestring (Enum)nein–INVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
archivedstring ("true"|"false"|"all")neinfalse
invoice_id, customer_idstringnein–
category_idstring | "uncategorized"nein–
searchstringnein–Name, Beschreibung, Tag
limitnumbernein50
offsetnumbernein0

Antwort: { data: Document[], meta: { total, limit, offset, hasMore } }

  • Sortierung createdAt absteigend. Dateiinhalte werden nie mitgeliefert.
POST/api/v1/documents— Beleg direkt hochladen (Base64)

Scope: documents:write

Body-Felder

FeldTypPflichtStandardBeschreibung
namestringja–
mimeTypestringja–Allow-List: PDF, PNG, JPEG, GIF, WebP, DOC(X), XLS(X), TXT, CSV
contentstring (Base64)ja–Mit oder ohne data:-Präfix; max. 20 MB
typestring (Enum)neinOTHERINVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
descriptionstringnein–
tagsstring[]nein–
invoiceId, customerId, documentCategoryIdstringnein–

Antwort: 201 { data: Document }

  • 400 FILE_TOO_LARGE über 20 MB, 400 MIME_NOT_ALLOWED außerhalb der Allow-List, 403 STORAGE_LIMIT bei erschöpftem Speicherkontingent des Plans.
  • Ablage: S3 wenn STORAGE_PROVIDER=s3, sonst Base64 in der Datenbank (502 STORAGE_FAILED bei S3-Fehler). Rechnung/Kunde/Kategorie werden geprüft (404/400). Audit DOCUMENT_CREATED_VIA_API.
POST/api/v1/documents/upload-url— Presigned S3-Upload-URL anfordern

Scope: documents:write

Body-Felder

FeldTypPflichtStandardBeschreibung
fileName / namestringja–
mimeTypestringja–
sizenumberja–Bytes > 0, max. 100 MB
typestring (Enum)neinOTHERINVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER

Antwort: 200 { data: { uploadUrl, key, method: "PUT", headers: { "Content-Type" }, expiresAt } }

  • 403 STORAGE_LIMIT, wenn die Datei das Speicherkontingent des Plans überschreiten würde.
  • Nur mit S3 als Ablage, sonst 400 S3_REQUIRED (Hinweis auf POST /documents). URL 5 Minuten gültig. Legt noch keinen Beleg an.
POST/api/v1/documents/confirm— Direkt-Upload abschließen und Beleg anlegen

Scope: documents:write

Body-Felder

FeldTypPflichtStandardBeschreibung
keystringja–Aus /upload-url, muss mit der Firmen-Id beginnen (sonst 400 INVALID_STORAGE_KEY)
namestringja–
mimeTypestringja–
sizenumberja–
typestring (Enum)nein–INVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
descriptionstringnein–
tagsstring[]nein–
invoiceId, customerId, documentCategoryIdstringnein–

Antwort: 201 { data: Document }

  • Fürs Speicherkontingent zählt die Größe des Objekts in S3, nicht die size-Angabe (diese wird überschrieben). Über dem Kontingent → 403 STORAGE_LIMIT, das hochgeladene Objekt wird gelöscht; ohne hochgeladenes Objekt → 400 UPLOAD_NOT_FOUND.
  • Entspricht confirmDirectUpload im Dashboard. Ohne S3 → 400 S3_REQUIRED. Abweichung von der ursprünglichen Planung: kein {id} im Pfad, da vor der Bestätigung noch kein Beleg existiert.
  • Audit DOCUMENT_CREATED_VIA_API.
GET/api/v1/documents/{id}— Belegmetadaten lesen

Scope: documents:read

Antwort: { data: Document }

  • Nur Metadaten.
GET/api/v1/documents/{id}/download— Beleginhalt herunterladen

Scope: documents:read

Antwort: S3: { data: { id, name, mimeType, url, expiresAt } }. Lokal: Binärdaten mit Content-Disposition attachment.

  • Vorsignierte S3-URL, 1 Stunde gültig. Fehlende Daten → 404 (DATA_MISSING/STORAGE_FAILED).
PUT/api/v1/documents/{id}— Belegmetadaten ändern

Scope: documents:write

Body-Felder

FeldTypPflichtStandardBeschreibung
namestringnein–Nicht leer
descriptionstringnein–
typestring (Enum)nein–INVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
tagsstring[]nein–
invoiceId, customerId, documentCategoryIdstring | nullnein–

Antwort: { data: Document }

  • Nur Metadaten, die Datei bleibt unverändert. Bezüge werden gegen die Firma geprüft (404). Audit DOCUMENT_UPDATED_VIA_API.
POST/api/v1/documents/{id}/archive— Beleg archivieren

Scope: documents:write

Antwort: 200 { data: Document }

  • Setzt isArchived=true, archivedAt=jetzt. Bereits archiviert → 409. Audit DOCUMENT_ARCHIVED_VIA_API.
POST/api/v1/documents/{id}/unarchive— Beleg aus dem Archiv zurückholen

Scope: documents:write

Antwort: 200 { data: Document }

  • Setzt isArchived=false, archivedAt=null. Nicht archiviert → 409. Audit DOCUMENT_ARCHIVED_VIA_API (dieselbe Aktion, die Richtung steht in changes.isArchived).
DELETE/api/v1/documents/{id}— Beleg löschen

Scope: documents:write

Antwort: { data: { id, deleted: true } }

  • Löscht auch die Datei in S3 (ein S3-Fehler verhindert das Löschen des Datensatzes nicht). Audit DOCUMENT_DELETED_VIA_API.
Exporte3 Endpunkte · exports:read, direct-debits:write

Buchhaltungsexporte (CSV, DATEV, BMD, UStVA) und SEPA-Lastschriftdateien.

MethodePfadScopeKurzbeschreibung
GET/api/v1/exportsexports:readBuchhaltungsexport erzeugen (CSV, DATEV, BMD, UStVA)
POST/api/v1/exports/sepadirect-debits:writeSEPA-Sammelauftrag anlegen und Lastschriftdatei (PAIN.008) erzeugen
GET/api/v1/exports/customersexports:readKunden als CSV exportieren
GET/api/v1/exports— Buchhaltungsexport erzeugen (CSV, DATEV, BMD, UStVA)

Scope: exports:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
typestring (Enum)neincsvcsv | datev | bmd | ust
yearnumberneinlaufendes Jahr
monthnumbernein–0–11
quarternumbernein–1–4; ohne month/quarter gilt das ganze Jahr
category_id / categorystringnein–auch "all"/"uncategorized"

Antwort: Datei als Content-Disposition attachment. csv/ust: text/csv. datev: text/csv (Buchungsstapel). bmd: application/zip (buchungen.csv, personenkonten.csv, hinweise.txt). Mit Accept: application/json liefert csv stattdessen { csv, filename, summary, warnings[] }.

  • Identische Dateien wie /dashboard/exports; gleiche Belegauswahl (taxRelevantInvoiceConditions: keine Entwürfe, keine Proformas, stornierte Rechnungen nur mit Storno-Gutschrift).
  • Plan-Gate datevExport für type=datev/bmd (403); csv und ust sind in jedem Plan enthalten. Ungültiger type → 400 mit allowedValues. Kein AuditLog (wie im Dashboard).
POST/api/v1/exports/sepa— SEPA-Sammelauftrag anlegen und Lastschriftdatei (PAIN.008) erzeugen

Scope: direct-debits:write

Body-Felder

FeldTypPflichtStandardBeschreibung
invoiceIdsstring[]ja–1 bis 500
requestedCollectionDateISO-Datumja–Muss nach heute liegen (Kalendertag in Wien)
mandateTypestring (Enum)neinCOREKunden mit der anderen Mandatsart werden übersprungenCORE | B2B

Antwort: 200 Standard: application/xml, Content-Disposition attachment, Header X-Sepa-Message-Id/-Transaction-Count/-Warnings/-Batch-Number. Mit Accept: application/json: { xml, filename, messageId, transactionCount, totalAmount, warnings[], batchId, batchNumber }.

  • Jeder Aufruf legt einen Sammelauftrag (DD-JJJJ-NNNN) an, wie die Sammelaktion im Dashboard — deshalb ein eigener Scope statt exports:read: Die Rechnungen sind danach bis zum Verwerfen des Auftrags (Dashboard → SEPA-Lastschriften) für weitere Exporte gesperrt. Die Datei bleibt gespeichert. Eingezogen wird der offene Rest versendeter oder überfälliger Rechnungen in Euro; der Rechnungsstatus bleibt unverändert.
  • Übersprungen und in warnings gemeldet ("RE-… (Kunde): Grund"): andere Belegart oder Status, nichts offen, Rechnung bereits in einem nicht verworfenen Sammelauftrag, IBAN fehlt oder ungültig, kein aktives Mandat mit Datum, andere Mandatsart, ein schon verwendetes Einmalmandat (OOFF), eine Mandatsreferenz außerhalb der SEPA-Regeln (höchstens 35 Zeichen aus Buchstaben, Ziffern und + ? / - : ( ) . , ' Leerzeichen). Der Header X-Sepa-Warnings enthält höchstens 50 Einträge plus einen Hinweis auf die übrigen; vollständig mit Accept: application/json.
  • Firma braucht eine gültige sepaCreditorId (400 MISSING_CREDITOR_ID bzw. INVALID_CREDITOR_ID) und eine gültige iban (400 MISSING_IBAN bzw. INVALID_IBAN, Prüfziffer). Bleibt keine Lastschrift übrig: 400 NO_VALID_TRANSACTIONS mit details. Keine der Rechnungen gefunden → 404. Audit SEPA_EXPORT_VIA_API.
GET/api/v1/exports/customers— Kunden als CSV exportieren

Scope: exports:read

Query-Parameter

FeldTypPflichtStandardBeschreibung
include_archived / includeArchivedbooleanneinfalse
formatstring (Enum)neinsemicoloncomma | semicolon

Antwort: CSV mit BOM, Content-Disposition attachment, Header X-Export-Customer-Count.

  • Gleiche 43 Spalten (deutsche Kopfzeile) und Formel-Neutralisierung wie der Dashboard-Export. Audit CSV_EXPORT_CUSTOMERS (zusätzlich apiKeyId in changes).
Firmendaten1 Endpunkt · company:read

Firmenstammdaten, Nummernkreise, Plan-Funktionen und Verbrauch — nur lesend.

MethodePfadScopeKurzbeschreibung
GET/api/v1/companycompany:readFirmenstammdaten, Nummernkreise und Plan-Nutzung lesen
GET/api/v1/company— Firmenstammdaten, Nummernkreise und Plan-Nutzung lesen

Scope: company:read

Antwort: { data: { id, name, address, contact, legal, tax, bank, currency, paymentTerms, dunning, branding, numberRanges, plan: { plan, subscriptionPlan, subscriptionExpiresAt, trialEndsAt, features, limits }, usage: { documents, customers, emails, storage, apiCalls, users } } }

  • Read-only, keine Seiteneffekte.
  • legal enthält Rechtsform (legalForm), rechtlichen Namen (legalName), Handelsname (tradingName), Firmenbuchgericht (registryCourt) und bei Einzelunternehmen den Inhaber (owner) — dieselben Angaben wie auf den Belegen.
  • Bewusst NICHT enthalten: SMTP-Zugangsdaten, E-Mail-Domain-/DKIM-Einstellungen, Stripe-Ids, finAPI-Verknüpfung, API-Schlüssel, BMD-Kontenkonfiguration, Admin-Plan-Übersteuerung, Logo-Rohablage.
Webhooks8 Endpunkte · webhooks:read, webhooks:write

Webhook-Endpunkte für Ereignisbenachrichtigungen (nur Enterprise-Plan). Verwaltung nur über diese API, im Dashboard gibt es keinen Webhook-Editor. Jede Zustellung ist per HMAC-SHA256 über den unveränderten JSON-Body mit dem Secret des Endpunkts signiert (Header X-Webhook-Signature, hex); dazu X-Webhook-Event, X-Webhook-Event-Id und X-Webhook-Timestamp.

MethodePfadScopeKurzbeschreibung
GET/api/v1/webhookswebhooks:readWebhook-Endpunkte auflisten
POST/api/v1/webhookswebhooks:writeWebhook-Endpunkt anlegen
GET/api/v1/webhooks/{id}webhooks:readWebhook-Endpunkt inkl. letzter Zustellungen lesen
PUT/api/v1/webhooks/{id}webhooks:writeWebhook-Endpunkt ändern
DELETE/api/v1/webhooks/{id}webhooks:writeWebhook-Endpunkt löschen
POST/api/v1/webhooks/{id}/rotate-secretwebhooks:writeSignatur-Secret eines Webhook-Endpunkts rotieren
POST/api/v1/webhooks/{id}/testwebhooks:writeTestereignis an einen Webhook-Endpunkt senden
GET/api/v1/webhooks/{id}/deliverieswebhooks:readZustellversuche eines Webhook-Endpunkts auflisten
GET/api/v1/webhooks— Webhook-Endpunkte auflisten

Scope: webhooks:read

Plan-Feature: webhooks

Antwort: { data: [{ id, name, url, events[], is_active, max_retries, retry_delay_ms, rate_limit_per_min, total_deliveries, created_at, updated_at }] }

  • Enterprise-Plan-Gate (Feature "webhooks"). Liefert nie das secret.
POST/api/v1/webhooks— Webhook-Endpunkt anlegen

Scope: webhooks:write

Plan-Feature: webhooks

Body-Felder

FeldTypPflichtStandardBeschreibung
namestringja–
urlstringja–Muss zu einem öffentlichen HTTPS-Host auflösen (assertPublicHttpUrl)
eventsstring[]ja–Nicht leer, jeder Wert gegen WebhookEventType geprüft (Groß-/Kleinschreibung und „-“ egal); WEBHOOK_TEST ist nicht abonnierbar
secretstringneingeneriert als whsec_<48 hex>
max_retries / maxRetriesnumbernein3Ganzzahl 0–10 (Gesamtzahl der Versuche, mindestens 1)
retry_delay_ms / retryDelayMsnumbernein1000Ganzzahl 100–600000; Wartezeit vor Retry n = retry_delay_ms · 2^n. Retries gibt es nur innerhalb von 60 Minuten nach dem Ereignis
rate_limit_per_min / rateLimitPerMinnumber | nullneinnull (unbegrenzt)null (unbegrenzt) oder Ganzzahl 1–10000
headersobjectnein–Wird bei jeder Zustellung mitgesendet
metadataobjectnein–

Antwort: 201 { data: { id, name, url, secret, events[], is_active, max_retries, retry_delay_ms, created_at } } — secret wird nur hier zurückgegeben

  • Audit WEBHOOK_ENDPOINT_CREATED. 400 fehlender name/url/events, ungültiger Event-Typ, eine URL, die den Public-HTTPS-Egress-Check nicht besteht (privat/lokal/mit Zugangsdaten/kein HTTPS), oder Retry-Einstellungen außerhalb der Grenzen (max_retries 0–10, retry_delay_ms 100–600000, rate_limit_per_min null oder 1–10000). null bei max_retries/retry_delay_ms bedeutet hier den Standardwert.
  • Payout-Webhooks enthalten Bankdaten nur gekürzt als iban_last4: die letzten vier Zeichen ohne Whitespace, null ohne IBAN. iban, bic, bankAccountHolder und bankName entfallen auch bei eingebettetem payout (z. B. CREDIT_NOTE_CREATED/PAID) und als benannte Kopien in Payout-Metadaten. Status, Beträge, Transaktionsreferenzen und übrige freigegebene Metadaten bleiben erhalten. REST-Gutschrift- und Auszahlungsantworten bleiben unverändert.
GET/api/v1/webhooks/{id}— Webhook-Endpunkt inkl. letzter Zustellungen lesen

Scope: webhooks:read

Plan-Feature: webhooks

Antwort: { data: { id, name, url, events[], is_active, max_retries, retry_delay_ms, rate_limit_per_min, headers, metadata, total_deliveries, recent_deliveries: [...] (letzte 10), created_at, updated_at } }

  • 404, wenn nicht gefunden oder fremde Firma.
PUT/api/v1/webhooks/{id}— Webhook-Endpunkt ändern

Scope: webhooks:write

Plan-Feature: webhooks

Body-Felder

FeldTypPflichtStandardBeschreibung
name, url, eventsgemischtnein–Alle optional/partiell
is_active / isActivebooleannein–
max_retries / maxRetriesnumbernein–Ganzzahl 0–10 (Gesamtzahl der Versuche, mindestens 1)
retry_delay_ms / retryDelayMsnumbernein–Ganzzahl 100–600000; Wartezeit vor Retry n = retry_delay_ms · 2^n. Retries gibt es nur innerhalb von 60 Minuten nach dem Ereignis
rate_limit_per_min / rateLimitPerMinnumber | nullnein–null (unbegrenzt) oder Ganzzahl 1–10000
headers, metadataobjectnein–

Antwort: 200 { data: { id, name, url, events[], is_active, max_retries, retry_delay_ms, rate_limit_per_min, updated_at } } — rate_limit_per_min ist neu in der Antwort

  • 404 wenn nicht gefunden. 400 bei leerer/ungültiger url, nicht-array events, ungültigem Event-Typ oder Retry-Einstellungen außerhalb der Grenzen (max_retries 0–10, retry_delay_ms 100–600000, rate_limit_per_min null oder 1–10000). null bei max_retries/retry_delay_ms wird abgelehnt (früher still als 0 gespeichert); null bei rate_limit_per_min hebt das Limit auf.
  • Ein mitgeschicktes secret wird abgelehnt (400, code secret_not_updatable), statt wie früher still ignoriert zu werden; nichts wird geändert.
  • Eigene headers können die Header X-Webhook-Signature, X-Webhook-Event, X-Webhook-Event-Id, X-Webhook-Timestamp, Host und Content-Length nicht überschreiben (auch nicht in anderer Schreibweise).
  • Audit WEBHOOK_ENDPOINT_UPDATED mit changes = { apiKeyId, <feld>: { old, new } } für jedes tatsächlich geänderte Feld. headers-Änderungen werden nur als { old_keys, new_keys } geloggt (Werte nie im Audit-Log, da sie Secrets wie Authorization-Token enthalten können).
DELETE/api/v1/webhooks/{id}— Webhook-Endpunkt löschen

Scope: webhooks:write

Plan-Feature: webhooks

Antwort: 200 { success: true }

  • Hard Delete (kaskadiert WebhookDelivery-Zeilen per FK). Audit WEBHOOK_ENDPOINT_DELETED. 404 wenn nicht gefunden.
POST/api/v1/webhooks/{id}/rotate-secret— Signatur-Secret eines Webhook-Endpunkts rotieren

Scope: webhooks:write

Plan-Feature: webhooks

Body-Felder

FeldTypPflichtStandardBeschreibung
secretstringneinfehlt: Claribill erzeugt whsec_<48 hex> und gibt es einmalig zurückNeues Secret, 32–256 sichtbare ASCII-Zeichen ohne Leerzeichen. Wird nie zurückgegeben, auch nicht in Fehlermeldungen
expected_updated_at / expectedUpdatedAtstring (ISO-Zeitstempel)nein–updated_at aus GET /webhooks/{id} (ISO 8601 mit Uhrzeit und Zone); weicht der Stand ab → 409 endpoint_modified. Empfohlen, auch ohne mitgeliefertes secret

Antwort: 200 { data: { id, rotated: true, secret_source: "provided" | "generated", secret (nur bei generated), updated_at } } mit Cache-Control: no-store

  • Wirkt sofort für alle folgenden Sendeversuche, auch für Retries bereits laufender Zustellungen. Ein Request, der beim Rotieren schon unterwegs ist, trägt noch die alte Signatur. Claribill signiert nicht parallel mit dem alten Secret; den Ablauf mit dem Empfänger beschreibt das Betriebs-Runbook.
  • Audit WEBHOOK_SECRET_ROTATED im selben Commit, nur mit Marker und Quelle (provided/generated), ohne Secret und ohne Hash. GET-Antworten enthalten das Secret weiterhin nie.
  • 400 ungültiges secret, ungültiger Zeitstempel oder kein JSON-Objekt; 404 nicht gefunden oder fremde Firma; 409 endpoint_modified mit aktuellem updated_at.
POST/api/v1/webhooks/{id}/test— Testereignis an einen Webhook-Endpunkt senden

Scope: webhooks:write

Plan-Feature: webhooks

Antwort: 200 { data: { delivery_id, event_id, event_type: "WEBHOOK_TEST", status: "SUCCESS" | "FAILED", response_status, response_time_ms, error_message } }

  • Genau ein signierter Versuch an genau diesen Endpunkt, ohne Retries und ohne Rundversand an andere Endpunkte. Body wird ignoriert.
  • Feste Nutzlast { event: "WEBHOOK_TEST", event_id: "evt_test_…", timestamp, data: { test: true, message } } ohne Geschäftsobjekt: Es entsteht keine Rechnung, Zahlung, Mahnung, kein Kunde und keine E-Mail. Der Empfänger muss WEBHOOK_TEST ohne Verarbeitung quittieren.
  • Ergebnis auch im Zustellprotokoll (event_type WEBHOOK_TEST). Ein Fehlschlag beim Empfänger ist status FAILED in einer 200-Antwort. Gesamtfrist 10 Sekunden für Namensauflösung, Verbindung und Antwort-Header; den Antwort-Body liest Claribill nicht. Der Test zählt in rate_limit_per_min des Endpunkts und kann echte Ereignisse dort zurückstellen.
  • Audit WEBHOOK_TEST_SENT. 404 nicht gefunden oder fremde Firma; 409 endpoint_inactive; 429 test_rate_limited (höchstens 5 Tests pro Minute und Endpunkt, auch bei parallelen Aufrufen; Retry-After nennt die Sekunden bis zum nächsten freien Platz).
GET/api/v1/webhooks/{id}/deliveries— Zustellversuche eines Webhook-Endpunkts auflisten

Scope: webhooks:read

Plan-Feature: webhooks

Query-Parameter

FeldTypPflichtStandardBeschreibung
statusstring (Enum)nein–PENDING | SUCCESS | FAILED | RETRYING
event_typestring (Enum WebhookEventType)nein–Auch WEBHOOK_TEST für Testversände
limitnumbernein50
offsetnumbernein0

Antwort: { data: [{ id, event_type, event_id, status, attempts, last_attempt_at, next_retry_at, response_status, response_body, response_time_ms, error_message, created_at, completed_at }], pagination: { total, limit, offset, has_more } }

  • 404 wenn Endpunkt nicht gefunden. Ungültiges status/event_type → 400 mit allowedValues (vorher leeres Ergebnis bzw. möglicher 500).
Blog (nur Plattform-Admins)32 Endpunkte · blog:read, blog:write, blog:publish, blog:moderate

Internes CMS für den Claribill-Blog. Eigene Authentifizierung über lib/blog/api-auth.ts: der API-Key muss zusätzlich einem Plattform-Admin gehören. Kein Kunden-Feature — hier nur mit Methode, Pfad und Scope gelistet.

MethodePfadScopeKurzbeschreibung
GET/api/v1/blog/postsblog:readBlogposts auflisten
POST/api/v1/blog/postsblog:writeBlogpost anlegen
GET/api/v1/blog/connectionblog:readBlog-Verbindung prüfen
GET/api/v1/blog/posts/{id}blog:readBlogpost lesen
PATCH/api/v1/blog/posts/{id}blog:writeBlogpost ändern
DELETE/api/v1/blog/posts/{id}blog:writeBlogpost löschen
GET/api/v1/blog/posts/by-slug/{slug}blog:readBlogpost per Slug lesen
POST/api/v1/blog/posts/{id}/publishblog:publishBlogpost veröffentlichen
DELETE/api/v1/blog/posts/{id}/publishblog:publishBlogpost zurückziehen (unpublish)
POST/api/v1/blog/posts/{id}/scheduleblog:publishBlogpost für späteren Zeitpunkt planen
GET/api/v1/blog/categoriesblog:readBlog-Kategorien auflisten
POST/api/v1/blog/categoriesblog:writeBlog-Kategorie anlegen
GET/api/v1/blog/categories/{id}blog:readBlog-Kategorie lesen
PATCH/api/v1/blog/categories/{id}blog:writeBlog-Kategorie ändern
DELETE/api/v1/blog/categories/{id}blog:writeBlog-Kategorie löschen
GET/api/v1/blog/tagsblog:readBlog-Tags auflisten
POST/api/v1/blog/tagsblog:writeBlog-Tag anlegen
GET/api/v1/blog/tags/{id}blog:readBlog-Tag lesen
PATCH/api/v1/blog/tags/{id}blog:writeBlog-Tag ändern
DELETE/api/v1/blog/tags/{id}blog:writeBlog-Tag löschen
GET/api/v1/blog/mediablog:readMedienbibliothek auflisten
POST/api/v1/blog/mediablog:writeMedium hochladen
GET/api/v1/blog/media/{id}blog:readMedium lesen
POST/api/v1/blog/ai/full-postblog:writeKI-Blogpost-Generierung anstoßen
POST/api/v1/blog/ai/full-post/jobsblog:writeKI-Generierungsjob anlegen
GET/api/v1/blog/ai/full-post/jobs/{id}blog:readStatus eines KI-Generierungsjobs lesen
POST/api/v1/blog/ai/full-post/jobs/{id}/resumeblog:writeUnterbrochenen KI-Generierungsjob fortsetzen
POST/api/v1/blog/posts/{id}/translationsblog:writeÜbersetzungsentwurf in der anderen Sprache anlegen
GET/api/v1/blog/posts/{id}/translation-reviewblog:readPrüfstatus und Inhalts-Hashes der Übersetzung lesen
POST/api/v1/blog/posts/{id}/translation-reviewblog:publishGeprüfte Übersetzung an den aktuellen Quellenstand binden
PUT/api/v1/blog/categories/{id}/translationsblog:writeEnglischen Namen, Slug und Beschreibung einer Kategorie speichern
PUT/api/v1/blog/tags/{id}/translationsblog:writeEnglischen Namen und Slug eines Tags speichern
GET/api/v1/blog/posts— Blogposts auflisten

Scope: blog:read

Antwort: { posts: BlogPost[], pagination: { total, limit, offset } }

POST/api/v1/blog/posts— Blogpost anlegen

Scope: blog:write

HTTP-Header

FeldTypPflichtStandardBeschreibung
Idempotency-Keystringnein–Optional, 8–200 Zeichen aus A–Z, a–z, 0–9, . _ : -. Pro Firma und Endpunkt: gleicher Schlüssel und gleicher JSON-Body liefern denselben Artikel im aktuellen Stand (201, Idempotent-Replayed: true), auch bei parallelen Aufrufen. Abweichender Body oder ungültiger Schlüssel → 422; inzwischen gelöschter Artikel → 409 idempotency_key_post_deleted. Die JSON-Feldreihenfolge ist egal; auch nicht ausgewertete Felder zählen zum Vergleich. Aufbewahrung mindestens 30 Tage, danach kann derselbe Schlüssel wieder einen neuen Artikel anlegen.

Antwort: 201 BlogPost (ohne data-Hülle)

  • PUBLISHED und SCHEDULED erfordern zusätzlich blog:publish; Authentifizierung, Scopes und Kontingent gelten auch bei Wiederholungen.
  • Ohne Idempotency-Key bleibt jeder Aufruf eine neue Anlage. Wiederholungen lösen keine erneuten Webhooks oder Cache-Invalidierungen aus. Der vorhandene Webhook-Versand ist keine garantierte Zustellung: ein Abbruch nach Commit kann die erste Meldung verhindern.
GET/api/v1/blog/connection— Blog-Verbindung prüfen

Scope: blog:read

Antwort: BlogConnection { companyId, scopes, locales, revisionHeader, adapterVersion }

GET/api/v1/blog/posts/{id}— Blogpost lesen

Scope: blog:read

Antwort: BlogPost (ohne data-Hülle)

PATCH/api/v1/blog/posts/{id}— Blogpost ändern

Scope: blog:write

HTTP-Header

FeldTypPflichtStandardBeschreibung
X-Claribill-Expected-Updated-Atstringnein–Optional: exakter ISO-Wert von updatedAt aus dem letzten Readback; veralteter Stand wird atomar mit 409 abgewiesen.

Antwort: BlogPost (ohne data-Hülle)

  • Statuswechsel auf/von PUBLISHED erfordert zusätzlich blog:publish.
DELETE/api/v1/blog/posts/{id}— Blogpost löschen

Scope: blog:write

HTTP-Header

FeldTypPflichtStandardBeschreibung
X-Claribill-Expected-Updated-Atstringnein–Optional: exakter ISO-Wert von updatedAt aus dem letzten Readback; veralteter Stand wird atomar mit 409 abgewiesen.

Antwort: 200 { ok: true }

GET/api/v1/blog/posts/by-slug/{slug}— Blogpost per Slug lesen

Scope: blog:read

Antwort: BlogPost (ohne data-Hülle)

POST/api/v1/blog/posts/{id}/publish— Blogpost veröffentlichen

Scope: blog:publish

HTTP-Header

FeldTypPflichtStandardBeschreibung
X-Claribill-Expected-Updated-Atstringnein–Optional: exakter ISO-Wert von updatedAt aus dem letzten Readback; veralteter Stand wird atomar mit 409 abgewiesen.

Antwort: 200 BlogPost (ohne data-Hülle)

DELETE/api/v1/blog/posts/{id}/publish— Blogpost zurückziehen (unpublish)

Scope: blog:publish

HTTP-Header

FeldTypPflichtStandardBeschreibung
X-Claribill-Expected-Updated-Atstringnein–Optional: exakter ISO-Wert von updatedAt aus dem letzten Readback; veralteter Stand wird atomar mit 409 abgewiesen.

Antwort: BlogPost (ohne data-Hülle)

POST/api/v1/blog/posts/{id}/schedule— Blogpost für späteren Zeitpunkt planen

Scope: blog:publish

Antwort: 200 BlogPost (ohne data-Hülle)

GET/api/v1/blog/categories— Blog-Kategorien auflisten

Scope: blog:read

Antwort: { categories: BlogCategory[] }

POST/api/v1/blog/categories— Blog-Kategorie anlegen

Scope: blog:write

Antwort: 201 { id, slug, name }

GET/api/v1/blog/categories/{id}— Blog-Kategorie lesen

Scope: blog:read

Antwort: BlogCategory (Datensatz ohne data-Hülle)

PATCH/api/v1/blog/categories/{id}— Blog-Kategorie ändern

Scope: blog:write

Antwort: BlogCategory (Datensatz ohne data-Hülle)

DELETE/api/v1/blog/categories/{id}— Blog-Kategorie löschen

Scope: blog:write

Antwort: 200 { ok: true }

GET/api/v1/blog/tags— Blog-Tags auflisten

Scope: blog:read

Antwort: { tags: BlogTag[] }

POST/api/v1/blog/tags— Blog-Tag anlegen

Scope: blog:write

Antwort: 201 { id, slug, name }

GET/api/v1/blog/tags/{id}— Blog-Tag lesen

Scope: blog:read

Antwort: BlogTag (Datensatz ohne data-Hülle)

PATCH/api/v1/blog/tags/{id}— Blog-Tag ändern

Scope: blog:write

Antwort: BlogTag (Datensatz ohne data-Hülle)

DELETE/api/v1/blog/tags/{id}— Blog-Tag löschen

Scope: blog:write

Antwort: 200 { ok: true }

GET/api/v1/blog/media— Medienbibliothek auflisten

Scope: blog:read

Antwort: { media: BlogMedia[] }

POST/api/v1/blog/media— Medium hochladen

Scope: blog:write

Antwort: 201 BlogMedia ohne width/height (ohne data-Hülle)

GET/api/v1/blog/media/{id}— Medium lesen

Scope: blog:read

Antwort: BlogMedia (ohne data-Hülle)

POST/api/v1/blog/ai/full-post— KI-Blogpost-Generierung anstoßen

Scope: blog:write

Antwort: 200 { draft, ai: { model, promptHash } } — synchrone Generierung; für lange Läufe die Job-Endpunkte verwenden

POST/api/v1/blog/ai/full-post/jobs— KI-Generierungsjob anlegen

Scope: blog:write

Antwort: 202 { job: Job }

GET/api/v1/blog/ai/full-post/jobs/{id}— Status eines KI-Generierungsjobs lesen

Scope: blog:read

Antwort: { job: Job }

POST/api/v1/blog/ai/full-post/jobs/{id}/resume— Unterbrochenen KI-Generierungsjob fortsetzen

Scope: blog:write

Antwort: 202 { job: Job } (200, wenn der Job bereits abgeschlossen ist)

POST/api/v1/blog/posts/{id}/translations— Übersetzungsentwurf in der anderen Sprache anlegen

Scope: blog:write

Antwort: { id, locale, status }

GET/api/v1/blog/posts/{id}/translation-review— Prüfstatus und Inhalts-Hashes der Übersetzung lesen

Scope: blog:read

Antwort: { state, postHash, sourceHash, sourceId }

POST/api/v1/blog/posts/{id}/translation-review— Geprüfte Übersetzung an den aktuellen Quellenstand binden

Scope: blog:publish

Antwort: 200 { ok: true }

PUT/api/v1/blog/categories/{id}/translations— Englischen Namen, Slug und Beschreibung einer Kategorie speichern

Scope: blog:write

Antwort: 200 { id, categoryId, locale, slug, name, description }

PUT/api/v1/blog/tags/{id}/translations— Englischen Namen und Slug eines Tags speichern

Scope: blog:write

Antwort: 200 { id, tagId, locale, slug, name }

Meta & Discovery1 Endpunkt

Maschinenlesbare Beschreibung der API selbst.

MethodePfadScopeKurzbeschreibung
GET/api/v1/openapi.json–Maschinenlesbares OpenAPI-3.0-Dokument der gesamten v1-API laden
GET/api/v1/openapi.json— Maschinenlesbares OpenAPI-3.0-Dokument der gesamten v1-API laden

Öffentlich, keine Authentifizierung erforderlich.

Query-Parameter

FeldTypPflichtStandardBeschreibung
localestring (Enum)neindeSprache der Beschreibungen; technische Felder und Beispiele bleiben unverändert. Unbekannte Sprachen liefern 400.de | en

Antwort: 200 application/json — OpenAPI-3.0.3-Dokument, generiert aus diesem Katalog (lib/api/openapi.ts).

  • Öffentlich erreichbar, keine Authentifizierung nötig. Cache-Control: public, max-age=300.

Thema in der Hilfe öffnen

UID-Validierungshistorie

Alle UID-Prüfungen werden automatisch protokolliert.

Gespeicherte Daten:

  • UID-Nummer und Ländercode
  • Validierungsergebnis (gültig/ungültig)
  • Firmenname und Adresse (von VIES zurückgeliefert)
  • Zeitstempel und Benutzer
  • Verknüpfung zum Kunden (falls vorhanden)

Zugriff:

  1. Gehen Sie zu Kunden
  2. Klicken Sie auf "UID-Historie"

Verwendung:

  • Nachweis für das Finanzamt
  • Compliance-Dokumentation
  • Nachvollziehbarkeit von Reverse-Charge-Entscheidungen

Thema in der Hilfe öffnen

Benachrichtigungen

Claribill informiert Sie in der App und per E-Mail über wichtige Ereignisse, z. B. eingegangene Zahlungen, überfällige Rechnungen oder angenommene Angebote.

Einstellungen:

Unter Einstellungen → Benachrichtigungen legen Sie je Ereignistyp fest, ob Sie in der App, per E-Mail oder über beide Kanäle benachrichtigt werden möchten.

Benachrichtigungstexte anpassen:

Unter Einstellungen → Benachrichtigungstexte bearbeiten Sie die Vorlage jedes Benachrichtigungstyps individuell und senden sich eine Test-E-Mail mit der zuletzt gespeicherten Version.

In-App:

Ungelesene Benachrichtigungen erscheinen über das Glockensymbol im Dashboard.

Thema in der Hilfe öffnen

Buchhaltung (BMD)

Ordnen Sie Ihre Umsätze den passenden BMD-Konten zu, damit der Export direkt in BMD NTCS übernommen werden kann.

Konfiguration:

Unter Einstellungen → Buchhaltung hinterlegen Sie u. a. das Standard-Erlöskonto für Inlandsumsätze sowie die BMD-Steuercodes für inländische und EU-Reverse-Charge-Umsätze.

Verwendung:

Diese Zuordnung wird beim BMD-Export (siehe Exporte) automatisch angewendet. Für DATEV-Exporte greift stattdessen die Debitorennummer je Kunde.

Thema in der Hilfe öffnen

E-Mail-Postausgang

Behalten Sie den Überblick über automatisch versendete E-Mails.

Übersicht:

Unter Postausgang in der Seitenleiste sehen Sie protokollierte E-Mails und ihren Zustellstatus, darunter Versendet und Fehlgeschlagen.

Erneut senden:

Unterstützte fehlgeschlagene Belegmails können im Postausgang erneut versendet werden. Neue Einträge verwenden den gespeicherten Empfänger, die Sprache, den Text und das PDF. Wurde der Beleg inzwischen geändert, prüfen und versenden Sie ihn auf seiner Dokumentseite erneut.

Historische Einträge ohne gespeicherten Inhalt sind gekennzeichnet und verwenden beim Neuversand den aktuellen Beleg. Jeder Versandversuch erzeugt einen neuen Eintrag; der vorherige Fehlversuch bleibt in der Historie.

Unklarer Versand

Bei laufender oder unklarer Zustellung nicht blind erneut senden. Prüfen Sie Beleg und Postausgang. Eine reservierte Versandkapazität wird nicht nach einer Wartefrist automatisch frei. Inhaber und Admin können nur bei nachweislich nicht erfolgter Zustellung Nicht zugestellt bestätigen verwenden; ein aktiver Versandversuch bleibt gesperrt.

Thema in der Hilfe öffnen

Sicherheit & Passkeys

Verwalten Sie Ihre Anmeldemethoden unter Einstellungen → Sicherheit.

Passkey hinzufügen:

  1. Klicken Sie auf "Passkey hinzufügen"
  2. Bestätigen Sie mit Fingerabdruck, Gesichtserkennung oder Geräte-PIN
  3. Der Passkey erscheint in der Liste mit Gerätename und Erstellungsdatum

Verwaltung:

  • Mehrere Passkeys pro Konto möglich
  • Nicht mehr benötigte Passkeys können jederzeit entfernt werden
  • Der Magic Link per E-Mail bleibt immer als Rückfalloption verfügbar

Thema in der Hilfe öffnen

Entwürfe

Die zentrale Entwurfsübersicht unter /dashboard/drafts enthält automatisch gesicherte Formulareingaben des aktuellen Benutzers in der aktiven Firma. Sie können einen Entwurf fortsetzen oder nach Bestätigung löschen. Die automatische Sicherung startet nur, wenn das jeweilige Formular ausreichende Eingaben enthält, etwa einen gewählten Kunden.

Ein automatisch gesichertes Formular ist von einem bereits mit Rechnung erstellen gespeicherten Rechnungsbeleg im Status Entwurf zu unterscheiden: Diesen Beleg finden Sie unter Rechnungen und öffnen ihn dort. Firmenwechsel und Benutzer trennen auch die Formularentwürfe. Ein Entwurf wird durch Autosave weder fertiggestellt noch versendet.

Thema in der Hilfe öffnen

Rollen & Rechte

Legen Sie selbst fest, was jede Rolle in Ihrem Unternehmen darf.

Standardrollen anpassen

Unter Einstellungen → Rollen & Rechte öffnen Sie eine Rolle (Administrator, Buchhaltung, Mitarbeiter oder Extern). Die Rechte sind nach Bereichen gruppiert: Belege, Stammdaten, Finanzen und Verwaltung. Jeder Bereich (zum Beispiel Rechnungen oder Kunden) ist zunächst eingeklappt und zeigt, wie viele Rechte erlaubt sind. Klicken Sie auf einen Bereich, um seine Rechte zu sehen und zu ändern, oder nutzen Sie die Suche. Jedes Recht lässt sich einzeln vergeben oder entziehen, zum Beispiel Rechnungen: Erstellen, Zahlungen erfassen, Lieferscheine: Erstellen oder Kunden: Löschen. Mit Rechte speichern gelten die Änderungen sofort für alle Mitglieder der Rolle. Auf Standard zurücksetzen stellt die ursprünglichen Rechte wieder her.

Der Inhaber hat immer alle Rechte; seine Rolle lässt sich nicht einschränken.

Keine, Eigene, Kategorien, Alle

Bei Belegen wählen Sie für viele Rechte den Geltungsbereich: Keine, Eigene, Kategorien oder Alle. „Eigene“ gilt für selbst erstellte Belege, beim Ansehen auch für freigegebene. „Kategorien“ gilt wie „Eigene“ und zusätzlich für alle Belege in den Kategorien, die Sie beim jeweiligen Recht auswählen; ohne Auswahl wirkt es wie „Eigene“. „Alle“ gilt für alle Belege der Firma.

Einen Geltungsbereich haben:

  • Rechnungen: Ansehen, Bearbeiten, Entwürfe löschen, Fertigstellen, Per E-Mail versenden, Status ändern, Stornieren
  • Angebote: Ansehen, Löschen, Per E-Mail versenden, Status ändern
  • Auftragsbestätigungen: Ansehen, Bearbeiten, Löschen, Per E-Mail versenden, Status ändern
  • Aufträge: Ansehen, Bearbeiten, Löschen, Status ändern
  • Lieferscheine: Ansehen, Löschen, Per E-Mail versenden, Status ändern
  • Wiederkehrende Rechnungen: Ansehen; Bearbeiten, pausieren und fortsetzen; Löschen und archivieren
  • Dokumente: Ansehen, Bearbeiten und archivieren, Löschen
  • Dokumentkategorien: Belegen eine Kategorie zuweisen

Alle übrigen Rechte kennen nur erlaubt oder nicht erlaubt, zum Beispiel Erstellen, Zahlungen, Berichtigen und Umwandeln.

Kategorien je Recht

Steht ein Recht auf der Stufe Kategorien, erscheint in seiner Zeile links neben der Stufen-Auswahl eine durchsuchbare Mehrfachauswahl. Als erster Eintrag steht Belege ohne Kategorie, darunter die Dokumentkategorien. Jedes Recht hat seine eigene Auswahl, auch jede Belegart (Rechnungen, Angebote, Auftragsbestätigungen, Aufträge, Lieferscheine, wiederkehrende Rechnungen, Dokumente). Ohne Auswahl steht in der Schaltfläche Kategorien wählen, und das Recht gilt nur für eigene Belege. Mit den Schaltflächen unter der Liste (Für die n anderen „Kategorien“-Rechte in Bereich übernehmen, Für alle n anderen „Kategorien“-Rechte der Rolle übernehmen) kopieren Sie die Auswahl auf andere Rechte, die schon auf „Kategorien“ stehen. Eine früher für die ganze Rolle gespeicherte Auswahl gilt weiter und erscheint in den Zeilen dieser Rechte.

Arbeitsbereich der Rolle begrenzen

Oben auf der Seite jeder Rolle (außer Inhaber) legen Sie in der Karte Arbeitsbereich der Rolle begrenzen optional eine Grenze fest: Mit dem Kontrollkästchen Diese Rolle arbeitet ausschließlich in bestimmten Kategorien und einer Auswahl der Kategorien (auch hier mit dem Eintrag Belege ohne Kategorie) sehen und bearbeiten Mitglieder nur Belege innerhalb der Grenze: Eigene und freigegebene Belege außerhalb sind gesperrt, neue Belege brauchen eine dieser Kategorien, und das gilt auf jeder Stufe, auch bei „Alle“. Ohne Grenze steht dort „Keine Begrenzung“. Mit Grenze bietet die Auswahl eines Rechts nur Kategorien innerhalb der Grenze an. Eine leere Grenze sperrt den Belegzugriff, und der firmenweite Abruf im Zahlungsabgleich steht solchen Rollen nicht zur Verfügung. Rollen mit dem Recht Kategorien verwalten können keine Grenze haben.

Beispiel: Die Rolle „Projekt X“ darf Rechnungen: Ansehen in den Kategorien A und B, Rechnungen: Bearbeiten nur in B (jeweils Stufe „Kategorien“). Die Mitglieder sehen eigene Rechnungen und die der Kategorien A und B, bearbeiten aber nur eigene und die der Kategorie B. Braucht ein einzelnes Mitglied besondere Rechte, legen Sie eine eigene Rolle für es an.

Gutschriften

Das Modul Gutschriften hat keine Stufen und keine Kategorie-Auswahl. Gutschriften zählen zu den Rechnungen: Welche Gutschriften eine Rolle sieht, bestimmt das Recht Rechnungen: Ansehen, samt den dort gewählten Kategorien. Die Rechte Gutschriften: Ansehen und Gutschriften: Erstellen legen nur fest, ob die Rolle den Bereich Gutschriften öffnen und Gutschriften erstellen darf.

Abhängigkeiten

Manche Rechte setzen ein anderes voraus. Ohne Ansehen sind die übrigen Rechte des Bereichs gesperrt. In Rechnung umwandeln setzt Rechnungen: Erstellen voraus. Die Seite zeigt unter dem Recht an, was fehlt.

Eigene Rollen

Ab dem Professional-Paket legen Sie mit Neue Rolle eigene Rollen an, zum Beispiel „Vertrieb“ oder „Lager“. Wählen Sie eine Vorlage, vergeben Sie einen Namen und passen Sie die Rechte an. Eigene Rollen weisen Sie unter Team zu, auch schon in der Einladung. Eine eigene Rolle lässt sich nur löschen, wenn sie niemandem mehr zugewiesen ist.

Schutzregeln

  • Rollen und Rechte verwaltet, wer das Recht Rollen und Rechte verwalten hat (standardmäßig Inhaber und Administrator)
  • Niemand ändert die eigene Rolle
  • Niemand vergibt Rechte oder Kategorien, die über die eigenen hinausgehen
  • Jede Änderung steht im Audit-Log

Thema in der Hilfe öffnen

Versand unklar oder Kontingent reserviert

Ein Entwurf kann einen Versandplatz reservieren, obwohl er noch nicht als verbrauchter Beleg zählt. Ein laufender oder unklarer Versand gibt diesen Platz nicht automatisch nach einer Frist frei.

  1. Öffnen Sie den betroffenen Beleg und Postausgang. Prüfen Sie vorhandene Versandhinweise und Protokolle.
  2. Bei Versandplatz reserviert lesen Sie, ob der Vorgang noch läuft oder sein Ergebnis unklar ist. Wiederholtes Klicken kann keinen sicheren Zustellnachweis ersetzen.
  3. Nur Inhaber und Admin dürfen Nicht zugestellt bestätigen verwenden, wenn nachgewiesen ist, dass keine Zustellung erfolgt ist und kein Versuch mehr läuft.
  4. Der Bestätigungsdialog Zustellung nachweislich nicht erfolgt? erklärt die Folgen. Nicht zugestellt – Platz freigeben gibt ausschließlich den Platz frei; Beleg, Nummer und Versandprotokoll bleiben erhalten.
  5. Bei weiterhin unklarer Zustellung abbrechen und Support um Prüfung bitten. Ein aktiver Versuch bleibt gesperrt und kann eine kontrollierte Wiederherstellung erfordern.

Ein technischer Fehler, fehlender Status oder eine Wartezeit allein beweist keine Nichtzustellung. Diese Klärung versendet selbst keine E-Mail.

Thema in der Hilfe öffnen

REST-API, MCP und Webhooks

REST-API

Wer das Recht API-Schlüssel hat (standardmäßig Inhaber und Admin), erstellt unter Einstellungen → API-Schlüssel firmenspezifische Schlüssel mit ausgewählten Scopes; API-Zugang ist ab Starter verfügbar. Der vollständige Schlüssel wird nur einmal angezeigt. Danach sind Aktivieren, Deaktivieren und Löschen möglich. Die öffentliche Referenz und OpenAPI-Datei beschreiben Methoden, Felder, Fehler, Limits und Seiteneffekte.

Ein API-Schlüssel gehört zur Firma, nicht zu einem Benutzer, und ist nicht an Rollen oder Dokumentkategorien gebunden. Im Rahmen seiner Scopes erreicht er alle Belege der Firma - unabhängig von Rolle und Kategorien der Person, die ihn anlegt. Vergeben Sie deshalb nur die Scopes, die eine Integration braucht. Braucht eine Aktion einen handelnden Benutzer, zum Beispiel 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.

Die REST-API deckt viele Beleg- und Stammdatenabläufe ab. Sie ersetzt nicht jede Dashboard-Einstellung oder jede persönliche Benutzerfunktion. Plattform-Blog-Endpunkte sind zusätzlich auf Plattformadministratoren beschränkt.

Rechnungsentwurf vorbereiten

POST /api/v1/invoices/prepare liefert eine Vorschau und einen ausdrücklichen Erstellungsrumpf. Vorbereitung allein erstellt oder versendet keinen Beleg. Verwenden Sie beim anschließenden Anlegen die dokumentierte Version und Idempotenzregeln.

Versandvertrag

Der optionale Vertrag invoice_send_v1 muss betrieblich freigegeben sein. Erkennen Sie seine Verfügbarkeit über den dokumentierten Capability-Endpunkt. Vorhandener Code bedeutet keine allgemeine Aktivierung. Bei unklarem Versand niemals automatisch mit neuem Schlüssel oder ohne Schlüssel erneut senden. Status und Replay sind historisch; resolution_decision kann eine gesonderte geprüfte Klärung anzeigen.

MCP

Die separate OAuth-Verbindung für Codex/ChatGPT bietet zehn Werkzeuge gemäß öffentlicher Plugin-Anleitung. Sie ist vom integrierten Dashboard-KI-Assistenten verschieden. Insbesondere darf dessen größerer Funktionsumfang nicht pauschal auf das öffentliche MCP-Angebot übertragen werden.

Verbinden kann, wessen Rolle das Recht Externe KI-Apps verbinden hat (Einstellungen → Rollen & Rechte, Bereich KI-Assistent). Wird es entzogen, lehnt Claribill weitere Aufrufe der verbundenen App ab. Jedes Werkzeug braucht zusätzlich zum OAuth-Scope das passende Recht der Rolle, zum Beispiel Rechnungen: Erstellen für Rechnungsentwürfe. Dabei gelten die Stufen und Kategorien je Recht wie im Dashboard: Rechnungen und Gutschriften erscheinen nur so weit, wie Rechnungen: Ansehen reicht (eigene, die dort gewählten Kategorien oder alle). Arbeitet die Rolle ausschließlich in bestimmten Kategorien, gilt diese Grenze auch hier.

Ein Rechnungsentwurf lässt sich mit documentCategoryId in einer Dokumentkategorie anlegen. prepare_invoice_draft nennt in documentCategories die Kategorien, die der Benutzer wählen darf, und zeigt die gewählte Kategorie zur Bestätigung. Ohne Angabe entsteht der Entwurf ohne Kategorie; die Standardkategorie des Kunden wird nicht vorbelegt. Arbeitet die Rolle ausschließlich in bestimmten Kategorien, ist eine davon Pflicht, sofern Belege ohne Kategorie nicht dazugehört.

Webhooks

Enterprise-Kunden verwalten Webhooks über /api/v1/webhooks und passende Scopes. Es gibt keinen Webhook-Editor im Dashboard. Der API-Explorer dokumentiert Ereignisse, Signatur, Testzustellung und Secret-Wechsel. Ein empfangendes System muss Ereignisse anhand ihrer ID gegen doppelte Verarbeitung schützen.

Thema in der Hilfe öffnen

Teamverwaltung

Laden Sie Mitarbeiter ein und vergeben Sie Rollen.

Einladung:

  1. Gehen Sie zu Team
  2. Geben Sie die E-Mail-Adresse ein
  3. Wählen Sie die Rolle
  4. Klicken Sie auf "Einladen"

Der Eingeladene erhält eine E-Mail mit Link zur Registrierung. Offene, noch nicht angenommene Einladungen zählen bereits zum Benutzer-Limit Ihres Plans.

Rollen verwalten:

  • Inhaber: Kann nicht entfernt werden, Rolle ist nicht änderbar und nicht zuweisbar
  • Rollen weist zu, wer das Recht Rollen zuweisen und Mitglieder entfernen hat (standardmäßig Inhaber und Admin): eine Standardrolle oder, ab dem Professional-Paket, eine eigene Rolle
  • Ein Mitglied kann seine eigene Rolle nicht ändern
  • Was eine Rolle darf, legen Sie unter Einstellungen → Rollen & Rechte fest

Thema in der Hilfe öffnen

Rollen & Berechtigungen

Claribill verwendet ein rollenbasiertes Berechtigungssystem (RBAC). Die fünf Standardrollen sind der Ausgangspunkt; die Übersicht zeigt ihre Standardwerte. Unter Einstellungen → Rollen & Rechte passen Sie die Rechte jeder Rolle außer dem Inhaber an und legen ab dem Professional-Paket eigene Rollen an. Wo diese Dokumentation Rollen nennt, zum Beispiel „Inhaber und Admin“, sind die Standardrechte gemeint.

Übersicht der Rollen:

RolleBeschreibung
InhaberFirmengründer, hat immer alle Rechte
Administrator (kurz Admin)Verwaltet Firma, Team und alle Belege
BuchhaltungRechnungswesen und Finanzen
MitarbeiterErstellt Rechnungen, pflegt Kunden, bearbeitet eigene Belege
ExternLesezugriff auf freigegebene Belege, zum Beispiel für die Steuerberatung

Berechtigungsmatrix (Standardwerte):

BereichInhaberAdminBuchhaltungMitarbeiterExtern
Dashboard✓✓✓✓✓
Rechnungen✓✓✓eingeschränktnur freigegebene
Angebote✓✓✓nur lesennur lesen
Auftragsbestätigungen✓✓✓nur lesennur lesen
Aufträge✓✓✓nur lesennur lesen
Lieferscheine✓✓✓nur lesennur lesen
Gutschriften✓✓✓✗✗
Kunden✓✓✓eingeschränkt✗
Artikel & Leistungen✓✓✓✗✗
Berichte✓✓✓✗✗
Dokumente✓✓✓nur lesennur lesen
Wiederkehrend✓✓✓nur lesennur lesen
Exporte✓✓✓✗✓
Team✓✓✗✗✗
Firmeneinstellungen✓✓nur Buchhaltungskonten✗✗
API-Schlüssel✓✓✗✗✗
Audit-Log✓✓✗✗✗
E-Mail-Templates✓✓✗✗✗

Besonderheiten:

  • Mitarbeiter dürfen standardmäßig eigene Rechnungen anlegen, den eigenen Entwurf fertigstellen und eigene Rechnungen stornieren - bei fremden Rechnungen bleiben sie auf Lesen beschränkt. Zahlungen erfassen dürfen standardmäßig nur Inhaber, Admin und Buchhaltung
  • Kunden: Standardmäßig dürfen Mitarbeiter Kunden ansehen, anlegen und bearbeiten, aber nicht löschen oder archivieren; Extern hat standardmäßig keinen Zugriff. Diese Rechte sind pro Firma unter Einstellungen → Rollen & Rechte für jede Rolle einzeln einstellbar
  • Extern: Gedacht für die Steuerberatung - standardmäßig Lesezugriff auf freigegebene Rechnungen, Angebote, Auftragsbestätigungen, Aufträge, Lieferscheine, Wiederholungsrechnungen und Dokumente sowie Exporte; kein Zugriff auf Gutschriften und Kunden. Die Rolle ist erst ab dem Professional-Plan nutzbar
  • Inhaber: Hat immer alle Rechte, kann nicht entfernt werden, Rolle kann nicht geändert werden
  • Eigene Rollen (ab dem Professional-Paket): Starten mit den Rechten einer Standardrolle als Vorlage und lassen sich danach frei einstellen
  • Jeder Benutzer sieht nur die Menüpunkte, für die er berechtigt ist

Lesen ist nicht Bearbeiten

Ein Haken in der Übersicht bedeutet Bereichszugang, nicht jede Aktion. Angebote, Auftragsbestätigungen, Aufträge, Lieferscheine und Wiederholungen anlegen oder verwalten dürfen standardmäßig Inhaber, Admin und Buchhaltung; Mitarbeiter und Externe können je Bereich lediglich sichtbare Belege lesen. Buchhaltung, Mitarbeiter und Externe sehen standardmäßig nur eigene und für sie freigegebene Belege. Mehr sehen sie, wenn das Recht Ansehen der jeweiligen Belegart auf der Stufe Kategorien (mit den bei diesem Recht gewählten Dokumentkategorien) oder Alle steht. Alle Rechte sind pro Firma unter Einstellungen → Rollen & Rechte einstellbar; die Stufen Keine / Eigene / Kategorien / Alle beschreibt der Abschnitt „Rollen & Rechte“. Persönliche Sprache, Sicherheit und Benachrichtigungseinstellungen sind von den administrativen Firmeneinstellungen zu unterscheiden.

Thema in der Hilfe öffnen

Team-Freigaben

Wer das Recht Belegfreigaben verwalten hat (standardmäßig Inhaber und Admin), kann sichtbare Belege über Teilen öffnen, mit Teammitglied auswählen … einen Empfänger auswählen und mit Freigeben bestätigen. Unter Team lassen sich außerdem Freigaben für alle Belege eines bestimmten Erstellers oder einer bestimmten Quellrolle verwalten. Solche Freigaben kann nur anlegen, wer selbst alle Belege der Firma sieht; sonst blendet die Teamseite die beiden Formulare aus und nennt den Grund.

Eine Rollenfreigabe bedeutet: Ein ausgewählter Empfänger sieht die Belege, die Mitglieder der gewählten Quellrolle erstellt haben. Sie gibt nicht automatisch jedem Mitglied einer Rolle alle Dokumente.

Freigaben erweitern die Dokumentensichtbarkeit, verleihen aber keine zusätzlichen Rechte für Anlegen, Zahlung, Versand oder Verwaltung. Sie wirken für Mitglieder, deren Recht Ansehen der Belegart auf der Stufe Eigene oder Kategorien steht; auf der Stufe Keine bleibt auch ein freigegebener Beleg unsichtbar, auf der Stufe Alle ist keine Freigabe nötig. Die Grenze Diese Rolle arbeitet ausschließlich in bestimmten Kategorien bleibt wirksam: Ein freigegebener Beleg außerhalb der Grenze bleibt gesperrt. Standardmäßig sehen Buchhaltung, Mitarbeiter und Extern nur eigene und freigegebene Belege.

Thema in der Hilfe öffnen

Firmenwechsel

Bei mindestens zwei Firmenmitgliedschaften erscheint der Firmenwähler im Kopfbereich. Wählen Sie dort die gewünschte Firma; Claribill öffnet deren Dashboard. Bei nur einer Firma wird nur der Firmenname angezeigt.

Neue Firma anlegen führt aus dem Firmenmenü zur Ersteinrichtung. Ist dieses Menü mangels zweiter Mitgliedschaft noch nicht vorhanden, können berechtigte Benutzer die Ersteinrichtung direkt unter /onboarding öffnen. Die Anzahl eigener Firmen hängt vom Tarif ab: Free und Starter 1, Professional 3, Enterprise 10.

Firma, Belege, Vorlagen, Abonnement und Benutzerrolle sind jeweils getrennt. Nach einem Wechsel zeigt ein anderer geöffneter Tab Firma gewechselt – bitte neu laden. Verwenden Sie dort Neu laden, bevor Sie weiterarbeiten. Alte Formulare lassen sich nicht für die inzwischen andere Firma speichern.

Thema in der Hilfe öffnen

KI-Assistent

Der KI-Assistent erledigt im Chat, was Sie sonst im Dashboard machen. Beschreiben Sie in eigenen Worten, was zu tun ist. Der Assistent legt die Belege an und führt Aufgaben aus.

Wo Sie ihn finden

  • KI-Assistent in der Seitenleiste: Chat im Vollbild mit Gesprächsverlauf und Aktivitätsverlauf
  • Strg/⌘ + J auf jeder Dashboard-Seite: öffnet den Chat rechts. Der Assistent weiß dabei, welchen Beleg Sie gerade ansehen.

Was er kann

  • Rechnungen, Proformas, Angebote, Auftragsbestätigungen, Lieferscheine, Aufträge, Gutschriften und Wiederholungsrechnungen anlegen
  • Angebote und Auftragsbestätigungen in Rechnungen umwandeln
  • Rechnungen fertigstellen und versenden, Zahlungen erfassen, Mahnungen senden, stornieren
  • Kunden und Produkte suchen, anlegen und ändern
  • Auswertungen: offene und überfällige Rechnungen, Umsatz des Monats und des Jahres

Beispiele:

  • „Erstelle für die Müller GmbH eine Rechnung über 10 Beratungsstunden à 120 € für September.“
  • „Wandle das Angebot AN-2026-0042 in eine Rechnung um und schick sie an den Kunden.“
  • „Lege für Huber eine monatliche Wiederholungsrechnung über die Wartungspauschale an.“
  • „Welche Rechnungen sind überfällig?“

Bestätigung vor jeder Außenwirkung

Lesen und Entwürfe anlegen führt der Assistent sofort aus. Alles mit Außenwirkung oder ohne Rückweg zeigt er zuerst als Bestätigungskarte mit allen Angaben (Empfänger, Betrag, Rechnungsnummer):

  • Versand per E-Mail
  • Fertigstellen mit Rechnungsnummer
  • Zahlung und Mahnung
  • Storno und Löschen
  • Statuswechsel und Aktivieren einer Wiederholungsrechnung
  • Änderungen an bestehenden Kunden und Produkten

Erst Bestätigen und ausführen führt die Aktion genau so aus. Ein Vorschlag verfällt mit Ihrer nächsten Nachricht oder nach 30 Minuten. Wiederholungsrechnungen legt der Assistent immer pausiert und ohne automatischen Versand an.

Aktivitätsverlauf und Gespräche

  • Rechts zeigt der Aktivitätsverlauf, was der Assistent abgefragt, entschieden, angelegt oder versendet hat, jeweils mit Link zum Beleg.
  • Unter Verlauf öffnen, suchen, umbenennen und löschen Sie frühere Gespräche.
  • Gespräche sind privat: Auch Kollegen derselben Firma sehen sie nicht.

Dokumentkategorien

Nennen Sie beim Anlegen die Kategorie („… in der Kategorie Projekt A“), entsteht der Beleg darin: Rechnungen, Proformas, Angebote, Lieferscheine, Aufträge, freie Gutschriften und Wiederholungsrechnungen. Wählbar sind dieselben Kategorien wie im Formular des Dashboards. Ohne Angabe bleibt der Beleg ohne Kategorie; eine am Kunden hinterlegte Standardkategorie übernimmt der Assistent nicht von selbst. Die Kategorie eines Rechnungsentwurfs ändert er, wenn Ihre Rolle an dieser Rechnung Belegen eine Kategorie zuweisen darf.

Rechte

  • Den Assistenten verwendet, wessen Rolle das Recht KI-Assistent verwenden hat (Einstellungen → Rollen & Rechte). Standardmäßig sind das alle Rollen außer Extern (Steuerberater).
  • Der Assistent darf nur, was Ihre Rolle auch im Dashboard darf – mit denselben Stufen und Kategorien je Recht. Er sieht und ändert Belege so weit, wie das jeweilige Recht reicht (Eigene, Kategorien oder Alle); „Rechnungen: Ansehen“ kann andere Kategorien umfassen als „Rechnungen: Bearbeiten“. Mit den Standardrechten erstellen Mitarbeiter zum Beispiel keine Angebote und erfassen keine Zahlungen; unter Einstellungen → Rollen & Rechte lässt sich das je Rolle ändern.
  • Arbeitet Ihre Rolle ausschließlich in bestimmten Kategorien, gilt diese Grenze auch im Chat: Belege außerhalb findet der Assistent nicht, und neue Belege brauchen eine dieser Kategorien.
  • Der Assistent kennt Ihre Rechte und sagt vorab, wenn eine Aufgabe außerhalb davon liegt.
  • Inhaber und Admins schalten ihn unter Einstellungen → KI-Assistent für die ganze Firma ein oder aus.

KI-Credits

Jede Anfrage verbraucht KI-Credits:

AnfrageCredits
Frage ohne Abfrage1
Mit Abfragen2
Mit Änderungen3
Bestätigen einer Karte0

Das monatliche Kontingent hängt vom Plan ab: Free 50, Starter 300, Professional 1.500, Enterprise 5.000. Den aktuellen Stand sehen Sie im Chat und unter Einstellungen → KI-Assistent.

Thema in der Hilfe öffnen

Dateien und Datenschutz

Dateien anhängen

Über die Büroklammer im Chat hängen Sie Dateien an, zum Beispiel eine Kundenbestellung, aus der ein Angebot werden soll.

  • Erlaubt sind PDF, PNG, JPEG und WebP, bis zu 3 Dateien und zusammen höchstens 3 MB pro Nachricht.
  • Der Assistent übernimmt Kunde, Positionen, Mengen und Preise und gleicht sie mit Ihren Kunden und Produkten ab.
  • Nach einem Anhang zeigt der Assistent für jede Schreibaktion eine Bestätigungskarte, auch für Entwürfe. Inhalte aus Dateien behandelt er als fremde Daten, nicht als Anweisungen.

Ablage im Dokumentenarchiv

Angehängte Dateien speichert Claribill unter Dokumente im Ordner KI-Assistent, mit einem Unterordner je Gespräch. Es gelten das Speicherkontingent Ihres Plans und die üblichen Sichtbarkeitsregeln für Dokumente.

Löschen

Löschen Sie ein Gespräch im Verlauf, entfernt Claribill auch dessen Ordner mit allen Dateien. Gespräche ohne neue Nachricht werden nach 365 Tagen automatisch gelöscht. Belege, die der Assistent angelegt hat (Rechnungen, Angebote …), bleiben erhalten.

Welche Daten an das KI-Modell gehen

Für eine Antwort überträgt Claribill Ihre Nachricht, die nötigen Kunden- und Belegdaten sowie angehängte Dateien an Anthropic (Claude) über das Vercel AI Gateway. E-Mail-Adressen von Kunden gibt Claribill dabei nur maskiert weiter.

Thema in der Hilfe öffnen

Paket & Abrechnung

Claribill bietet vier Pakete für unterschiedliche Anforderungen. Neue Firmen erhalten bei der Einrichtung eine 14-tägige Testphase mit Professional-Funktionen. Ein gebuchter kostenpflichtiger Plan bestimmt anschließend die verfügbaren Funktionen.

Free (Kostenlos)

  • 1 Benutzer, 1 Firma
  • 25 Kunden, 50 Belege pro Jahr (Rechnungen, Gutschriften und Proforma-Rechnungen ab Fertigstellung, Angebote, Auftragsbestätigungen und Lieferscheine ab Versendet, Aufträge ab Aktiv - zusammengezählt, Entwürfe zählen nicht)
  • 25 E-Mails pro Monat, 1 GB Speicher
  • KI-Assistent mit 50 KI-Credits pro Monat
  • Claribill-Branding auf PDFs und E-Mails ist Pflicht
  • Kein CSV-Import, kein DATEV-Export, keine Team-Einladungen

Starter - 19 €/Monat (190 €/Jahr)

  • 3 Benutzer, 1 Firma
  • 500 Kunden, 1.000 Belege pro Jahr, 5 GB Speicher, 150 E-Mails pro Monat, 10.000 API-Aufrufe pro Monat
  • KI-Assistent mit 300 KI-Credits pro Monat
  • Claribill-Branding auf PDFs und E-Mails bleibt wie im Free-Plan bestehen
  • Team-Einladungen und Rollen mit einstellbaren Rechten, CSV-Import, DATEV-Export
  • REST-API-Zugang
  • Wiederkehrende Rechnungen
  • E-Mail-Support

Professional - 29 €/Monat (290 €/Jahr)

  • 10 Benutzer, 3 Firmen
  • 2.000 Kunden, 2.500 Belege pro Jahr, 25 GB Speicher, 1.000 E-Mails pro Monat, 50.000 API-Aufrufe pro Monat
  • KI-Assistent mit 1.500 KI-Credits pro Monat
  • Kein Claribill-Branding mehr auf PDFs und E-Mails
  • Externer Zugang für Steuerberater (Rolle "Extern")
  • Eigene Rollen zusätzlich zu den fünf Standardrollen
  • Eigene E-Mail-Domain und eigener SMTP-Server
  • Bank-Integration (finAPI)
  • Prioritäts-Support

Enterprise - 99 €/Monat (990 €/Jahr)

  • 25 Benutzer (Basis), 10 Firmen
  • 10.000 Kunden, 10.000 Belege pro Jahr, 150 GB Speicher, 3.000 E-Mails pro Monat, 250.000 API-Aufrufe pro Monat
  • KI-Assistent mit 5.000 KI-Credits pro Monat
  • Alles aus Professional
  • Webhooks (nur in diesem Plan verfügbar)
  • Höchste Priorität im Support

Paket anzeigen:

Einstellungen → Paket & Abrechnung zeigt Ihr aktuelles Paket sowie den Verbrauch gegenüber den Limits.

Rechnungsempfänger für das Claribill-Abo ändern

  1. Öffnen Sie Einstellungen → Paket & Abrechnung und dort Rechnungsempfänger. Fehlt Ihre Firmenadresse, führt Firmendaten bearbeiten zu den Angaben für Ihre eigenen Belege.
  2. Als Inhaber oder Admin aktivieren Sie Rechnung an ein anderes Unternehmen. Füllen Sie Firmenname, Straße und Hausnummer, PLZ, Ort, Land und Rechnungs-E-Mail aus. Ansprechpartner und UID-Nummer sind optional.
  3. Bestätigen Sie mit Rechnungsempfänger speichern. Der neue Empfänger gilt für künftige Abo-Rechnungen. Die Absenderangaben auf Ihren Kundenbelegen ändern sich dadurch nicht.
  4. Um wieder die Firmendaten zu verwenden, schalten Sie Rechnung an ein anderes Unternehmen aus und bestätigen mit Änderung speichern. Erscheint ein bereits hinterlegter Empfänger als Vorschlag, übernimmt Aus Stripe übernehmen die Angaben ins Formular. Prüfen Sie sie vor dem Speichern.

Bei kostenpflichtigen Paketen steht der Preis zzgl. USt. in der Paketübersicht. Monatlich und Jährlich wechseln den Abrechnungszeitraum.

Thema in der Hilfe öffnen

Branding-Regeln

Das Branding wird basierend auf Ihrem Subscription-Plan gesteuert.

Free- und Starter-Plan (Branding aktiv):

Auf PDFs:

  • Claribill-Logo am Seitenende
  • Text: "Erstellt mit claribill · Kostenlose Rechnungssoftware"
  • QR-Code zur Claribill-Website

In E-Mails:

  • Claribill-Logo in der Fußzeile
  • Text: "Erstellt mit Claribill · Rechnungssoftware für Selbstständige"
  • Link zur Claribill-Website

Unabhängig vom Paket tragen versendete Beleg-E-Mails zusätzlich den neutralen Versandhinweis "Versendet über Claribill". Dieser Sicherheitshinweis ist kein Werbe-Badge und bleibt daher auch bei eigenem E-Mail-Design erhalten.

Professional und höher:

  • Kein Branding auf PDFs
  • Kein Branding in E-Mails
  • Ihre Dokumente erscheinen bis auf den neutralen Versandhinweis vollständig in Ihrem Corporate Design

Freiwilliges Badge:

Auch auf bezahlten Plänen können Sie unter Einstellungen → Branding-Farben die Option "Claribill-Badge auf Dokumenten anzeigen" freiwillig aktivieren, um uns zu unterstützen.

Upgrade:

Öffnen Sie Einstellungen → Paket & Abrechnung, wählen Sie Paket und Abrechnungsintervall und folgen Sie dem Checkout. Inhaber und Admin können außerdem das Kundenportal für die Abonnementverwaltung öffnen.

Thema in der Hilfe öffnen

Vollständige Dokumentation | Claribill