Nummer des Kontakts bestätigen
Benötigte Berechtigung:contacts:write(Kontakte anlegen und ändern)
Echte Wirkung
/api/contact/{id}/numbers/confirmKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Bestätigt, dass die USt-IdNr. oder IBAN zum Kontakt gehört, wie der Button „Behalten“ im Hinweis der App. Danach liefert GET /api/contact/{id}/numbers für diese Nummer null, bis der Kontakt eine andere bekommt. value ist die Nummer, die bestätigt wird. Hat der Kontakt inzwischen eine andere oder keine, antwortet die API mit 409 VersionConflict und bestätigt nichts. Ist field weder vatId noch iban oder ist value leer, antwortet sie mit 400 InvalidContactWrite. Der Kontakt selbst ändert sich nicht, auch nicht sein updatedAt.
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 Kontakts (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
Die Nummer, die beim Kontakt bleibt.
field?stringvatId oder iban.
"vatId""iban"value?stringDie Nummer, wie GET /api/contact/{id}/numbers sie in value geliefert hat.
Erfolg.
application/json- response
Abgleich der Nummern des Kontakts mit seinen Belegen, je Nummer ein Feld.
iban?|Abgleich der IBAN oder null.
vatId?|Abgleich der USt-IdNr. oder null.
curl --fail-with-body "https://app.bimetrics.de/api/contact/497f6eca-6276-4993-bfeb-53cbbbba6f08/numbers/confirm" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "iban": null, "vatId": null}USt-IdNr. und IBAN mit den Belegen abgleichen GET
Meldet, wenn eine andere USt-IdNr. oder IBAN auf mehr Belegen des Kontakts steht als seine eigene. So fallen Kontakte auf, die früher die Nummer einer anderen Firma übernommen haben, weil ein Beleg nur wegen eines ähnlichen Namens bei ihnen gelandet ist. Solange die Nummer beim Kontakt gespeichert ist, landen weiterhin Belege dieser Firma bei ihm. Die App zeigt das als Frage unter dem Feld. Ausgewertet werden die letzten 500 ausgelesenen Belege des Kontakts. Bei Eingangsbelegen ist er der Aussteller, bei Rechnungen der Empfänger. Die Nummer des Kontakts gilt als gefunden, wenn sie im Belegtext steht, auch wenn sie dort mit Leerzeichen, Punkten oder Bindestrichen geschrieben ist. Eine fremde USt-IdNr. erkennt bimetrics im Belegtext nur, wenn sie aus Deutschland, Österreich oder der Schweiz stammt. Als fremde IBAN gilt die IBAN, die bimetrics aus dem Beleg ausgelesen hat, sofern sie auch im Belegtext steht. Nummern der eigenen Firma zählen nicht. `documentIds` nennt die Belege mit der Nummer des Kontakts, `otherDocumentIds` die mit `other`, jeweils höchstens die 50 neuesten. `vatId` und `iban` sind `null`, wenn der Kontakt keine gültige Nummer hat, wenn keine andere Nummer auf mehr Belegen steht als seine eigene oder wenn jemand die Nummer mit `POST /api/contact/{id}/numbers/confirm` bestätigt hat. Gehört die Nummer nicht zum Kontakt, lässt sie sich mit `PUT /api/contact/{id}` entfernen. Die Belege der anderen Firma verschiebt `POST /api/document/bulk/counterparty` zum richtigen Kontakt. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.
Ähnliche Kontakte lesen GET
Liefert bis zu fünf andere Kontakte, die nach denselben Regeln wie bei der Zuordnung neuer Belege dieselbe Firma sein könnten, den ähnlichsten zuerst. Die App zeigt sie im Kontakt als Hinweis „Es gibt einen ähnlichen Kontakt“. Eine andere USt-IdNr. oder eine andere Rechtsform auf beiden Seiten schließt einen Kontakt aus, eine andere Postleitzahl oder eine Rechtsform nur auf einer Seite nicht. Gehören zwei Kontakte zur selben Firma, verschiebt `POST /api/contact/{id}/merge` die Belege des Kontakts `{id}` zum Kontakt `targetContactId`. `sourceId` und `targetId` nennen die Richtung, die die App dafür nimmt: vom Kontakt mit weniger Belegen zum Kontakt mit mehr. `movable` gibt an, wie viele Belege sich dabei verschieben lassen. Ist der Wert 0 und bleiben alle Belege endgültig, nennt `blockedBy` den häufigsten Grund: `exported` oder `issued`, `deleted` nur, wenn alle Belege storniert sind. Sonst fehlt das Feld, und die Vorschau nennt die Gründe. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.