lexoffice Public API Kochbuch - Buchhaltung
- Grundkonzept der lexoffice Buchhaltung
- Belegarten
- Kontakte
- Kategorien
- Unternehmens-Einstellungen
- Upload von Dateien zu Belegen
- Gruppierung von Rechnungspositionen für die Buchhaltung
- Berechnung der Steuerbeträge
- Änderbarkeit von Belegen
- Liste der unterstützten Kategorien
Grundkonzept der lexoffice Buchhaltung
Das Konzept der lexoffice Buchhaltung weicht von der im Buchhaltungs-Umfeld üblichen Verwendung von Soll, Haben und SKU Konten ab.
lexoffice teilt Buchungsbelege in vier Belegarten ein:
- Einnahmen
- Einnahmen-Minderungen
- Ausgaben
- Ausgaben-Minderungen
Zur weiteren Klassifizierung von Belegen verwendet lexoffice anstelle von SKU Konten sogenannte Kategorien wie z.B. “Warenverkauf”, “Einnahmen”, “Miete”, “Lohn” und viele mehr. Anmerkung: Kategorien sind im Hintergrund auf SKU Konten gemappt.
lexoffice verwendet Kategorien anstelle von SKU Konten, damit unsere Anwender - die in der Regel über kein Buchhaltungs-Wissen verfügen und auch nicht aufbauen wollen - Ein- und Ausgaben in einer umgangssprachlichen Form erfassen können.
Damit sich die per API und Web-UI angelegten Belege identisch verhalten, zieht sich das Belegarten- und Kategorien-Konzept bis in die Public API durch.
Hinweis: lexoffice unterstützt nur die Währung EUR sowie die Steuersätze 0%, 5%, 7%, 16% & 19%.
Abbildung: Formular zur Erfassung von Buchhaltungs-Belegen im lexoffice Web-UI
Belegarten
Einnahmebelege
Über Einnahmebelege werden in der Regel, die in vorgelagerten Anwendungen erstellten Rechnungen verbucht.
Beispiel: Ein Anwender betreibt einen Onlineshop, der auch die Rechnung erstellt. Diese Rechnung soll als Einnahme verbucht werden.
Einnahmen-Minderungs Belege
Über Einnahmen-Minderungs Belege werden in der Regel, die in vorgelagerten Anwendungen erstellten Einnahmen-Minderungen (ehemals Gutschriften) verbucht.
Beispiel: Im Onlineshop des Anwenders kommt es zu Retouren. Diese Retoure führt zu einer vollständigen oder teilweisen Erstattung des per Vorkasse erhaltenen Kaufbetrags. Der Onlineshop erstellt einen Einnahmen-Minderungs Beleg (ehemals Gutschrift), der verbucht werden soll.
Ausgabenbelege
Ausgabenbelege sind in der Regel Eingangs-Rechnungen, die verbucht werden sollen.
Beispiel: Rechnung über Telekommunikationsdienstleistungen, die als Ausgabe verbucht werden soll.
Ausgaben-Minderungs Belege
Dabei handelt es sich um Erstattungen bereits bezahlter Rechnungen.
Beispiel: Die Rechnung über Telekommunikationsdienstleistungen war zu hoch und der zuviel eingezogene Betrag wird erstattet. Die hieraus resultierende Ausgaben-Minderung soll verbucht werden.
Kontakte
Kunde, Lieferant, Kreditor, Debitor
Einnahmen & -Minderungen werden auf Kunden (Debitoren) und Ausgaben & -Minderungen auf Lieferanten (Kreditoren) gebucht.
Kunden und Lieferanten werden in lexoffice durch Kontakte repräsentiert. Kontakte sind über deren Eigenschaften als Lieferant (Kreditor) und / oder Kunde (Debitor) klassifiziert.
Einnahmen-Belege können mit Kontakten des Typs Kunde (Debitor) oder dem sogenannten Sammel-Kunden verknüpft werden.
Ausgaben-Belege können mit Kontakten des Typs Lieferant (Kreditor) oder dem sogenannten Sammel-Lieferanten verknüpft werden.
Zur Bearbeitung von Kontakten steht der contacts-Endpunkt zur Verfügung:
Sammel-Kunde, Sammel-Lieferant
Für manche Zwecke kann es sinnvoll sein, anstelle von dedizierten Kontakten, mit den Sammel-Kunden oder dem Sammel-Lieferanten zu arbeiten.
Beispiel: Ein Onlineshop generiert viele Rechnungen. Die Käufer sind in der Regel “Einmalkunden”, die nicht als Kontakt in lexoffice angelegt werden sollen. In diesem Fall können die Rechnungen unter Verwendung des Sammel-Kunden als Debitor als Einnahme-Beleg verbucht werden.
Hinweis: Bei Verwendung des Sammel-Kunden oder Sammel-Lieferanten wird der Umsatz auch dem Sammel-Kunden bzw. -Lieferanten zugeordnet.
Sammel-Kunde und Sammel-Lieferant sind Interna von lexoffice und können nicht per API gelesen oder verändert werden.
Bitte zu beachten: Der Sammel-Kunde und Sammel-Lieferant lässt sich zumeist nicht für die im Kapitel Häufige Sonderfälle beschriebenen Buchungs-Kategorien verwenden.
Kategorien
Kategorien & Steuersatz
Passend zu jeder Belegart stehen Kategorien und Steuersätze zur Verfügung. Eine Liste der zur Verwendung in der Public API zugelassenen Kategorien, sowie den möglichen Steuersätzen, befindet sich am Ende dieses Kochbuchs.
Bitte beachten Sie, dass JSON Payloads dahingehend validiert werden. Bei Validierungsfehlern kommt es zu einem HTTP 4xx Statuscode. Details entnehmen Sie bitte der API Dokumentation.
Häufige Sonderfälle
In der Buchhaltung ist mit diversen Sonderfällen zu rechnen.
Sonderfälle müssen in der Client-Anwendung erkannt und passend aufbereitet an lexoffice übermittelt werden.
Bauleistungen §13b
https://support.lexoffice.de/buchhaltungsbegriffe/was-ist-eine-bauleistungen-13b
Hier gilt es zu beachten, dass kein Sammel-Kunde / -Lieferant verwendet werden kann. Der verknüpfte Kontakt muss vom Typ Firma sein.Einnahmen als Kleinunternehmer
https://support.lexoffice.de/einstellungen/was-sind-kleinunternehmer
Sofern der Anwender der Client-Anwendung unter die Kleinunternehmer-Regelung (Unternehmens-Einstellungen) fällt, ist diese Kategorie anzuwenden.Innergemeinschaftliche Lieferung (IgL)
https://support.lexoffice.de/buchhaltungsbegriffe/was-ist-eine-innergemeinschaftliche-lieferungigl
Hier ist zu beachten, dass kein Sammel-Kunde / -Lieferant verwendet werden kann. Der verknüpfte Kontakt muss vom Typ Firma sein und über eine valide Umsatzsteuer-ID verfügen.Dienstleistungen an Drittländer
https://support.lexoffice.de/buchhaltungsbegriffe/was-sind-einnahmendienstleistungen-an-drittlander
Hier gilt es zu beachten, dass kein Sammel-Kunde / -Lieferant verwendet werden kann. Der verknüpfte Kontakt muss vom Typ Firma sein und eine Adresse im Ausland haben.Ausfuhrlieferungen an Drittländer
https://support.lexoffice.de/buchhaltungsbegriffe/was-sind-ausfuhrlieferungen-an-drittlander
Hier gilt es zu beachten, dass kein Sammel-Kunde / -Lieferant verwendet werden kann. Der verknüpfte Kontakt muss vom Typ Firma sein und eine Adresse im Ausland haben.Liefer- & Leistungszeitraum für Einnahmebelege
Ist ein Liefer-/Leistungsdatum oder Liefer-/Leistungszeitraum auf dem Einnahmebeleg angegeben, kommt das Feld "Leistungs-/ Lieferdatum" in lexoffice zum Einsatz. Im Fall von Zeiträumen muss der letzte Tag des im Beleg angegebenen Leistungs- oder Lieferzeitraums eingetragen werden. Ansonsten das im Beleg angegebene Liefer-/Leistungsdatum. Details dazu finden sich in unser FAQ:
https://support.lexoffice.de/de-form/articles/4311845-leistungsdatum-und-lieferdatum-in-lexoffice
Unternehmens-Einstellungen
In den “Allgemeinen Einstellungen” eines lexoffice Accounts werden die Unternehmens-Einstellungen vorgenommen.
U.a. auch, ob das Unternehmen Umsatzsteuerbefreit ist und die Kleinunternehmer-Regelung in Anspruch genommen wird.
Upload von Dateien zu Belegen
Zu Belegen können eine oder mehrere Dateien per API hochgeladen werden. Hierfür steht in der API eine Komfort-Funktion zur Verfügung, die den Datei-Upload gleich mit einem existierenden Beleg verknüpft.
Details zu dieser Funktion finden Sie hier: https://developers.lexoffice.io/docs/#vouchers-endpoint-upload-a-file-to-a-voucher
Gruppierung von Rechnungspositionen für die Buchhaltung
Nachfolgend dargestellt wird eine Rechnung, die mehrere Positionen mit unterschiedlichen Steuersätzen enthält. Dies ist sicherlich nicht der Regelfall, aber veranschaulicht das Konzept sehr gut.
Die dargestellte Rechnung wurde in der Client-Anwendung (z.B. ein Online-Shop oder einer Middleware) generiert und soll nun per API in die lexoffice Buchhaltung übergeben werden.
Das Konzept basiert auf der Gruppierung von Rechnungspositionen in der Client-Anwendung, bevor diese an lexoffice übermittelt werden.
Hier die Regeln zur Gruppierung:
- Gruppiere alle Rechnungspositionen einer Buchungskategorie (in diesem Fall “Einnahmen”) mit gleichem MwSt-Satz zusammen.
- Die Stückzahl der Positionen auf der Rechnung sind für die Buchhaltung nicht relevant.
Daraus resultiert folgender lexoffice Buchhaltungs-Beleg. Links ein Ausschnitt der Beispiel-Rechnung, rechts die Daten der Buchung:
Es ist zu erkennen, dass aus den vier Rechnungspositionen zwei voucherItems geworden sind. Gruppiert wurde in dem Fall nach Steuersatz (7% und 19%) und Buchungskategorie (“Einnahmen”).
Hier das JSON zum obigen Einnahme-Beleg:
Bitte halten Sie sich bei der Implementierung Ihrer Public API Schnittstelle an die Regeln zur Gruppierung.
Berechnung der Steuerbeträge
Spaltenmethode
Die Spaltenmethode bedeutet, dass in einer Nettorechnung zuerst alle Nettobeträge eines Steuersatzes summiert werden, und dann darauf der Steueranteil gerechnet wird. Alle Nettobeträge plus die Steueranteile ergeben den Bruttobetrag einer Rechnung.
Bei einer Bruttorechnung werden erst alle Bruttoanteile der Rechnung gruppiert nach Steuersatz summiert und dann wird die Steuer herausgerechnet. Die jeweilige Nettoanteil und die Steueranteile werden auf der Rechnung ausgewiesen.
Zeilenmethode
Im Gegensatz zur Spaltenmethode, ist ab und zu die Zeilenmethode anzutreffen.
Dort wird pro Zeile einer Rechnung zunächst der Steueranteil berechnet und dann werden bei einer Nettorechnung die Nettobeträge und die Steueranteile der einzelnen Zeilen summiert. Analog wird bei einer Bruttorechnung pro Zeile der Steueranteil herausgerechnet.
Daraus ergibt sich u.U. eine andere Summe der Rechnung als wenn diese nach der Spaltenmethode berechnet wird.
Änderbarkeit von Belegen
Unsere Public API bietet eine Möglichkeit zum Ändern von Belegen des Typs Einnahmen & Einnahmen-Minderungen an.
Die Änderung von Belegen per API wird verhindert wenn:
- Der Beleg als “Privat bezahlt” markiert wurde
- Der Beleg mit einer Banktransaktion verknüpft wurde
- Der Beleg mit einer Einnahme oder Ausgabe aus dem Kassenbuch verknüpft wurde
- Der Beleg festgeschrieben wurde. https://support.lexoffice.de/de-form/articles/2112437-festschreibung-richtig-gemacht
Ist ein Beleg nicht mehr änderbar, wird ein PUT {resourceurl}/v1/vouchers/{id} mit HTTP 406 oder HTTP 409 quittiert.
Liste der unterstützten Kategorien
Kategorie UUID | Bezeichnung | Steuersatz (in %) | Sammelkontakt möglich |
---|---|---|---|
8f8664a1-fd86-11e1-a21f-0800200c9a66 | Einnahmen | 0; 5; 7; 16; 19 | X |
8f8664a0-fd86-11e1-a21f-0800200c9a66 | Dienstleistung | 0; 5; 7; 16; 19 | X |
8f8664a4-fd86-11e1-a21f-0800200c9a66 | Honorar/Gage | 0; 5; 7; 16; 19 | X |
8f8664a8-fd86-11e1-a21f-0800200c9a66 | Warenverkäufe | 0; 5; 7; 16; 19 | X |
8f8664a3-fd86-11e1-a21f-0800200c9a66 | Erlösminderungen | 0; 5; 7; 16; 19 | X |
7a1efa0e-6283-4cbf-9583-8e88d3ba5960 | Einnahmen als Kleinunternehmer | 0 | X |
be32ceb3-684a-485e-b628-4bcc748bac4b | Bauleistungen §13b | 0 | - |
380a20cb-d04c-426e-b49c-84c22adfa362 | Fremdleistungen §13b | 0 | - |
9075a4e3-66de-4795-a016-3889feca0d20 | Innergemeinschaftliche Lieferung | 0 | - |
ef5b1a6e-f690-4004-9a19-91276348894f | Dienstleistungen an Drittländer | 0 | - |
93d24c20-ea84-424e-a731-5e1b78d1e6a9 | Ausfuhrlieferungen an Drittländer | 0 | - |
Weitere Infos zu den aktuell gültigen Steuersätzen finden Sie hier.
API Dokumentation
Die vollständige Dokumentation aller REST-Endpunkte und der verfügbaren Methoden finden Sie hier.