bimetricsEntwickler
Kontakte

Kontakt anlegen

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.
post/api/contact/

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

Legt einen Kontakt ohne Bankverbindung an. Gleiche normalisierte USt-IdNr., externalRef oder gleicher Name ohne Rechtsform ergeben ContactDuplicate mit existingId. Nur eine Namensdublette kann mit forceDuplicate bestätigt werden.

Benötigt einen Schlüssel mit der Berechtigung contacts:write.

Authentifizierung

AuthentifizierungBearer <token>

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

In: header

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

TypeScript-Typen

Typ request body für TypeScript.

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

Antworten

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl --fail-with-body "https://app.bimetrics.de/api/contact/" \  -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"  }}

Originaldatei eines Belegs laden GET

Liefert die hochgeladene Originaldatei als Binärdaten. PDFs und Bilder kommen mit ihrem Typ (`application/pdf`, `image/png`, `image/jpeg`), alles andere, etwa XML-E-Rechnungen, als `application/octet-stream`. Der `ETag` ist der SHA-256 der Datei (Hex, ohne Anführungszeichen); mit genau diesem Wert in `If-None-Match` antwortet die Route mit `304` ohne Inhalt. `404`, wenn der Beleg keine Originaldatei hat oder gelöscht ist. Benötigt einen Schlüssel mit der Berechtigung `read`.

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