bimetricsEntwickler
Kontakte

Kontakt ändern

Als Markdown ansehen

Benötigte Berechtigung:contacts:write(Kontakte anlegen und ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
put/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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID des Objekts in dieser Firma (UUID).

Formatuuid

Header-Parameter

Idempotency-Key*string

Stabiler 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.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

application/json
  1. body

Kontakt anlegen oder gezielt ändern; ausgelassene Felder bleiben bei Änderungen erhalten.

addresses?array<>

Vollständige Liste der gewünschten Anschriften.

companyName?string

Name oder Firma des Kontakts.

contactInfo?

Gezielte Änderungen an Kontakt- und Kommunikationsdaten.

customerKind?string

Steuerlich: business (Unternehmen) oder private (Privatperson). Nur beim Ändern, beim Anlegen 400 InvalidContactWrite.

Wert in"business""private"
customerNumber?integer

Kundennummer. Ändern lässt sie sich nur, solange der Kontakt in keinem Beleg steht, sonst 409 CustomerNumberInUse.

defaultCostCenterId?string

Kostenstelle oder Verteilung für neue Belege des Kontakts als ID, ein leerer String entfernt sie. Eine archivierte wird abgelehnt. Ohne Angabe bleibt sie.

expectedUpdatedAt?string

Exakter zuletzt gelesener updatedAt-Wert einschließlich Sekundenbruchteilen; für Änderungen erforderlich.

Formatdate-time
externalRef?string

Stabile externe Kundenreferenz, höchstens 255 Zeichen.

forceDuplicate?boolean

Nur nach bewusster Prüfung einer Namensdublette verwenden; umgeht keine USt-IdNr.- oder externalRef-Dublette.

noReminders?boolean

Nicht 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?string

Kontaktart customer, supplier oder partner.

Antworten

Erfolg.

application/json
  1. response

Ein Kontakt: Kunde, Lieferant oder Partner.

addresses?array<>

Anschriften.

companyId?string

ID der Firma.

Formatuuid
companyName?string

Name.

contactInfo?

Kontaktdaten.

createdAt?string

Anlage in bimetrics.

Formatdate-time
customerKind?string

Steuerlich: business Unternehmen, private Privatperson. Fehlt, wenn unbekannt.

Wert in"business""private"
customerNumber?integer

Kunden- 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?string

Kostenstelle oder Verteilung, die neue Belege dieses Kontakts bekommen, solange sie noch keine haben. Fehlt ohne.

Formatuuid
deletedAt?|

Gilt als gelöscht seit diesem Zeitpunkt; null, solange nicht gelöscht. Gelöschte Einträge liefern nur die Suchrouten mit includeDeleted.

Formatdate-time
externalRef?string

Externe 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?string

ID des Kontakts.

Formatuuid
noReminders?boolean

Nicht 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?string

Zugang bei Anlage: web, api oder mcp.

type?string

Art des Kontakts.

Wert in"customer""supplier""partner"
updatedAt?string

Letzte Änderung.

Formatdate-time
vatCheck?

Letzte Prüfung der USt-IdNr. über VIES. Fehlt ohne Prüfung.

Beispielanfrage
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 '{}'
Beispielantwort
{  "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`.