bimetricsEntwickler
Kontakte

USt-IdNr. und IBAN mit den Belegen abgleichen

Als Markdown ansehen

Benötigte Berechtigung:contacts:read(Kontakte lesen)

GET
/api/contact/{id}/numbers

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.

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 Kontakts (UUID).

Formatuuid

Antworten

Erfolg.

application/json
  1. 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.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/contact/497f6eca-6276-4993-bfeb-53cbbbba6f08/numbers" \  -H "Authorization: Bearer $BIMETRICS_API_KEY"
Beispielantwort
{  "iban": null,  "vatId": {    "documentIds": [      "a2543540-c7ca-413d-8bcc-1ef3427e8aa4",      "a129ef0a-da5d-4204-804c-764d751bca95"    ],    "documents": 6,    "other": "DE123456788",    "otherDocumentIds": [      "3f5c1a2e-8b4d-4c6e-9a7f-1d2e3f4a5b6c",      "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",      "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"    ],    "value": "DE298765435",    "withNumber": 2,    "withOther": 3  }}

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. Übersprungen werden ausgestellte Rechnungen (`issued`, sie bleiben bei dem Kunden, an den sie gingen), an DATEV exportierte Belege, auch über eine Zuordnung (`exported`), Belege aus Dauerbuchungen (`contract`) oder Buchungsvorlagen (`linked`), Belege einer Zuordnung mit weiteren Belegen (`collective`, erst die Zuordnung lösen), Belege mit erfasster Bar- oder Privatzahlung (`paid`), 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`), und Belege, die schon beim Zielkontakt sind (`unchanged`). 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`.

Nummer des Kontakts bestätigen POST

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