# Buchungsvorlagen suchen (https://developer.bimetrics.de/reference/matches/filter-document-series)

`POST https://app.bimetrics.de/api/document/collection/series/filter`

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

Sucht die Buchungsvorlagen der Firma, etwa für Gewerbesteuer, Bankgebühren oder Privatentnahmen. Ihre IDs nimmt `createMatch` in `documentSeriesIds`: bimetrics legt beim Zuordnen eines Umsatzes aus der Vorlage einen Beleg an. Wie in der App fehlen Vorlagen, die zur Rechtsform nicht passen, und solche, die zum Löschen vorgemerkt sind.

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

Filter, Sortierung und Seite. Dokumentierte Filterattribute: `x-bimetrics-filter`.

Schema `FilterBody`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `attribute` | string | Filterattribut für `eq`, `in`, `range` und `oneof`, siehe `x-bimetrics-filter` der Operation. Groß-/Kleinschreibung und Punkte werden ignoriert. |
| `children` | Array<FilterDescriptor> | Teilfilter für `and`, `or` und `not`. |
| `direction` | string: `asc`, `desc` \| Array<string: `asc`, `desc`> | Richtung je Eintrag in `sort`; Standard `asc`. |
| `includeDeleted` | boolean | `true` liefert auch gelöschte Einträge, erkennbar an `deletedAt`, aber nur bei Belegen, Kontakten, Bankkonten, Umsätzen und Buchungen; die übrigen Suchrouten ignorieren das Feld. Ohne das Feld oder mit `false` nur Einträge, die nicht gelöscht sind. Für Abgleiche von Löschungen mit `range` auf `deletedAt`, siehe [Delta-Sync](https://developer.bimetrics.de/recipes/delta-sync). |
| `kind` | string: ``, `and`, `or`, `eq`, `not`, `in`, `range`, `oneof` | Art des Filters: `and`/`or` verknüpfen `children`, `not` verneint `children`, `eq` vergleicht `attribute` mit `value` (`null` prüft auf leer), `in` sucht `value` als Text im Attribut (enthält, ohne Groß-/Kleinschreibung), `range` prüft `lower` ≤ Attribut ≤ `upper` (eine Grenze genügt), `oneof` prüft, ob das Attribut einem Wert der Liste `value` entspricht. Leer: alle Einträge. |
| `limit` | integer | Treffer je Seite. Standard und Höchstwert 1000; größere Werte werden auf 1000 begrenzt. |
| `lower` | beliebig, kann null sein | Untergrenze für `range`, einschließlich. |
| `offset` | integer | Anzahl übersprungener Treffer. Haben mehrere Treffer dieselben Werte in `sort`, ist ihre Reihenfolge nicht festgelegt, und sie können zwischen zwei Seiten doppelt kommen oder fehlen; `id` als letztes Attribut in `sort` oder ein Abgleich mit Überlappung ([Delta-Sync](https://developer.bimetrics.de/recipes/delta-sync)) hilft dagegen. |
| `sort` | string \| Array<string> | Attribute, nach denen sortiert wird; nur sortierbare Attribute (`sortable` in `x-bimetrics-filter`). Ein Attribut mit `sortable: false` ergibt `400`. |
| `upper` | beliebig, kann null sein | Obergrenze für `range`, einschließlich. |
| `value` | beliebig, kann null sein | Vergleichswert: für `eq` ein Wert oder `null`, für `in` ein Text, für `oneof` eine Liste. |

### Filterattribute

| Attribut | Typ | Sortierbar | Beschreibung |
| --- | --- | --- | --- |
| `id` | uuid | ja | ID der Buchungsvorlage. |
| `friendlyName` | string | ja | Bezeichnung. |
| `collectionNumber` | string | ja | Nummer der Buchungsvorlage. |
| `kind` | string | ja | Art der erzeugten Belege: `receipt` (Eingangsbeleg) oder `invoice` (Ausgangsrechnung). |
| `issuer.name` | string | ja | Name des Ausstellers der erzeugten Belege. |
| `recipient.name` | string | ja | Name des Empfängers der erzeugten Belege. |
| `systemTemplateId` | uuid | ja | ID der Standardvorlage von bimetrics; `null` bei eigenen Vorlagen. |
| `updatedAt` | date-time | ja | Zeitpunkt der letzten Änderung. |

Dokumentiert sind diese Attribute für `attribute`; für `sort` nur die als sortierbar markierten.

Filterarten: `and`, `or`, `eq`, `not`, `in`, `range`, `oneof`.

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/document/collection/series/filter" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction":["asc","asc"],"limit":100,"offset":0,"sort":["friendlyName","id"]}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Eine Seite der Treffer. | `application/json`: DocumentSeriesFilterResult |
| 400 | Ungültige Suche, z. B. ein unbekanntes Filterattribut oder ein nicht sortierbares Attribut in `sort`; 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 (`DocumentSeriesFilterResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `items` | Array<DocumentSeries>, kann null sein | Die Treffer dieser Seite. |
| `limit` | integer, kann null sein | Verwendetes `limit`. |
| `offset` | integer | Verwendetes `offset`. |
| `total` | integer | Anzahl aller Treffer des Filters. |

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