Datentypen

Hier stehen die Datentypen der bimetrics API, der REST-API unter developer.bimetrics.de. Die MCP-Werkzeuge von bimetrics haben eigene Feldnamen und Formate. Für sie gelten ihre eigenen Beschreibungen und Schemas.

ÜberblickLink zu diesem Abschnitt kopieren

Welche Attribute sich filtern lassen und welchen Typ sie haben, steht unter Filtern und Paginieren.

KalenderdatenLink zu diesem Abschnitt kopieren

Rechnungsdatum, Fälligkeit, Buchungstag und ähnliche Angaben sind Kalenderdaten ohne Uhrzeit und ohne Zeitzone. In Antworten kommen sie als Objekt:

{ "invoiceDate": { "year": 2026, "month": 9, "day": 30 } }

Fehlt ein Datum, etwa solange ein Beleg noch nicht erkannt ist, ist der Wert null.

In Filtern schreibst du ein Kalenderdatum als String im Format JJJJ-MM-TT, mit führenden Nullen und ohne Uhrzeit:

{ "kind": "range", "attribute": "invoiceDate", "lower": "2026-09-01", "upper": "2026-09-30" }

• range schließt beide Grenzen ein. Das Beispiel trifft alle Belege mit einem Rechnungsdatum im September 2026.
• Die API vergleicht Kalenderdaten Zeichen für Zeichen in diesem Format. Andere Schreibweisen lehnt sie hier nicht ab, sie liefern aber falsche Treffer. So schließt 2026-09-01T00:00:00Z als Untergrenze den 1. September aus.
• Eine Zeitzone spielt keine Rolle: Ein Filter auf invoiceDate trifft das Datum, das auf dem Beleg steht.

Welches Datum was bedeutetLink zu diesem Abschnitt kopieren

Erstreckt sich der Leistungszeitraum eines Belegs über mehrere Monate, verteilt bimetrics den Betrag auf diese Monate. Die Buchungen tragen den jeweiligen Zeitraum dann in performanceFrom und performanceTo.

ZeitpunkteLink zu diesem Abschnitt kopieren

createdAt, updatedAt, finalized und ähnliche Angaben sind Zeitpunkte. Sie kommen als String nach RFC 3339 mit Zeitzone, auf Mikrosekunden genau:

{ "updatedAt": "2026-09-27T08:15:42.123456Z" }

In Filtern schreibst du Zeitpunkte ebenfalls nach RFC 3339, zum Beispiel 2026-09-01T00:00:00Z oder 2026-09-01T00:00:00+02:00.

• Gib die Zeitzone immer mit an. Einen Wert ohne Zeitzone oder ohne Uhrzeit, etwa 2026-09-01, liest die Datenbank in ihrer eigenen Zeitzone. Darauf solltest du dich nicht verlassen.
• Einen Zeitpunkt aus einer Antwort kannst du unverändert als Filterwert verwenden. Das nutzt der Delta-Sync.
• Die API nimmt auch die übrigen Formen nach ISO 8601 an: ein Leerzeichen statt T, eine Uhrzeit ohne Sekunden, einen Wert ohne Zeitzone oder nur ein Datum, etwa 2026-09-01 08:15. Andere Schreibweisen, etwa 01.09.2026, ergeben 400.

BeträgeLink zu diesem Abschnitt kopieren

Beträge in CentLink zu diesem Abschnitt kopieren

Die meisten Beträge sind Ganzzahlen in Cent: 11900 steht für 119,00 €.

Den Bruttobetrag eines Belegs erhältst du als Summe von total über alle invoicePositions; gebucht wird er immer als Euro. Die Währung steht bei Umsätzen in transactionCurrency und bei Bankkonten in currency. Ist ein Beleg in einer anderen Währung als Euro, nennt sie documentCurrency (ISO 4217, fehlt bei Euro), den Bruttobetrag vom Beleg originalTotalAmount in Hundertsteln dieser Währung, und euroAmountSource sagt, woher der Euro-Betrag stammt: payment aus der Zahlung, person selbst eingetragen oder bestätigt. Fehlt euroAmountSource, sind die Positionen noch der Betrag vom Beleg („Euro-Betrag fehlt“).

In Filtern gibst du Cent-Beträge als Zahl an, etwa { "kind": "range", "attribute": "transactionAmount", "upper": -10000 } für Ausgänge ab 100,00 €.

Beträge von BuchungenLink zu diesem Abschnitt kopieren

Das Feld amount einer Buchung ist ein Betrag in Euro als Dezimalzahl im String, zum Beispiel "119", "-19.5" oder "1234.56".

• Das Vorzeichen bezieht sich auf das Konto in account: größer als 0 ist Soll, kleiner als 0 ist Haben. Das Gegenkonto accountContra hat die umgekehrte Seite.
• Die Zahl hat keine feste Anzahl an Nachkommastellen. 119,00 € kommt als "119", 19,50 € als "19.5".
• Lies den Wert als Dezimalzahl, nicht als Gleitkommazahl, damit keine Rundungsfehler entstehen.
• netAmount und taxAmount teilen amount in Netto und Steuer, im selben Format und mit demselben Vorzeichen, auf Cent gerundet. Sie stehen nur in den Antworten der Buchungsrouten, nicht in bookings an Belegen und Umsätzen.

Beträge von Buchungen in Filtern: Die API vergleicht amount in Filtern und beim Sortieren als Text. Ein Filterwert muss deshalb ein String in genau der Schreibweise aus den Antworten sein, also "119" und nicht "119.00" oder 119. range und sort nach amount ergeben keine Reihenfolge nach Betrag. Filtere und sortiere Beträge von Buchungen deshalb in deiner Anwendung.

ProzentsätzeLink zu diesem Abschnitt kopieren

Prozentsätze sind Dezimalzahlen im String und bedeuten Prozent, nicht Anteile: "19" steht für 19 %, "5.5" für 5,5 %. Das gilt für den Steuersatz einer Position (vatPercentage), den Skontosatz (cashDiscount.percent) und den Steuersatz einer Buchung (taxRate, "0" ohne Steuer).

Nur die Anteile einer Verteilung von Kostenstellen sind ganze Zahlen in Basispunkten (shares[].basisPoints): 5000 sind 50 %, 3333 sind 33,33 %, zusammen ergeben sie 10000.

IDsLink zu diesem Abschnitt kopieren

Alle IDs sind UUIDs als String, zum Beispiel "0b5c2f4e-8a1d-4c3e-9f6a-2d7b1e8c4a90".

• Eine ID im Pfad, die keine UUID ist, ergibt 400.
• Eine ID, die zu einer anderen Firma gehört, ergibt 401 mit dem Code Unauthorized (siehe Fehler).
• In Filtern schreibst du UUIDs als String. Ein Wert, der keine UUID ist, ergibt 400.

Feste WerteLink zu diesem Abschnitt kopieren

Felder mit einer festen Liste von Werten sind Strings, zum Beispiel:

Die Werte je Feld stehen in der Referenz. Plane in deiner Anwendung einen Standardfall für Werte ein, die du nicht kennst.

Leere WerteLink zu diesem Abschnitt kopieren

• Felder, die in der Referenz als „kann null sein“ markiert sind, kommen als null, wenn es keinen Wert gibt.
• Einige Felder fehlen ganz, statt null zu sein, zum Beispiel duplicate beim Upload oder cashDiscount ohne Skonto. Die Beschreibung des Felds nennt das.
• Mit { "kind": "eq", "attribute": "…", "value": null } findest du Einträge ohne Wert.