bimetricsEntwickler
Kontakte

Kontaktangaben prüfen

Als Markdown ansehen

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

POST
/api/contact/check

Prüft IBAN, USt-IdNr. sowie PLZ und Ort wie beim Anlegen und Ändern eines Kontakts, ohne etwas zu speichern und ohne einen anderen Dienst zu fragen. ibanValid sagt, ob das Speichern die IBAN annimmt. hints sind dieselben Hinweise wie in der Antwort von createContact und updateContact. Ob eine USt-IdNr. aus dem EU-Ausland vergeben ist, prüft bimetrics weiter beim Speichern über VIES.

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.

Request-Body

application/json
  1. body

Angaben eines Kontakts zum Prüfen; gespeichert wird nichts.

city?string

Ort der ersten Anschrift.

country?string

Land des Kontakts als ISO-Code oder Name; nennt den Staat einer USt-IdNr. ohne Länderpräfix und die PLZ-Liste.

iban?string

IBAN, mit oder ohne Leerzeichen.

postalCode?string

PLZ der ersten Anschrift.

vatId?string

USt-IdNr.

Antworten

Erfolg.

application/json
  1. response

Ergebnis der Prüfung.

bank?

Nur bei einer gültigen deutschen oder österreichischen IBAN, deren Bankleitzahl bimetrics kennt: die Bank nach den Verzeichnissen der Deutschen Bundesbank bzw. der Oesterreichischen Nationalbank. bimetrics speichert sie nicht am Kontakt.

hints?array<>|

Hinweise, die nie sperren, wie in der Antwort von createContact und updateContact; leer, wenn es keine gibt.

ibanValid?boolean

Nur mit iban: true, wenn das Speichern die IBAN annimmt (bekanntes Land, genau dessen Länge, Prüfziffern), sonst false: Dann lehnt es sie mit 400 InvalidIban ab.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/contact/check" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "bank": {    "bic": "COBADEFFXXX",    "name": "Commerzbank"  },  "hints": [    {      "code": "vat_id_check_digit",      "field": "paymentInfo.vatId",      "params": {        "prefix": "DE"      }    },    {      "code": "postal_code_city",      "field": "addresses.0.city",      "params": {        "city": "Hamburg",        "postalCode": "20457"      }    }  ],  "ibanValid": true}

Kontakt anlegen POST

Legt einen Kontakt ohne Bankverbindung und steuerliche Art an; beides lässt sich danach mit updateContact ergänzen. Gleiche normalisierte USt-IdNr., externalRef oder gleicher Name ohne Rechtsform ergeben `409 ContactDuplicate` mit existingId. Nur eine Namensdublette kann mit forceDuplicate bestätigt werden. Benötigt einen Schlüssel mit der Berechtigung `contacts:write`.

Kontakte suchen POST

Sucht Kontakte (Kunden und Lieferanten) der Firma mit einem Filter und liefert eine Seite der Treffer. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.