# Belege für die Wahl einer Kostenstelle lesen (https://developer.bimetrics.de/reference/cost-centers/describe-cost-center-documents)

`GET https://app.bimetrics.de/api/cost-centers/documents`

operationId: `describeCostCenterDocuments` · Berechtigung (Scope): `read` · Bereich: Kostenstellen

Beschreibt bis zu 20 Belege so, wie die Prüfung vor dem DATEV-Export in der App sie zum Wählen einer Kostenstelle zeigt: Name, Rechnungsdatum, Bruttobetrag (`totalMinor`, in Cent), das Aufwands- oder Erlöskonto mit dem größten Betrag und die Kostenstellen, die der Kontakt schon hatte, seine Vorgabe zuerst (`suggestedCostCenterIds`). `locked` sagt, warum sich die Kostenstelle dort nicht wählen lässt: `exported` und `finalized` ändert man am Beleg mit Storno und Neubuchung, `contract` folgt seiner Dauerbuchung. Gesetzt wird die Kostenstelle mit `costCenterId` in `PATCH /api/document/{id}`. Die Belege stehen in der Reihenfolge der IDs, unbekannte, fremde und gelöschte fehlen. Mehr als 20 IDs lehnt die Route mit `400 CostCenterRejected` ab.

Benötigt einen Schlüssel mit der Berechtigung `read`.

### Authentifizierung

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

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `ids` | query | ja | string | Bis zu 20 Beleg-IDs, durch Komma getrennt, etwa aus `POST /api/document/filter` mit `costCenterId` gleich `null`. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/cost-centers/documents" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: Array<CostCenterDocument> |
| 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 |
| 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

Array aus `CostCenterDocument`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `account` | integer | Aufwands- oder Erlöskonto seiner Buchungen mit dem größten Betrag, fehlt ohne. |
| `accountName` | string | Name des Kontos. |
| `costCenterId` | string (uuid) | Kostenstelle oder Verteilung, die der Beleg inzwischen hat; fehlt ohne. |
| `currency` | string | Währung von `totalMinor`, solange bei einem Beleg in Fremdwährung der Euro-Betrag fehlt: der Betrag steht dann wie auf dem Beleg. Fehlt bei Euro. |
| `customerNumber` | integer | Kontaktnummer, fehlt ohne Kontakt. |
| `date` | string | Rechnungsdatum, fehlt ohne. |
| `draftId` | string (uuid) | Nur bei `invoice`: die Rechnung in der Rechnungsliste (`GET /api/draft/{id}`). |
| `id` | string (uuid) | ID des Belegs. |
| `invoiceNumber` | string | Rechnungsnummer. Vom Nutzer eingegebener Text. |
| `kind` | string | `invoice` für eine in bimetrics ausgestellte Rechnung, `receipt` für jeden anderen Beleg. |
| `locked` | string | `exported` oder `finalized`: Die Kostenstelle ändert sich nur mit Storno und Neubuchung am Beleg. `contract`: Der Beleg folgt seiner Dauerbuchung, die Kostenstelle kommt von dort. Fehlt sonst. |
| `name` | string | Lieferant oder Kunde. Vom Nutzer eingegebener Text. |
| `outgoing` | boolean | `true` bei einer Ausgangsrechnung, ausgestellt oder hochgeladen. |
| `suggestedCostCenterIds` | Array<string (uuid)>, kann null sein | Kostenstellen, die der Kontakt schon hatte, seine Voreinstellung zuerst. |
| `totalMinor` | integer | Bruttobetrag des Belegs in Cent, in Euro, außer `currency` nennt eine andere Währung. |

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