bimetricsEntwickler
Bankkonten

Bankkonto deaktivieren

Als Markdown ansehen

Benötigte Berechtigung:bankaccounts:write(Bankkonten aktivieren und deaktivieren)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/bankaccount/{id}/disable

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

Deaktiviert ein Bankkonto wie „Konto deaktivieren“ unter Einstellungen › Bank in der App. bimetrics holt danach keine Umsätze mehr für das Konto, sein Platz im Tarif wird frei. Bisherige Umsätze, Zuordnungen und Buchungen bleiben; filterBankTransactions liefert die Umsätze eines deaktivierten Kontos aber nicht. Die Bankfreigabe bleibt bestehen, getrennt wird nur in der App. Ist das Konto schon deaktiviert, ändert sich nichts. Läuft gerade der Abruf des Kontos, wartet die Route höchstens 5 Sekunden und antwortet dann mit 409 BankAccountBusy, ohne etwas zu ändern. Ein API-Schlüssel gehört immer einem Inhaber und darf deshalb wie in der App jedes Bankkonto der Firma schalten. Die Antwort ist das Konto, wie es danach gespeichert ist. Bei einer Wiederholung schickst du denselben Idempotency-Key. Ist er schon verarbeitet, läuft nichts erneut, und die Antwort zeigt den aktuellen Stand des Kontos; der kann inzwischen ein anderer sein, etwa disabled: true auf /enable.

Benötigt einen Schlüssel mit der Berechtigung bankaccounts: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 Bankkontos (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

Antworten

Erfolg.

application/json
  1. response

Ein mit bimetrics verbundenes Bankkonto.

IBAN?string

IBAN.

accountOwner?|

Diese Mitgliedschaft, ohne Personendaten.

accountOwnerId?string

ID der Mitgliedschaft, die das Konto verbunden hat.

Formatuuid
balance?integer

Saldo in Cent zum Zeitpunkt balanceDate.

balanceAvailable?boolean

Die Bank hat einen Saldo geliefert. Fehlt bei älteren Konten.

balanceCurrency?string

Währung des Saldos. Fehlt bei älteren Konten.

balanceDate?string

Zeitpunkt des Saldos.

Formatdate-time
bankName?string

Name der Bank.

companyId?string

ID der Firma.

Formatuuid
connected?boolean

Das Konto hat gerade eine Bankverbindung; ohne sie kommen Umsätze nur aus eingelesenen Kontoauszügen.

createdAt?string

Anlage in bimetrics.

Formatdate-time
currency?string

Kontowährung (ISO 4217).

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
disabled?boolean

Das Konto ist deaktiviert; seine Umsätze erscheinen nicht in filterBankTransactions.

displayName?string

Name des Kontos in bimetrics: der eigene Name, sonst aus den Angaben der Bank abgeleitet.

id?string

ID des Bankkontos.

Formatuuid
ownerName?string

Kontoinhaber laut Bank.

productName?string

Kontobezeichnung der Bank.

updatedAt?string

Letzte Änderung.

Formatdate-time
Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/bankaccount/497f6eca-6276-4993-bfeb-53cbbbba6f08/disable" -X POST \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001"
Beispielantwort
{  "IBAN": "DE89370400440532013000",  "accountOwner": {    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "createdAt": "2026-03-02T11:20:05Z",    "id": "53cd10a9-c864-4dc3-a777-9860d59efe6c",    "mcpAccess": "",    "role": "owner",    "status": "active",    "updatedAt": "2026-03-02T11:20:05Z",    "userId": "3ea56d84-7ca1-4a4f-88d4-428c62c8aee5"  },  "accountOwnerId": "53cd10a9-c864-4dc3-a777-9860d59efe6c",  "balance": 2465032,  "balanceAvailable": true,  "balanceCurrency": "EUR",  "balanceDate": "2026-09-27T05:00:12Z",  "bankName": "Commerzbank",  "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",  "connected": true,  "createdAt": "2026-03-02T11:48:30Z",  "currency": "EUR",  "deletedAt": null,  "disabled": true,  "displayName": "Geschäftskonto",  "id": "8faaa132-ef45-4af2-8dbb-a139b051f10f",  "ownerName": "Hansen & Kowalski Werbetechnik GmbH",  "productName": "Geschäftskonto",  "updatedAt": "2026-09-27T05:00:12Z"}

Bankkonto lesen GET

Liefert ein verbundenes Bankkonto mit Saldo. Benötigt einen Schlüssel mit der Berechtigung `read`.

Bankkonto aktivieren POST

Aktiviert ein Bankkonto wie „Konto aktivieren“ unter Einstellungen › Bank in der App. Liefert eine funktionierende Bankfreigabe der Firma das Konto, hängt bimetrics es an die jüngste davon, ohne die Bank zu fragen; neue Umsätze holt deren nächster Abruf. Gibt es keine, bleibt die Bindung, wie sie war: An einer getrennten Freigabe oder ganz ohne hat das Konto keine Bankverbindung (`connected` ist `false`), und Umsätze kommen nur aus Kontoauszügen, bis jemand in der App die Bank verbindet. Eine abgelaufene Freigabe erneuert man in der App. Ein aktives Konto mit Bankverbindung belegt einen Platz im Tarif. Ist keiner frei, antwortet die Route mit `402 LimitReached`, und das Konto bleibt deaktiviert. Ist es schon aktiv, ändert sich nichts. Läuft gerade der Abruf des Kontos oder eine andere Aktivierung, die die Plätze im Tarif zählt, wartet die Route höchstens 5 Sekunden und antwortet dann mit `409 BankAccountBusy`, ohne etwas zu ändern. Ein API-Schlüssel gehört immer einem Inhaber und darf deshalb wie in der App jedes Bankkonto der Firma schalten. Die Antwort ist das Konto, wie es danach gespeichert ist. Bei einer Wiederholung schickst du denselben Idempotency-Key. Ist er schon verarbeitet, läuft nichts erneut, und die Antwort zeigt den aktuellen Stand des Kontos; der kann inzwischen ein anderer sein, etwa `disabled: true` auf `/enable`. Benötigt einen Schlüssel mit der Berechtigung `bankaccounts:write`.