# Abgang einer Anlage buchen (https://developer.bimetrics.de/reference/assets/dispose-asset)

`POST https://app.bimetrics.de/api/assets/{id}/disposal`

operationId: `disposeAsset` · Berechtigung (Scope): `documents:write` · Bereich: Anlagen

Bucht den Abgang wie die Vorschau: die AfA bis zum Abgangsmonat (er zählt voll und trägt den Abgangstag), den Restwert am Abgangstag auf das Konto nach Art und Ergebnis gegen das Anlagekonto. Spätere Monate werden entfernt oder storniert. Beim Verkauf an der Rechnung bekommen ihre Positionen die Kategorie `asset_sale` (Anlagenverkauf), und die Rechnung bucht neu: Offenes wird ersetzt, Festgeschriebenes mit seinem Datum storniert und neu gebucht. `expectedVersion` ist Pflicht. Bei einer Wiederholung schickst du denselben Idempotency-Key.

Benötigt einen Schlüssel mit der Berechtigung `documents: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 der Anlage (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. |

### Request-Body (`application/json`)

the disposal

Schema `AssetDisposalRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `confirmPriorYear` | boolean | `true` bestätigt einen Abgangstag im Vorjahr; er ändert dessen Gewinn. |
| `date` | NaiveDate | Abgangstag, der Tag der Lieferung, nicht in der Zukunft. Beim Verkauf an der Rechnung ohne Angabe ihr Lieferdatum, sonst Pflicht. |
| `dealerDocumentId` | string (uuid) | Verkauf, den der Händler mit seiner Rechnung oder Gutschrift (Eingangsbeleg) verrechnet. Noch nicht möglich: Die Route lehnt ihn ab. |
| `expectedVersion` | string | Pflicht: `version` der Anlage, wie zuletzt gelesen. |
| `invoiceId` | string (uuid) | Verkauf an einer Ausgangsrechnung: die Rechnung. |
| `invoiceVersion` | string | Mit `invoiceId` Pflicht: die zuletzt gelesene Version der Rechnung. |
| `kind` | string: `sale`, `scrap` | Pflicht: `sale` (Verkauf) oder `scrap` (Verschrottung). |
| `positions` | Array<integer> | Mit `invoiceId` Pflicht: die Positionen, die die Anlage verkaufen, ab 0; 19 % oder als Kleinunternehmer ohne Umsatzsteuer. |
| `proceedsNetCents` | integer | Verkauf ohne eigene Rechnung: Erlös netto in Cent. |
| `reason` | string | Bei der Verschrottung Pflicht: der Grund, höchstens 500 Zeichen. |
| `vatCents` | integer | Verkauf ohne eigene Rechnung: 19 % Umsatzsteuer auf den Erlös, beim Kleinunternehmer keine in Cent. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/assets/{id}/disposal" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: AssetDisposed |
| 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 diese Route (`APIKeyPermissionDenied`), 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 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `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 (`AssetDisposed`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `asset` | Asset | Die Anlage. |
| `replayed` | boolean | `true` bei einer Wiederholung. |

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