# Zuordnungsvorschläge lesen (https://developer.bimetrics.de/reference/matches/list-match-suggestions)

`POST https://app.bimetrics.de/api/match/suggestions`

operationId: `listMatchSuggestions` · Berechtigung (Scope): `read` · Bereich: Zuordnungen

Liefert die Vorschläge, die die App zu offenen Belegen und Umsätzen zeigt, für bis zu 20 auf einmal: Gegenstück, Begründung, offener Betrag danach und ob die App noch nachfragen würde. Es wird nichts zugeordnet. `anchors` hat einen Eintrag je Beleg und Umsatz, erst die Belege, je in der Reihenfolge der Anfrage, mit denselben Vorschlägen in derselben Reihenfolge wie einzeln, höchstens `limit` (1 bis 5, ohne Angabe 3). Ist ein Eintrag schon zugeordnet, steht die Zuordnung in `anchorMatchId`; lässt er sich nicht lesen oder trägt er manuelle Zahlungen, nennt `unavailable` den Grund. Beides stört die übrigen Einträge nicht. Vorschläge aus Buchungsvorlagen fehlen. Die Route vergleicht mit allen offenen Belegen und Umsätzen der Firma und hat deshalb ein eigenes Budget, siehe Limits.

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

### Authentifizierung

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

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

Belege und Umsätze, zu denen Vorschläge gelesen werden

Schema `MatchSuggestionsRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `documentIds` | Array<string> | IDs der Belege. |
| `limit` | integer | Höchstens so viele Vorschläge je Beleg oder Umsatz, 1 bis 5. Ohne Angabe 3. |
| `transactionIds` | Array<string> | IDs der Umsätze. |

### Beispiel

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

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: MatchSuggestions |
| 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 (`MatchSuggestions`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `anchors` | Array<MatchSuggestionAnchor>, kann null sein | Ein Eintrag je Beleg und Umsatz, erst die Belege, je in der Reihenfolge der Anfrage. |

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