Skip to main content
POST
/
v2
/
datev-duo
/
buchungsvorschlag
Buchungsvorschlag
curl --request POST \
  --url https://api.business-os.de/v2/datev-duo/buchungsvorschlag \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "belegdatum": "2025-03-01T00:00:00Z",
  "waehrung": "EUR",
  "rechnungsordner": "Eingangsrechnungen",
  "belegnummer": "RE-2025-001",
  "betrag": 119,
  "positionen": [
    {
      "betrag": 119,
      "belegtext": "Büromaterial",
      "steuersatzProzent": 19,
      "skontoBetrag": 123,
      "skontoProzent": 123,
      "skontoBetrag2": 123,
      "skontoProzent2": 123,
      "kontoname": "<string>",
      "kontonummer": 123,
      "buSchluessel": "<string>",
      "kostenstelle1": "Marketing",
      "kostenstelle2": "IT-Abteilung"
    }
  ],
  "belegtyp": "EINGANGSRECHNUNG",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "adressen": [
    {
      "stadt": "<string>"
    }
  ],
  "bankkontonummer": 123,
  "bankleitzahl": "<string>",
  "bic": "DEUTDEFF",
  "iban": "DE89370400440532013000",
  "kontaktKontonummer": 123,
  "kontaktName": "<string>",
  "lieferdatum": "2023-11-07T05:31:56Z",
  "faelligkeitsdatum": "2023-11-07T05:31:56Z",
  "skontoZahlungsdatum": "2023-11-07T05:31:56Z",
  "skontoZahlungsdatum2": "2023-11-07T05:31:56Z",
  "zahlungsdatum": "2023-11-07T05:31:56Z",
  "istZahlungsauftrag": true,
  "notizen": "<string>",
  "bestellId": "<string>",
  "zahlungsbedingungenId": "<string>",
  "ustId": "<string>",
  "belegbilder": [
    {
      "content": "<string>",
      "dateiname": "rechnung.pdf"
    }
  ]
}
'
{
  "id": "<string>",
  "adressen": [
    {
      "stadt": "<string>"
    }
  ],
  "belegdatum": "2023-11-07T05:31:56Z",
  "belegtyp": "EINGANGSRECHNUNG",
  "kontaktKontonummer": 123,
  "kontaktName": "<string>",
  "erstellungsdatum": "<string>",
  "waehrung": "EUR",
  "lieferdatum": "2023-11-07T05:31:56Z",
  "skontoZahlungsdatum": "2023-11-07T05:31:56Z",
  "skontoZahlungsdatum2": "2023-11-07T05:31:56Z",
  "faelligkeitsdatum": "2023-11-07T05:31:56Z",
  "belegbilder": null,
  "iban": "<string>",
  "bankkontonummer": 123,
  "bankleitzahl": "<string>",
  "bic": "<string>",
  "istZahlungsauftrag": true,
  "rechnungsordner": "<string>",
  "positionen": [
    {
      "erstellungsdatum": "<string>",
      "belegtext": "<string>",
      "betrag": 123,
      "steuersatzProzent": 123,
      "skontoBetrag": 123,
      "skontoProzent": 123,
      "skontoBetrag2": 123,
      "skontoProzent2": 123,
      "kontoname": "<string>",
      "kontonummer": 123,
      "buSchluessel": "<string>",
      "kostenstelle1": "<string>",
      "kostenstelle2": "<string>"
    }
  ],
  "belegnummer": "RE-2025-001",
  "notizen": "<string>",
  "bestellId": "<string>",
  "zahlungsdatum": "2023-11-07T05:31:56Z",
  "zahlungsbedingungenId": "<string>",
  "aufgabenId": "<string>",
  "betrag": 119,
  "ustId": "<string>",
  "datevAntwort": {
    "status": "<string>",
    "information": [
      {
        "filename": "<string>",
        "message": "<string>",
        "timestamp": "2023-11-07T05:31:56Z",
        "type": "<string>"
      }
    ]
  },
  "business-os": {
    "neuesGuthaben": 499
  }
}

Authorizations

​
x-api-key
string
header
required

Dein Business OS API Key. Erstelle einen unter app.business-os.de → API Keys.

Query Parameters

​
connectionId
string<uuid>
required

UUID der DATEV-Verbindung. Abrufbar über den /connections-Endpunkt des jeweiligen Moduls (z. B. GET /v2/datev-duo/connections).

Example:

"abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145"

​
quelle
string
default:API

Kennzeichnung der Aufrufquelle für die Nutzungsanalyse. Standard bei Weglassen: API (direkter API-Aufruf). Für Automationen aus Make z. B. Make angeben.

Example:

"Make"

Body

application/json
​
belegdatum
string<date-time>
required

Belegdatum (z. B. Rechnungsdatum). ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).

Example:

"2025-03-01T00:00:00Z"

​
waehrung
string
required

Währungscode nach ISO 4217.

Example:

"EUR"

​
rechnungsordner
string
required

Name des Rechnungsordners. Muss zum Buchungstyp passen: bei EINGANGSRECHNUNG ein Kreditorenordner, bei AUSGANGSRECHNUNG ein Debitorenordner. Kann aus GET /v2/datev-duo/rechnungsordner (Feld bezeichnung) ausgelesen werden.

Example:

"Eingangsrechnungen"

​
belegnummer
string
required

Belegnummer / Rechnungsnummer.

Maximum string length: 36
Pattern: ^[a-zA-Z0-9$%&*+\-/]{0,36}$
Example:

"RE-2025-001"

​
betrag
number
required

Gesamtbetrag brutto (wie bei anderen DUO-Belegen). Darf nicht 0 sein und muss der Summe der Positionsbeträge (positionen[].betrag) entsprechen. Max. 10 Vorkomma- und 2 Nachkommastellen.

Example:

119

​
positionen
object[]
required

Belegpositionen — mindestens eine Position erforderlich.

Minimum array length: 1
​
belegtyp
enum<string>
required

EINGANGSRECHNUNG = Eingangsrechnung (Kreditor), AUSGANGSRECHNUNG = Ausgangsrechnung (Debitor).

Available options:
EINGANGSRECHNUNG,
AUSGANGSRECHNUNG
Example:

"EINGANGSRECHNUNG"

​
id
string<uuid>

Optionale UUID zur Zuordnung von hochgeladenen Dateien zum Buchungsvorschlag. Muss eine gültige UUID sein, wird andernfalls ignoriert.

​
adressen
object[]

Optionale Adressen.

​
bankkontonummer
number

Bankkontonummer (1–10 Ziffern). Wenn angegeben, ist bankleitzahl erforderlich.

​
bankleitzahl
string

Bankleitzahl. Wenn angegeben, ist bankkontonummer erforderlich.

Pattern: ^([1-9]|[0-9]{2,10})$
​
bic
string

BIC-Code.

Pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{0,3}$
Example:

"DEUTDEFF"

​
iban
string

IBAN.

Pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$
Example:

"DE89370400440532013000"

​
kontaktKontonummer
number

Kreditoren- oder Debitorennummer des Geschäftspartners.

​
kontaktName
string

Name des Geschäftspartners, max. 50 Zeichen.

Maximum string length: 50
​
lieferdatum
string<date-time>

Liefer- bzw. Leistungsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).

​
faelligkeitsdatum
string<date-time>

Fälligkeitsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Muss nach belegdatum liegen. Pflicht, wenn Skonto-Felder verwendet werden.

​
skontoZahlungsdatum
string<date-time>

Zahlungsziel für Skonto 1. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Muss vor faelligkeitsdatum und nach belegdatum liegen. Erfordert skontoBetrag und skontoProzent in jeder Position.

​
skontoZahlungsdatum2
string<date-time>

Zahlungsziel für Skonto 2. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Muss vor faelligkeitsdatum und nach skontoZahlungsdatum liegen. Erfordert zusätzlich skontoBetrag2 und skontoProzent2 in jeder Position.

​
zahlungsdatum
string<date-time>

Zahlungsdatum — markiert den Beleg als bezahlt. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).

​
istZahlungsauftrag
boolean

Ob automatisch eine Zahlungsanweisung (Überweisung bei EINGANGSRECHNUNG, Lastschrift bei AUSGANGSRECHNUNG) erstellt werden soll. Muss false sein, wenn zahlungsbedingungenId = 9.

​
notizen
string

Zusätzliche Notizen zum Buchungsvorschlag, max. 120 Zeichen.

Maximum string length: 120
​
bestellId
string

Bestell- bzw. Auftrags-ID.

Maximum string length: 30
Pattern: ^[a-zA-Z0-9$%&*+\-./]{1,30}$
​
zahlungsbedingungenId
string

Kennung der Zahlungsbedingungen (max. 3 Ziffern). Wenn gesetzt, dürfen keine Skonto-Felder verwendet werden.

Maximum string length: 3
Pattern: ^[0-9]{1,3}$
​
ustId
string

USt-IdNr. des Geschäftspartners.

Maximum string length: 15
Pattern: ^[0-9a-zA-Z. _]{1,15}$
​
ordnerVerwaltung
object

Optionale dreistufige Ordnerstruktur für die Belegablage. Ohne Angabe wird die Standardstruktur verwendet.

​
belegbilder
object[]

Optionale Belegdateien (z. B. PDF-Rechnungen).

Response

Buchungsvorschlag erfolgreich erstellt

​
id
string | null
​
adressen
object[] | null
​
belegdatum
string<date-time> | null
​
belegtyp
enum<string> | null
Available options:
EINGANGSRECHNUNG,
AUSGANGSRECHNUNG
Example:

"EINGANGSRECHNUNG"

​
kontaktKontonummer
number | null
​
kontaktName
string | null
​
erstellungsdatum
string | null
​
waehrung
string | null
Example:

"EUR"

​
lieferdatum
string<date-time> | null
​
skontoZahlungsdatum
string<date-time> | null
​
skontoZahlungsdatum2
string<date-time> | null
​
faelligkeitsdatum
string<date-time> | null
​
belegbilder
unknown
​
iban
string | null
​
bankkontonummer
number | null
​
bankleitzahl
string | null
​
bic
string | null
​
istZahlungsauftrag
boolean | null
​
rechnungsordner
string | null
​
positionen
object[] | null
​
belegnummer
string | null
Example:

"RE-2025-001"

​
notizen
string | null
​
bestellId
string | null
​
zahlungsdatum
string<date-time> | null
​
zahlungsbedingungenId
string | null
​
aufgabenId
string | null
​
betrag
number | null
Example:

119

​
ustId
string | null
​
datevAntwort
object

Ergebnis des DATEV-Async-Tasks. null, wenn kein Task gepollt wurde.

​
business-os
object