# Schnellstart (https://developer.bimetrics.de/schnellstart)

API-Schlüssel anlegen und den ersten Aufruf senden.

## 1. Schlüssel anlegen

Das geht nur als Inhaber der Firma und mit einem gültigen bezahlten Tarif oder einer Freischaltung durch bimetrics.

1. Öffne in der App **Einstellungen › API** ([app.bimetrics.de/settings/api-keys](https://app.bimetrics.de/settings/api-keys)).
2. Wähle **Schlüssel erstellen** und vergib einen Namen, zum Beispiel den Namen deiner Anwendung.
3. Wähle die Berechtigungen: **Daten lesen** (`read`) und bei Bedarf **Belege hochladen** (`upload`).
4. Wähle die Gültigkeit (30, 90 oder 365 Tage) und bestätige mit deinem aktuellen Passwort.

Der Schlüssel beginnt mit `bm_` und wird nur einmal angezeigt. Alle Inhaber der Firma erhalten eine E-Mail über den neuen Zugang.

> **Schlüssel sicher aufbewahren:** Wer den Schlüssel kennt, kann bis zum Ablauf alle Daten der Firma lesen und, mit der Berechtigung `upload`, Belege hochladen. Lege ihn nur serverseitig ab, etwa in einer Umgebungsvariable oder einem Secret-Store, nie im Frontend-Code. Mehr dazu unter [Authentifizierung](/authentifizierung).

## 2. Ersten Aufruf senden

Speichere den Schlüssel als Umgebungsvariable und frage Tarif und Kontingent ab. Der Aufruf ändert nichts und eignet sich als Test.

```sh
export BIMETRICS_API_KEY='bm_…'

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

Die Antwort enthält unter anderem den Tarif und die Nutzung im laufenden Zeitraum (gekürzt):

```json
{
  "active": true,
  "tier": "team",
  "period": { "start": "2026-09-01T00:00:00Z", "end": "2026-10-01T00:00:00Z" },
  "usage": { "documentsPeriod": 42 }
}
```

Die Firma ergibt sich aus dem Schlüssel. Eine Firmen-ID schickst du nie mit.

## 3. Daten lesen

Belege, Kontakte, Bankkonten, Umsätze und Buchungen suchst du mit einer Filteranfrage. Dieses Beispiel liefert die ersten 20 Belege ohne weitere Bedingung:

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

Die Antwort hat die Form `{ "total": …, "limit": …, "offset": …, "items": [ … ] }`. Wie du filterst, sortierst und blätterst, steht unter [Filtern und Paginieren](/filtern).

## Wie es weitergeht

* [Authentifizierung und Scopes](/authentifizierung): Header, Berechtigungen, Laufzeit und Widerruf.
* [Fehler](/fehler) und [Limits](/limits): was bei `4xx`, `5xx` und `429` zu tun ist.
* [Beleg-Upload](/beleg-upload): Belege ohne Doppelungen einreichen.
* [API-Referenz](/referenz): alle Endpunkte, mit Playground zum Ausprobieren.