Kontakt ändern
Benötigte Berechtigung:contacts:write(Kontakte anlegen und ändern)
Echte Wirkung
/api/contact/{id}Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Ändert nur übergebene Felder; ausgelassene Unterfelder bleiben erhalten. expectedUpdatedAt muss dem gelesenen Kontakt entsprechen. Es gelten die Regeln des Kontaktformulars der App, wie über MCP: Bankverbindung, steuerliche Art, USt-IdNr., Land, Name und Anschrift lassen sich auch bei bereits verwendeten Kontakten ändern, die Kundennummer nur, solange der Kontakt in keinem Beleg steht (409 CustomerNumberInUse). Eine neue IBAN ohne die Länge ihres Landes oder mit falscher Prüfziffer lehnt die API mit 400 InvalidIban ab, eine neue E-Mail-Adresse, die der Versand nicht nehmen würde, mit 400 InvalidContactEmail; gespeicherte bleiben, leeren geht immer. Hinweise, die nie sperren, stehen in hints.
Benötigt einen Schlüssel mit der Berechtigung contacts:write.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID des Objekts in dieser Firma (UUID).
uuidIdempotency-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
Kontakt anlegen oder gezielt ändern; ausgelassene Felder bleiben bei Änderungen erhalten.
addresses?array<>Vollständige Liste der gewünschten Anschriften.
companyName?stringName oder Firma des Kontakts.
contactInfo?Gezielte Änderungen an Kontakt- und Kommunikationsdaten.
customerKind?stringSteuerlich: business (Unternehmen) oder private (Privatperson). Nur beim Ändern, beim Anlegen 400 InvalidContactWrite.
"business""private"customerNumber?integerKundennummer. Ändern lässt sie sich nur, solange der Kontakt in keinem Beleg steht, sonst 409 CustomerNumberInUse.
defaultCostCenterId?stringKostenstelle oder Verteilung für neue Belege des Kontakts als ID, ein leerer String entfernt sie. Eine archivierte wird abgelehnt. Ohne Angabe bleibt sie.
expectedUpdatedAt?stringExakter zuletzt gelesener updatedAt-Wert einschließlich Sekundenbruchteilen; für Änderungen erforderlich.
date-timeexternalRef?stringStabile externe Kundenreferenz, höchstens 255 Zeichen.
forceDuplicate?booleanNur nach bewusster Prüfung einer Namensdublette verwenden; umgeht keine USt-IdNr.- oder externalRef-Dublette.
noReminders?booleanNicht mahnen: Keine Rechnung an diesen Kontakt lässt sich mahnen, auch ausgestellte; false hebt es auf. Ohne Angabe bleibt der Wert.
paymentInfo?Steuer-, Bank-, Leitweg- und Lieferantenkennung; Bankdaten nur beim Ändern.
paymentTerms?Zahlungsziel und Skonto des Kunden für neue Rechnungen. Ersetzt beide: Ein ausgelassener Wert nimmt wieder den der Firma, {} leert beide. Ohne Angabe bleiben sie. Regeln verletzt: 400 BadRequest mit context.field, etwa paymentTerms.cashDiscount.days.
type?stringKontaktart customer, supplier oder partner.
Erfolg.
application/json- response
Ein Kontakt: Kunde, Lieferant oder Partner.
addresses?array<>Anschriften.
companyId?stringID der Firma.
uuidcompanyName?stringName.
contactInfo?Kontaktdaten.
createdAt?stringAnlage in bimetrics.
date-timecustomerKind?stringSteuerlich: business Unternehmen, private Privatperson. Fehlt, wenn unbekannt.
"business""private"customerNumber?integerKunden- bzw. Lieferantennummer; ergibt Debitor- und Kreditorkonto.
datevAccounts?Personenkonten des Kontakts im DATEV-Export, aus der Kundennummer abgeleitet wie die Buchungen; nur lesbar. In der Antwort von getContact, createContact und updateContact und je Treffer von filterContacts, nur wenn die Firma einen Kontenrahmen hat.
defaultCostCenterId?stringKostenstelle oder Verteilung, die neue Belege dieses Kontakts bekommen, solange sie noch keine haben. Fehlt ohne.
uuiddeletedAt?|Gilt als gelöscht seit diesem Zeitpunkt; null, solange nicht gelöscht. Gelöschte Einträge liefern nur die Suchrouten mit includeDeleted.
date-timeexternalRef?stringExterne Kunden- oder Lieferantenreferenz, in der App „Alte Nummer“, etwa die Kundennummer aus dem früheren Programm. Steht nie auf Belegen.
hints?array<>Hinweise zu Angaben des gespeicherten Kontakts, die nie sperren, etwa eine USt-IdNr. mit falscher Prüfziffer oder ein Ort, der nicht zur PLZ gehört. Nur in der Antwort von createContact und updateContact und nur, wenn es welche gibt.
id?stringID des Kontakts.
uuidnoReminders?booleanNicht mahnen: Keine Rechnung an diesen Kontakt lässt sich mahnen, auch ausgestellte. Fehlt, wenn aus.
paymentInfo?Zahlungsdaten.
paymentTerms?Eigenes Zahlungsziel und Skonto des Kunden. Fehlt, wenn er die Vorgaben der Firma nutzt.
source?stringZugang bei Anlage: web, api oder mcp.
type?stringArt des Kontakts.
"customer""supplier""partner"updatedAt?stringLetzte Änderung.
date-timevatCheck?Letzte Prüfung der USt-IdNr. über VIES. Fehlt ohne Prüfung.
curl --fail-with-body "https://app.bimetrics.de/api/contact/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "addresses": [ { "city": "Hamburg", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "country": "DE", "createdAt": "2026-03-18T10:02:51Z", "id": "181e7601-21c2-47fa-bffa-008d1113c6d8", "postalCode": "20457", "street": "Am Sandtorkai 12", "updatedAt": "2026-03-18T10:02:51Z" } ], "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "companyName": "Brauhaus Elbwiese GmbH", "contactInfo": { "contactPersonName": "Erika Mustermann", "email": "buchhaltung@brauhaus-elbwiese.de" }, "createdAt": "2026-03-18T10:02:51Z", "customerKind": "business", "customerNumber": 1004, "deletedAt": null, "externalRef": "customer-1042", "id": "b17e8812-eae4-49b6-b5dc-30510635cb07", "paymentInfo": { "vatId": "DE987654321" }, "source": "api", "type": "customer", "updatedAt": "2026-09-01T09:13:02Z", "vatCheck": { "checkedAt": "2026-03-18T10:02:53Z", "valid": true, "vatId": "DE987654321" }}Kontakt lesen GET
Liefert einen Kontakt mit Anschriften, Kontakt- und Zahlungsdaten. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.
Kontakt zusammenführen POST
Verschiebt die Belege des Kontakts `{id}` zum Kontakt `targetContactId`, wie „Mit anderem Kontakt zusammenführen“ in der App, höchstens 50 Belege je Aufruf, die ältesten zuerst; `remaining` nennt, was danach noch beim Kontakt bleibt. Jeder Beleg bekommt Name, USt-IdNr., IBAN, Adresse und Nummer des Kontakts wie bei `counterparty.contactId` in `PATCH /api/document/{id}`, und bimetrics bucht ihn sofort auf das Personenkonto des Kontakts um. Liegt eine Buchung in einem festgeschriebenen Monat, storniert bimetrics sie dort und bucht sie neu; `reversedFinalizedMonths` nennt die Monate. Ist ein Beleg einem Bankumsatz zugeordnet, bucht bimetrics die ganze Zuordnung neu. Trägt der Beleg genau die Kostenstelle, die am alten Kontakt für neue Belege hinterlegt ist (`defaultCostCenterId`), oder hat er keine, bekommt er die des neuen Kontakts oder keine. Jede andere bleibt. Wechselt die Kostenstelle, zieht eine Anlage des Belegs mit: Festgeschriebene Abschreibung storniert bimetrics und bucht sie neu; `reversedFinalizedMonths` nennt auch diese Monate. Eine erfasste Zahlung, etwa bar über das Kassenbuch, wird mit auf das neue Personenkonto umgebucht; der Kassenbuch-Eintrag bleibt unverändert. Übersprungen werden ausgestellte Rechnungen (`issued`, sie bleiben bei dem Kunden, an den sie gingen), an DATEV exportierte Belege (`exported`; auch wenn nur seine Zuordnung exportiert ist oder, wenn die Kostenstelle mit dem Kontakt wechselt, die Abschreibung seiner Anlage), Belege aus Dauerbuchungen (`contract`) oder Buchungsvorlagen (`linked`), Belege einer Zuordnung mit weiteren Belegen (`collective`, erst die Zuordnung lösen), Belege, die in Fremdwährung bezahlt, erstattet oder mit einer Gutschrift verrechnet sind (`paid`, erst die Zahlung zurücknehmen), Belege unter „Belegtyp prüfen“ (`kindReview`), Belege, die danach einen Buchungsfehler hätten, etwa Reverse Charge ohne USt-IdNr. am Kontakt (`issues`), noch nicht gelesene (`reading`), stornierte (`deleted`), Belege, die keine Rechnung und kein Eingangsbeleg sind (`otherKind`), Belege, die schon beim Zielkontakt sind (`unchanged`), und Belege, für die der Zielkontakt kein eigenes Personenkonto hat, weil seine Nummer bei einem Eingangsbeleg über 29999 oder bei einer Ausgangsrechnung über 59999 liegt (`numberRange`). Dazu `notFound` und `notPreviewed`. Mit `deleteSource` löscht bimetrics den Kontakt danach, wenn nichts mehr auf ihn verweist, weder ein Beleg noch eine Vorlage, Dauerbuchung, ein Angebot oder ein Entwurf, so wie das Löschen eines Kontakts in der App (`sourceDeleted`). Ohne `deleteSource` bleibt er bestehen. Höchstens 50 Belege je Aufruf (`400 BulkLimitExceeded`). Die Antwort nennt je Beleg, was geschah: `change` geändert, `skipped` mit Grund übersprungen, `failed` mit Code abgelehnt. Das ist ein Teilerfolg wie in der App: Ein abgelehnter Beleg hält die anderen nicht auf, und die Route antwortet mit `200`. Mit `dryRun` ändert sie nichts und zeigt, was geschähe, mit einer `version` je Beleg. Zum Ausführen gibst du diese als `expectedVersions` zurück, sonst antwortet die Route mit `400 ExpectedVersionRequired`. Es ändert sich nur, was unter `change` stand und seitdem unverändert ist: Ein geänderter Beleg kommt mit `VersionConflict` in `failed`, die übrigen laufen, und ein Beleg ohne Eintrag bleibt mit `notPreviewed` in `skipped`. Jeder Beleg läuft als eigener Befehl mit eigenem Eintrag im Protokoll und zählt einzeln auf die Tagesgrenzen der Firma und der Testphase. Der ganze Aufruf zählt einmal auf die Grenzen je Minute. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt und erledigt, was noch offen ist. Sie klärt auch den Stand, wenn ein Aufruf abbricht: `OutcomeUnknown` heißt, der Beleg kann schon gebucht sein. Benötigt einen Schlüssel mit der Berechtigung `documents:write`.