Rechnungen über die belegFuchs API verwalten

Auf dieser Seite erfahren Sie, wie Sie Rechnungen über die API verwalten können.

API-Endpunkt

Der API-Endpunkt für Rechnungen lautet https://api.belegfuchs.de/v1/invoices.

Rechnungsdaten

Feldname	Typ	Optional	Min.	Max.	Beschreibung
id	String/Int	---	---	---	Bei der id handelt es sich um den PRIMARY_KEY. Das id-Feld wird automatisch bei der Erstellung gesetzt und kann nicht bearbeitet werden. Der Datentyp der id ist ein numerischer String. In API-Antworten wird also ein String zurückgegeben, der aber immer numerisch ist.
numberPrefix	String	Ja	---	10	Der Präfix für die Rechnungsnummer z.B RE-.
number	String/Int	Nein	---	---	Die auf Kontoebene eindeutige und fortlaufende Nummer des Kontakts. Int oder auto. number ist nicht der PRIMARY_KEY, sondern die Kontaktnummer die z.B auf Rechnungen dargestellt wird.
contactId	String	Nein	---	---	Die id des Kontakts bzw. Kunden an den die Rechnungen ausgestellt ist.
brutto	Int	Nein	0	1	Gibt an ob die Rechnung eine Bruttorechnung ist und ob die Positionen als Brutto angezeigt werden sollen 0 = nein, 1 = ja.
headText	String	Nein	1	2000	Der Kopftext der Rechnung.
footerText	String	Nein	1	2000	Der Fußtext der Rechnung.
vatType	Int	Nein	0	7	Die Umsatzsteuerregelung. Hier finden Sie eine Liste aller Umsatzsteuerregelungen.
invoiceDate	String	Nein	---	---	Das Rechnungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
serviceDate	String	Nein	---	---	Das Leistungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
payGoalDate	String	Ja	---	---	Das Datum des Zahlungsziels im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
positions	Array	Nein	1	1000	Die Rechnungspositionen. Die Datenstruktur der Rechnungspositionen finden Sie im nächsten Schritt.
paid	String?	---	---	---	Das Datum and dem die Rechnung vollständig bezahlt wurde, im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z. Wenn paid = null ist, wurde die Rechnung noch nicht oder nur teilweise bezahlt. Sie können diesen Wert nutzen, um zu prüfen, ob eine Rechnung vollständig bezahlt wurde. Dieser Wert ist ein reiner Rückgabewert.
payed	Decimal(10,2)	---	---	---	payed gibt den Bruttobetrag an, der bereits für diese Rechnung bezahlt wurde. Dieser Wert ist ein reiner Rückgabewert.
total	Decimal(10,2)	---	---	---	Der Rechnungs-Bruttobetrag. Dieser Wert ist ein reiner Rückgabewert.
totalWithoutTax	Decimal(10,2)	---	---	---	Der Rechnungs-Nettobetrag. Dieser Wert ist ein reiner Rückgabewert.
totalTax	Decimal(10,2)	---	---	---	Der Steuerbetrag. Dieser Wert ist ein reiner Rückgabewert.
created	String	---	---	---	Das Erstellungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z. Dieser Wert ist ein reiner Rückgabewert.
status	String	---	---	---	Der Status der Rechnung. Hier finden Sie eine Liste aller Rechnungsstatus. Dieser Wert ist ein reiner Rückgabewert.

Rechnungsdaten - Positionen

Feldname	Typ	Optional	Min.	Max.	Beschreibung
id	String/Int	---	---	---	Bei der id handelt es sich um den PRIMARY_KEY. Das id-Feld wird automatisch bei der Erstellung gesetzt und kann nicht bearbeitet werden. Der Datentyp der id ist ein numerischer String. In API-Antworten wird also ein String zurückgegeben, der aber immer numerisch ist.
productId	String	Ja	---	---	Die id eines Produkts.
description	String	Nein	1	255	Die Bezeichnung der Position bzw. des Produkts / der Dienstleistung.
itemPrice	Decimal(10, 2)	Nein	0.001	---	Der Netto-Einzelpreis des Produkts / der Dienstleistung.
amount	Decimal(10, 3)	Nein	0.001	---	Die Menge des Produkts / der Dienstleistung.
tax	Decimal(3, 2)	Nein	0	100	Die Umsatzsteuer in Prozent.
discount	Decimal(3, 2)	Nein	0	100	Der Rabatt für diese Position in Prozent.
unit	Int	Nein	---	---	Die id der Einheit. Hier finden Sie eine Liste aller Einheiten.
total	Decimal(10,2)	---	---	---	Der Bruttobetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.
totalWithoutTax	Decimal(10,2)	---	---	---	Der Nettobetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.
totalTax	Decimal(10,2)	---	---	---	Der Steuerbetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.
totalDiscount	Decimal(10,2)	---	---	---	Der Rabattbetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.

Rechnung erstellen

Um eine neue Rechnung zu erstellen, müssen Sie einen POST-Request an den Endpunkt senden.

Beispiel Payload

{
    "numberPrefix": "RE-",
    "number": "1000",
    "contactId": "1",
    "headText": "Vielen Dank für Ihren Einkauf!",
    "footerText": "Wir freuen uns auf Ihren nächsten Besuch.",
    "vatType": 0,
    "invoiceDate": "2023-12-31T00:00:00.000Z",
    "serviceDate": "2023-12-31T00:00:00.000Z",
    "payGoalDate": "2023-12-31T00:00:00.000Z",
    "positions": [
        {
            "productId": "1",
            "description": "Testprodukt",
            "amount": 1,
            "itemPrice": 99.99,
            "tax": 19,
            "discount": 7.5,
            "unit": 1
        }
    ]
}

Nummerverwaltung

Die Nummer einer Rechnung muss eindeutig und fortlaufend sein. Wenn Sie versuchen eine Rechnung mit einer Nummer zu erstellen, die bereits existiert oder die kleiner ist als die letzte Nummer, erhalten Sie einen 409 Conflict Fehler. Um dies zu verhindern, können Sie als number den wert auto übergeben. In diesem Fall wird automatisch die nächste freie Nummer oder 1 vergeben falls noch keine Rechnung existert.

Beispiel Payload mit automatischer Nummernvergabe

{
    "number": "auto",
    ...
}

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnung wurde erfolgreich erstellt. Die Antwort enthält die daten der erstellten Rechnung.
• 400 Bad Request : Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.
• 401 Unauthorized : Der API-Key ist ungültig.
• 409 Conflict : Es existiert bereits eine Rechnung mit der angegebenen Nummer.

Zahlungseingang buchen

Wie Sie Zahlungseingänge buchen können, erfahren Sie hier.

Rechnungen abrufen

Um alle Rechnungen abzurufen, müssen Sie einen GET-Request an den Endpunkt mit folgenden parametern senden:

https://api.belegfuchs.de/v1/invoices?page=1&status=Open

Parameter	Typ	Optional	Beschreibung
page	Int	Nein	Die aktuelle Seite.
status	String	Ja	Der Rechnungsstatus.

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnungen wurden erfolgreich abgerufen. Die Antwort enthält ein Array mit den Rechnungen.
• 401 Unauthorized : Der API-Key ist ungültig.

Einzelne Rechnung abrufen

Um eine einzelne Rechnung abzurufen, müssen Sie einen GET-Request an den Endpunkt mit folgenden parametern senden:

https://api.belegfuchs.de/v1/invoices/{invoiceId}

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnung wurde erfolgreich abgerufen. Die Antwort enthält die Daten der Rechnung.
• 401 Unauthorized : Der API-Key ist ungültig.

Rechnung stornieren

Um eine Rechnung zu stornieren, müssen Sie einen PUT-Request an den Endpunkt mit folgenden parametern senden:

https://api.belegfuchs.de/v1/invoices/{invoiceId}/cancel

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnung wurde erfolgreich storniert. Eine Stornorechnung wurde automatisch erstellt. Die Antwort ist null.
• 400 Bad Request : Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.
• 401 Unauthorized : Der API-Key ist ungültig.

Rechnung als PDF herunterladen

Um eine Rechnung als PDF herunterzuladen, müssen Sie einen GET-Request an den Endpunkt mit folgenden parametern senden:

https://api.belegfuchs.de/v1/invoices/{invoiceId}/pdf/download

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnung wurde erfolgreich als PDF heruntergeladen. Die Antwort enthält die PDF-Datei.
• 400 Bad Request : Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.
• 404 Not Found : Die Rechnung wurde nicht gefunden.
• 401 Unauthorized : Der API-Key ist ungültig.

Rechnungen innerhalb eines Zeitraums als .zip-Datei herunterladen.

Um Rechnungen innerhalb eines Zeitraums als .zip-Datei herunterzuladen, müssen Sie einen GET-Request an den Endpunkt mit folgenden parametern senden:

https://api.belegfuchs.de/v1/invoices/export?from=2023-12-31T00:00:00.000Z&to=2023-12-31T00:00:00.000Z

Parameter	Typ	Optional	Beschreibung
from	String	Nein	Das Startdatum invoiceDate im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
to	String	Nein	Das Enddatum invoiceDate im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnungen wurden erfolgreich als .zip-Datei heruntergeladen. Die Antwort enthält die .zip-Datei mit allen benannten Rechnungen, dessen Rechnungsdatum im angegebenen Zeitraum liegen.
• 400 Bad Request : Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.
• 404 Not Found : Es wurden keine Rechnungen im angegebenen Zeitraum gefunden.
• 401 Unauthorized : Der API-Key ist ungültig.

Rechnungsdaten-Vorschau

belegFuchs akzeptiert Beträge immer nur als Nettobetrag. Die Umsatzsteuer wird automatisch anhand des angegebenen Umsatzsteuersatzes berechnet. Die Rechnungsdaten-Vorschau gibt Ihnen die Möglichkeit, die Rechnungsdaten und somit auch den von der API berechneten Rechnungsbetrag zu überprüfen, bevor Sie die Rechnung erstellen.

Um eine Rechnungsdaten-Vorschau zu erhalten, müssen Sie einen POST-Request mit den Rechnungsdaten an folgenden Endpunkt senden:

https://api.belegfuchs.de/v1/invoices/preview

Antwort

Mögliche Antworten sind:

• 200 OK : Die Rechnungsdaten wurden erfolgreich überprüft. Die Antwort enthält die Rechnungsdaten und den von der API berechneten Rechnungsbetrag.
• 401 Unauthorized : Der API-Key ist ungültig.