# Bankkonto deaktivieren (https://developer.bimetrics.de/reference/bank-accounts/disable-bank-account)

`POST https://app.bimetrics.de/api/bankaccount/{id}/disable`

operationId: `disableBankAccount` · Berechtigung (Scope): `bankaccounts:write` · Bereich: Bankkonten

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

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Bankkontos (UUID). |
| `Idempotency-Key` | header | ja | 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. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/bankaccount/{id}/disable" -X POST \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: BankAccount |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 409 | Gerade läuft der Abruf dieses Kontos oder, beim Aktivieren, eine andere Aktivierung, die die Plätze im Tarif zählt (`BankAccountBusy`). Die Route wartet höchstens 5 Sekunden, geändert ist nichts. In einer Minute mit demselben Idempotency-Key erneut senden. `IdempotencyConflict` heißt dagegen, dass der Idempotency-Key schon für eine andere Anfrage benutzt wurde, etwa für ein anderes Konto. Dann einen neuen Key nehmen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`BankAccount`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `IBAN` | string | IBAN. |
| `accountOwner` | UserCompany | Diese Mitgliedschaft, ohne Personendaten. |
| `accountOwnerId` | string (uuid) | ID der Mitgliedschaft, die das Konto verbunden hat. |
| `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 (date-time) | Zeitpunkt des Saldos. |
| `bankName` | string | Name der Bank. |
| `companyId` | string (uuid) | ID der Firma. |
| `connected` | boolean | Das Konto hat gerade eine Bankverbindung; ohne sie kommen Umsätze nur aus eingelesenen Kontoauszügen. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `currency` | string | Kontowährung (ISO 4217). |
| `deletedAt` | string (date-time), kann null sein | Gilt als gelöscht seit diesem Zeitpunkt; `null`, solange nicht gelöscht. Gelöschte Einträge liefern nur die Suchrouten mit `includeDeleted`. |
| `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 (uuid) | ID des Bankkontos. |
| `ownerName` | string | Kontoinhaber laut Bank. |
| `productName` | string | Kontobezeichnung der Bank. |
| `updatedAt` | string (date-time) | Letzte Änderung. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
