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}
Die {invoiceId}
ist die id
der Rechnung, nicht die number
.
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
Die {invoiceId}
ist die id
der Rechnung, nicht die number
.
Antwort
Mögliche Antworten sind:
200 OK
: Die Rechnung wurde erfolgreich storniert. Eine Stornorechnung wurde automatisch erstellt. Die Antwort istnull
.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
Die {invoiceId}
ist die id
der Rechnung, nicht die number
.
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.