Belege über die belegFuchs API verwalten

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

API-Endpunkt

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

Belegdaten

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.
receiptNumber	String	Nein	1	255	Die Belegnummer. (z.B eine Rechnungsnummer)
receiptDate	String	Nein	---	---	Das Belegdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
deliveryDate	String	Nein	---	---	Das Lieferdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z
vatType	Int	Ja	0	7	Die Umsatzsteuerregelung. Hier finden Sie eine Liste aller Umsatzsteuerregelungen. Bei Ausgabenbelegen wird aktuell nur vatType = 0 und vatType = 5 unterstützt.
income	Int	Nein	0	1	Der Belegtyp. 1 = Einnahme, 2 = Ausgabe.
contactId	String/Int	Nein	---	---	Die Kontakt-id, des Kunden oder Lieferanten.
positions	Array	Nein	1	1000	Die Belegpositionen. Die Datenstruktur der Rechnungspositionen finden Sie im nächsten Schritt.
files	Array	Ja	0	5	Die Anhänge. Die Datenstruktur der Anhänge finden Sie im übernächsten Schritt.

Belegdaten - 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.
description	String	Nein	1	255	Die Bezeichnung der Position bzw. des Produkts / der Dienstleistung.
tax	Decimal(3, 2)	Nein	0	100	Die Umsatzsteuer in Prozent.
price	Decimal(10, 2)	Nein	0.001	---	Der Netto-Betrag des Produkts / der Dienstleistung.
asInvestment	Int	---	0	1	Ob die Position als Anlage behandelt werden soll. 0 = Nein, 1 = Ja.
periodOfUse	Int	---	1	---	Gibt an über wieviele Jahre die Anlage abgeschrieben werden soll, falls asInvestment = 1.
categoryId	Int	Nein	---	---	Die id der Kontenrahmen Kategorie. Hier erfahren Sie, wie Sie alle verfügbaren Kategorien abrufen können.

Belegdaten - Anhänge

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.
fileType	String	Nein	---	---	Der MIME-Type der Datei.
fileName	String	Nein	1	255	Der Dateiname.
fileData	String	Nein	---	5MB	Die Datei als Base64 String.

Beleg erstellen

Um einen neuen Beleg zu erstellen, müssen Sie einen POST-Request an den Endpunkt senden.

Beispiel Payload

{
    "receiptNumber": "RE-1000",
    "contactId": "1",
    "income": 1,
    "vatType": 0,
    "receiptDate": "2023-12-31T00:00:00.000Z",
    "deliveryDate": "2023-12-31T00:00:00.000Z",
    "positions": [
        {
            "categoryId": 25, // Einnahmen / Erlöse
            "description": "",
            "asInvestment": 0,
            "periodOfUse": 0,
            "price": 100,
            "tax": 19
        }
    ],
    "files": [
        {
            "fileType": "image/jpeg",
            "fileName": "test.jpg",
            "fileData": "base64..."
        }
    ]
}

Antwort

Mögliche Antworten sind:

• 200 OK : Der Beleg wurde erfolgreich erstellt. Die Antwort enthält die daten des erstellten Belegs.
• 400 Bad Request : Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.
• 401 Unauthorized : Der API-Key ist ungültig.

Zahlungsein- und Ausgänge buchen

Wie Sie Zahlungen buchen können, erfahren Sie hier.

Belege abrufen

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

https://api.belegfuchs.de/v1/receipts?page=1&type=Income

Parameter	Typ	Optional	Beschreibung
page	Int	Nein	Die aktuelle Seite.
type	String	Ja	Der Belegtyp.

Antwort

Mögliche Antworten sind:

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

Einzelnen Beleg abrufen

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

https://api.belegfuchs.de/v1/receipts/{receiptId}

Antwort

Mögliche Antworten sind:

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

Belegdaten-Vorschau

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

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

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

Antwort

Mögliche Antworten sind:

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