Firmendaten ändern
Benötigte Berechtigung:company:write(Firmendaten ändern)
Echte Wirkung
/api/company/Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Ändert die Firmendaten wie die Einstellungen der App, nur die genannten Felder, auch einzeln in address, contactInfo, accounting, invoiceDefaults und documentTexts. Sie gelten für neue Entwürfe und ab jetzt ausgestellte Belege; ausgestellte Belege behalten ihre Angaben. expectedVersion ist die version aus GET /api/company/; haben sich die Firmendaten seitdem geändert, antwortet die Route mit 409 CompanyVersionConflict und ändert nichts. Kontenrahmen, Versteuerung samt Befreiungsgrund und Bankverbindung änderst du nur in der App: Nennt der Anfrageinhalt ein solches oder ein unbekanntes Feld, antwortet die Route mit 400 CompanyFieldNotChangeable und dem Feld in context.field. Feste Texte (documentTexts) und der Fußtext der Rechnung (invoiceDefaults.closingText) nehmen nur druckbare Zeichen auf: Ein Emoji oder ein anderes Zeichen, das das PDF nicht drucken kann, ergibt 400 CompanyTextCharacters, context.character nennt es. Deshalb nehmen Firmentexte, die auf Rechnungen stehen, keine Bankdaten auf, weder eine IBAN noch Wörter wie BIC, Kontonummer oder Bankverbindung: Ein geänderter Text damit ergibt 400 CompanyTextBankDetails mit dem Feld in context.field; ein unveränderter gespeicherter Text bleibt. Es gelten dieselben Prüfungen wie in der App, etwa für den Start eines Nummernkreises (400 NumberStartTaken), die DATEV-Nummern (400 DatevNumberInvalid) und das Zahlungsziel von 0 bis 365 Tagen. Die Antwort ist die Firma wie bei GET, mit neuer version.
Benötigt einen Schlüssel mit der Berechtigung company:write.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Idempotency-Key*stringStabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.
^[!-~]+$1 <= length <= 128application/json- body
Die zu ändernden Firmendaten; nicht genannte Felder bleiben, wie sie sind.
accounting?Rechtliche Angaben, Nummernkreise, Skonto-Vorgabe, DATEV-Nummern, Art der Umsätze und Rechnungsabgrenzung.
address?Anschrift der Firma.
contactInfo?Kontaktangaben auf der Rechnung.
documentTexts?Feste Texte neuer Belege, je Belegart; einzeln änderbar.
expectedVersion?|version aus GET /api/company/, unverändert.
date-timeinvoiceDefaults?Vorgaben für neue Rechnungen.
legalForm?stringRechtsform als Code nach ISO 20275, z. B. 350 GmbH, 351 UG, 170 und 180 Einzelunternehmen; nur Codes aus der Liste der App.
name?stringFirmenname, höchstens 200 Byte.
Erfolg.
application/json- response
Die Firma des API-Schlüssels, wie die App sie in den Einstellungen führt.
accountingSystem?stringKontenrahmen, SKR03 oder SKR04; leer, solange keiner gewählt ist.
address?Anschrift der Firma wie auf der Rechnung.
companyId?stringID der Firma.
currency?stringBuchführungswährung, immer EUR.
documentTexts?Feste Texte neuer Belege, je Belegart; einzeln änderbar.
freeOfVatLiability?booleanNicht umsatzsteuerpflichtig; bei Kleinunternehmern ebenfalls true.
invoiceNumbers?Nummernkreis der Rechnungen; beim Ausstellen vergibt bimetrics die nächste freie Nummer.
legalForm?stringRechtsform als Code nach ISO 20275, z. B. 350 GmbH, 351 UG, 170 und 180 Einzelunternehmen; fehlt, solange keine eingetragen ist.
legalFormName?stringName der Rechtsform wie in der App, z. B. GmbH oder Einzelunternehmen.
managingDirectors?array<string>Geschäftsführung, Inhaber oder Vorstand, wie auf der Rechnung; fehlt, wenn die Rechnung keine nennt.
name?stringName der Firma.
proposalNumbers?Nummernkreis der Angebote.
register?Handelsregister wie auf der Rechnung.
salesKind?stringArt der Umsätze: services Dienstleistungen, goods Waren, both beides.
"services""goods""both"settings?Die Firmendaten, wie die Einstellungen der App sie ändern, in der Form von PATCH /api/company/.
smallBusiness?booleanKleinunternehmer nach § 19 UStG: Rechnungen ohne Umsatzsteuer, kein Vorsteuerabzug.
taxNumber?stringSteuernummer wie auf der Rechnung.
taxStatusHistory?array<>Versteuerung je Zeitraum nach einem Wechsel, älteste zuerst. Jede Buchung und Rechnung behält den Status ihres Leistungsdatums. Fehlt die Liste, gilt die heutige Versteuerung von Anfang an.
vatCashBasis?booleantrue bei Ist-Versteuerung (nach vereinnahmten Entgelten, § 20 UStG). Fehlt bei der Soll-Versteuerung, dem Standard. Gilt nur mit Umsatzsteuer und lässt sich nur in der App ändern.
vatId?stringUSt-IdNr. wie auf der Rechnung.
version?stringVersion der Firmendaten; PATCH /api/company/ nimmt sie unverändert als expectedVersion.
curl --fail-with-body "https://app.bimetrics.de/api/company/" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "accountingSystem": "SKR03", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "currency": "EUR", "documentTexts": { "invoiceRemark": "", "orderConfirmationNotes": "", "orderConfirmationRemark": "", "proposalNotes": "", "proposalRemark": "" }, "freeOfVatLiability": false, "invoiceNumbers": { "format": "RE-{YYYY}-{NNNN}", "start": 1 }, "legalForm": "350", "legalFormName": "GmbH", "managingDirectors": [ "Jana Hansen", "Piotr Kowalski" ], "name": "Hansen & Kowalski Werbetechnik GmbH", "proposalNumbers": { "format": "AN-{YYYY}-{NNNN}", "start": 1 }, "salesKind": "services", "settings": { "accounting": { "accrualAccountingMode": "automatic", "additionalLegalInfo": "", "commercialRegister": "", "datevClientNumber": "", "datevConsultantNumber": "", "invoiceNumberFormat": "RE-{YYYY}-{NNNN}", "invoiceNumberStart": 1, "managingDirectors": "Jana Hansen, Piotr Kowalski", "registrationCourt": "", "salesKind": "services", "taxId": "", "vatId": "" }, "address": { "cityName": "Hamburg", "countryCode": "DE", "lineOne": "Mühlenkamp 31", "lineThree": "", "lineTwo": "", "postcodeCode": "22303" }, "contactInfo": { "contactPersonName": "Jana Hansen", "email": "buchhaltung@hansen-kowalski.de", "phone": "+49 40 0000000", "website": "hansen-kowalski.de" }, "invoiceDefaults": { "closingText": "", "paymentTermDays": 30 }, "legalForm": "350", "name": "Hansen & Kowalski Werbetechnik GmbH" }, "smallBusiness": false, "version": "2026-11-04T09:31:12.481207Z"}Firma lesen GET
Liefert Name, Kontenrahmen, Buchführungswährung, Versteuerung, die Art der Umsätze und die Nummernkreise von Rechnungen und Angeboten, dazu die Rechtsform und die Stammdaten, die auf jeder Rechnung stehen: Geschäftsführung, Handelsregister, Anschrift, USt-IdNr. und Steuernummer. Leere Angaben fehlen. Diese Angaben liest auch `get_company_context` über MCP. Unter `settings` stehen die Firmendaten so, wie `PATCH /api/company/` sie nimmt, mit ihrer `version`. Benötigt einen Schlüssel mit der Berechtigung `read`.
Forderungsstände lesen GET
Liefert ausgestellte Rechnungen mit aktuellem Zahlungsstand, Korrekturkapazität und Aktionsfreigaben. Alle Geldwerte in EUR-Cent. Bei paymentKnown=false sind zahlungsabhängige Nullwerte keine bestätigten Nullbeträge; Mahnungen bleiben gesperrt. Benötigt einen Schlüssel mit der Berechtigung `sales:read` oder `read`.