menu  icon Rechnungen

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

FeldnameTypOptionalMin.Max.Beschreibung
idString/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.
numberPrefixStringJa---10Der Präfix für die Rechnungsnummer z.B RE-.
numberString/IntNein------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.
contactIdStringNein------Die id des Kontakts bzw. Kunden an den die Rechnungen ausgestellt ist.
bruttoIntJa01Gibt an ob die Rechnung eine Bruttorechnung ist und ob die Positionen als Brutto angezeigt werden sollen 0 = nein, 1 = ja.
headTextStringNein12000Der Kopftext der Rechnung.
footerTextStringNein12000Der Fußtext der Rechnung.
vatTypeIntNein07Die Umsatzsteuerregelung. Hier finden Sie eine Liste aller Umsatzsteuerregelungen.
invoiceDateStringNein------Das Rechnungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
serviceDateStringNein------Das Leistungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
payGoalDateStringJa------Das Datum des Zahlungsziels im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
positionsArrayNein11000Die Rechnungspositionen. Die Datenstruktur der Rechnungspositionen finden Sie im nächsten Schritt.
paidString?---------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.
payedDecimal(10,2)---------payed gibt den Bruttobetrag an, der bereits für diese Rechnung bezahlt wurde. Dieser Wert ist ein reiner Rückgabewert.
totalDecimal(10,2)---------Der Rechnungs-Bruttobetrag. Dieser Wert ist ein reiner Rückgabewert.
totalWithoutTaxDecimal(10,2)---------Der Rechnungs-Nettobetrag. Dieser Wert ist ein reiner Rückgabewert.
totalTaxDecimal(10,2)---------Der Steuerbetrag. Dieser Wert ist ein reiner Rückgabewert.
createdString---------Das Erstellungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z. Dieser Wert ist ein reiner Rückgabewert.
statusString---------Der Status der Rechnung. Hier finden Sie eine Liste aller Rechnungsstatus. Dieser Wert ist ein reiner Rückgabewert.
xRechnungIntJa01Soll die Rechnung als XRechnung gespeichert werden? 0 = nein, 1 = ja.
xRechnungBuyerReferenceStringJa0255Wird bei XRechnungen benötigt. z.B Bestellnummer, Projektnummer oder Leitweg-ID.
xRechnungPaymentMeanStringJa------Wird bei XRechnungen benötigt. Zahlungsmittel

Rechnungsdaten - Positionen

FeldnameTypOptionalMin.Max.Beschreibung
idString/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.
productIdStringJa------Die id eines Produkts.
descriptionStringNein1255Die Bezeichnung der Position bzw. des Produkts / der Dienstleistung.
itemPriceDecimal(10, 2)Nein0.001---Der Netto-Einzelpreis des Produkts / der Dienstleistung.
amountDecimal(10, 3)Nein0.001---Die Menge des Produkts / der Dienstleistung.
taxDecimal(3, 2)Nein0100Die Umsatzsteuer in Prozent.
discountDecimal(3, 2)Nein0100Der Rabatt für diese Position in Prozent.
unitIntNein------Die id der Einheit. Hier finden Sie eine Liste aller Einheiten.
totalDecimal(10,2)---------Der Bruttobetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.
totalWithoutTaxDecimal(10,2)---------Der Nettobetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.
totalTaxDecimal(10,2)---------Der Steuerbetrag für diese Position. Dieser Wert ist ein reiner Rückgabewert.
totalDiscountDecimal(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

ParameterTypOptionalBeschreibung
pageIntNeinDie aktuelle Seite.
statusStringJaDer 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}

annotation info icon

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

annotation info icon

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 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

annotation info icon

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

ParameterTypOptionalBeschreibung
fromStringNeinDas Startdatum invoiceDate im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
toStringNeinDas 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.