lexoffice API Kochbuch - Public API

• Grundlagen
• Rechnungskopf-Informationen
  • Rechnungsnummer
  • Kundennummer
  • Rechnungsdatum
  • Rechnungsstatus
• Rechnungsarten
• Kundenangaben
• Kopfbereich
  • Belegpositionen
  • Belegpositions-Typen
  • Elemente einer Belegposition
• Fußbereich
• Belegoptionen
• FAQ und Hinweise
• Kundenangaben

Grundlagen

Rechnungen in lexoffice können manuell im Browser, in iOS & Android Apps angelegt und bearbeitet werden. Per REST API können Rechnungen angelegt und gelesen werden.

Damit eine Rechnung den gesetzlichen Anforderungen genügt, müssen die Informationen zur Firmierung, Adresse etc. in den Einstellungen (Zahnrad-Icon) -> Allgemeine Einstellungen eingetragen werden.

Das Layout für Rechnungen kann in den Einstellungen (Zahnrad-Icon) -> Drucklayout konfiguriert werden.

Rechnungskopf-Informationen

Rechnungsnummer

lexoffice vergibt die Rechnungsnummer anhand den Einstellungen des Rechnungsnummern-Kreises im Menüpunkt "Einstellungen" (Zahnrad) -> Nummernkreise.

Kundennummer

lexoffice vergibt die Kundennummer anhand des referenzierten Kontakts. Bei Verwendung des Sammelkunden wird auf der Rechnung die gemeinsam genutzte Kundennummer für den Sammelkunden angezeigt; eine individuelle Kundennummer wird nicht erzeugt.

Rechnungsdatum

• Datum
  Legt das Datum der Rechnung fest.

  • Lieferdatum
    Legt das Lieferdatum fest.
  • Leistungsdatum
    Legt das Leistungsdatum fest.

• Lieferzeitraum
  Legt den Lieferzeitraum fest.

• Leistungszeitraum
  Legt den Leistungszeitraum fest.

• Kein Lieferdatum anzeigen
  Bei Auswahl dieser Option wird weder Lieferdatum, Leistungsdatum, Leistungszeitraum noch Lieferzeitraum auf der Rechnung angezeigt.

Rechnungsstatus

Eine Rechnung hat zu jedem Zeitpunkt genau einen der folgenden Status:

• draft: Die Rechnung befindet sich im Entwurfsmodus und ist editierbar.

• open: Die Rechnung wurde fertiggestellt und ist bereit für die Zustellung an den Rechnungsempfänger. Anmerkung: Die Bezeichnung "Open" bezieht sich auf den Zahlstatus der Rechnung.

• paid: Rechnung ist vollständig bezahlt

• voided: Die Rechnung wurde storniert.

Durch einen optionalen Parameter beim Aufruf kann eine Rechnung auch direkt im Status "open" angelegt werden.

Rechnungsarten

lexoffice unterstützt folgende Rechnungsarten:

• Brutto-/Netto-Rechnungen

  • Lesen & Anlegen per REST API möglich
  • Weitere Informationen über diese Rechnungsart

• §13b Bauleistung und Innergemeinschaftliche Lieferung (IgL) & Fremdleistungen

  • Lesen & Anlegen per REST API möglich
  • Weitere Informationen über diese Rechnungsart

• Steuerfrei/Kleinunternehmer

  • Lesen & Anlegen per REST API möglich.
  • Weitere Informationen über diese Rechnungsart

• Nicht Steuerbare Dienstleistungen

  • Lesender Zugriff auf Rechnungen dieses Typs per REST API möglich.
  • Weitere Informationen über diese Rechnungsart

• Dienstleistungen an Drittländer und Ausfuhrlieferungen an Drittländer

  • Lesender Zugriff auf Rechnungen dieses Typs per REST API möglich.
  • Weitere Informationen über diese Rechnungsart

• Abschlagsrechnung

  • Abschlagsrechnungen werden von der REST API weder lesend noch schreibend unterstützt.
  • Weitere Informationen über diese Rechnungsart

Kundenangaben

Im Bereich "Kundenangaben" einer Rechnung wird der Rechnungsempfänger oder Auftraggeber eingetragen.

lexoffice unterscheidet dabei zwischen Kunden (Menüpunkt "Kontakte") und einer "Einmal Rechnungsadresse". Kunden sind in den Stammdaten des lexoffice Accounts als Debitoren hinterlegt.

Einmal-Rechnungsadressen beziehen sich nur auf genau die Rechnung in der sie verwendet wurden.

Kopfbereich

Im Kopfbereich können Belegtitel und Einleitungstext eingetragen, und wenn gewünscht als Vorlage gespeichert werden.

Optional können diese Standardwerte über die REST API überschrieben werden.

Belegpositionen

Eine Rechnung kann beliebig viele Belegpositionen enthalten. Jede Belegposition besteht wiederum aus verschiedenen Attributen. Auf die Besonderheiten wird in diesem Abschnitt eingegangen.

Belegpositions-Typen

• Produkte & Services
  

• Manuelle Position
  Manuelle Positionen haben die selben Attribute wie Produkte oder Services. Sie werden allerdings lediglich im Kontext der Rechnung gespeichert.

• Freitextposition
  Freitextpositionen dienen der Strukturierung von Rechnungen. Sie enthalten zwei Attribute (Titel und Text).

Elemente einer Belegposition

• Titel
  Im Attribut Titel kann z.B. die Kurzbezeichnung der Rechnungsposition stehen.

• Text
  Im Attribut Text können optional ergänzende Informationen zur Rechnungsposition stehen.

• Menge
  Enthält die Anzahl der Rechnungsposition.

• Einheit
  Einheiten sind in lexoffice frei wählbar und gruppiert nach Produkt oder Service. Neue Einheiten werden on the fly zum jeweiligen Typ (Produkt oder Service) angelegt. Dies gilt sowohl für im Browser oder den mobile Apps angelegte Einheiten als auch per REST API hinzugefügte Einheiten.

• Preis
  Preis pro Einheit in EUR.

• Steuersatz
  lexoffice unterstützt die Steuersätze 0%, 5%, 7%, 16% und 19%.

• Rabatt
  Optional kann pro Belegposition ein prozentualer Rabatt gegeben werden.

• Gesamtrabatt
  Optional kann auf die Zwischensumme der Rechnung ein prozentualer oder absoluter Rabatt gegeben werden.

Fußbereich

Im Fußbereich von Rechnungen können die Zahlungsbedingungen zur Rechnung sowie eine Nachbemerkung hinterlegt werden.

• Zahlungsbedingungen
  In den Zahlungsbedingungen teilen Sie dem Rechnungsempfänger die Zahlungs-Modalitäten mit. Zahlungsbedingungen können auch als Vorlage gespeichert werden.

• Nachbemerkung
  Optional können Rechnungen mit einer abschließenden Nachbemerkung versehen werden. Nachbemerkungen können als Vorlage gespeichert werden.

Belegoptionen

• PayPal.Me-Link
  Optional kann eine Rechnung mit einem PayPal.Me-Link versehen werden.

• Sprache
  Rechnungen können mit mit einem Sprachkennzeichen versehen werden. Aktuell können mit lexoffice Rechnungen in deutscher und englischer Sprache erstellt werden.

FAQ und Hinweise

• Negative Werte in Belegpositionen sind möglich.

• Der Gesamtbetrag einer Rechnung darf nicht negativ sein.

• Jede per REST API angelegte Rechnung - draft oder open - verbraucht eine Rechnungsnummer aus dem Nummernkreis.

• Rechnungen vom Typ §13b Bauleistung, §13b Innergemeinschaftliche Lieferung (IgL) & Fremdleistungen erfordern die Verwendung von Kunden-Kontakten des Typs "Firma" mit valider Umsatzsteuer-ID als Referenz. Ansonsten wird ein Validierungsfehler geworfen.

• Rechnungen des Typs "Ausfuhrlieferung an Drittländer" und "Dienstleistungen an Drittländer" erfordern die Verwendung von Kunden-Kontakten. Das Kennzeichen "Steuerfreie Rechnung erlauben" muss aktiviert sein. Ansonsten wird ein Validierungsfehler geworfen.

• Per REST API können nur Rechnungen mit deutschem Sprachkennzeichen angelegt werden.

• Zur Anlage von Rechnungspositionen muss lediglich der Nettobetrag und der Steuersatz angegeben werden. Die Berechnung des Brutto- und Steuerbetrags übernimmt lexoffice.

• Hyperlinks auf spezifische Rechnungen sind über Deeplinks möglich.

• Download des Rechnungs-PDF einer Rechnung kann im Status "open", "paid" und "voided" erfolgen. Zum Download steht der files Endpunkt der REST API zur Verfügung. Die UUID des Rechnungs-PDF steht in der documentFileId.

• Im Response eines POST /v1/invoices steht die UUID der angelegten Rechnung. Mit der UUID kann auf die Rechnung per API zugegriffen werden. Zum Zugriff per Hyperlink auf eine Rechnung im Browser ist ebenfalls die UUID der Rechnung erforderlich.

• Sind alle oder einzelne Felder für Einleitungstext, Zahlungsbedingungen, Nachbemerkung im POST request einer Rechnung leer, setzt lexoffice den für das jeweilige Feld hinterlegten Defaultwert.

API Dokumentation

Die vollständige Dokumentation aller REST-Endpunkte und der verfügbaren Methoden finden Sie hier.