# Beleg-Upload (https://developer.bimetrics.de/beleg-upload)

Belege hochladen, ohne Doppelungen wiederholen und den Verarbeitungsstatus abfragen.

> **Achtung:** Erzeugt einen echten Beleg, verbraucht Kontingent und wird GoBD-protokolliert.

Teste den Upload deshalb mit einer Firma und einem Beleg, die du dafür vorgesehen hast. Die [Referenz](/referenz) bietet für den Upload bewusst keinen Testversand an.

## Voraussetzungen

* Ein Schlüssel mit der Berechtigung `upload` (in der App: **Belege hochladen**).
* `POST` an [`POST /api/document/`](https://developer.bimetrics.de/referenz/belege/upload-document.md) als `multipart/form-data`.
* Genau **eine Datei** je Anfrage, in genau einem dieser Felder:

| Feld        | Bedeutung                                                        |
| ----------- | ---------------------------------------------------------------- |
| `auto[]`    | bimetrics erkennt die Belegart selbst                            |
| `receipt[]` | Eingangsbeleg, etwa eine Rechnung eines Lieferanten              |
| `invoice[]` | Ausgangsrechnung, also eine Rechnung, die die Firma gestellt hat |

Weitere Formularfelder oder mehrere Dateien lehnt die API mit `400` ab. Unterstützt werden PDF, PNG, JPEG und Textformate wie XML-E-Rechnungen; die Art wird am Inhalt erkannt, nicht an der Dateiendung. Eine Datei darf höchstens 30 MiB groß sein; eine größere Datei ergibt `400`. Ist die ganze Anfrage größer als erlaubt, antwortet die API mit `413` (siehe [Limits](/limits)).

## Upload-ID

Jede Anfrage braucht den Header `X-Upload-Request-Id`: 1 bis 128 druckbare ASCII-Zeichen ohne Leerzeichen, zum Beispiel eine UUID oder die ID des Belegs in deinem System.

* Für jeden **neuen** Beleg eine **neue** ID verwenden.
* Bei einer **Wiederholung** derselben Übertragung ID, Datei, Dateiname und Feld gleich lassen.

```sh
curl --fail-with-body https://app.bimetrics.de/api/document/ \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "X-Upload-Request-Id: rechnung-2026-0001" \
  -F "auto[]=@rechnung.pdf"
```

## Sicher wiederholen

Firma, Schlüssel und Upload-ID bilden zusammen die Identität eines Uploads.

* Kommt dieselbe ID mit identischer Datei, gleichem Dateinamen und gleichem Feld erneut, liefert die API denselben Beleg zurück. Das gilt auch für parallele Anfragen. Die Wiederholung verbraucht kein weiteres Kontingent und startet keine zweite Verarbeitung.
* Kommt dieselbe ID mit anderem Inhalt, Dateinamen oder Feld, antwortet die API mit `409` und dem Code `UploadRequestConflict`. Das ist kein vorübergehender Fehler.
* Wurde der ursprüngliche Beleg inzwischen gelöscht, legt eine Wiederholung ihn nicht neu an, sondern antwortet ebenfalls mit `409`. Für einen neuen Upload brauchst du eine neue ID.
* Ein anderer Schlüssel bildet einen eigenen Bereich: Dieselbe ID mit einem neuen Schlüssel ist ein neuer Upload.

Wiederhole bei Zeitüberschreitung, Verbindungsabbruch, `5xx` und `429` (nach `Retry-After`) immer mit derselben ID.

## Antwort

Die Antwort ist ein Array mit genau einem Beleg (gekürzt):

```json
[
  {
    "id": "0b5c…",
    "uploadDocument": { "ocrStatus": "pending" }
  }
]
```

Liegt dieselbe Datei in der Firma schon vor, legt bimetrics keinen zweiten Beleg an. Die Antwort enthält dann den vorhandenen Beleg und `"duplicate": true`.

## Verarbeitung abfragen

Nach dem Upload erkennt bimetrics die Belegdaten im Hintergrund. Den Stand fragst du mit [`GET /api/document/{id}`](https://developer.bimetrics.de/referenz/belege/get-document.md) ab, im Feld `uploadDocument.ocrStatus`:

| Status         | Bedeutung                                                                           |
| -------------- | ----------------------------------------------------------------------------------- |
| `pending`      | Beleg gespeichert, Verarbeitung noch nicht gestartet                                |
| `processing`   | Verarbeitung läuft                                                                  |
| `success`      | Verarbeitung abgeschlossen, die erkannten Werte stehen im Beleg                     |
| `failed`       | Verarbeitung fehlgeschlagen, der Beleg bleibt gespeichert                           |
| `quota_paused` | Beleg gespeichert, Verarbeitung pausiert, weil das Belegkontingent ausgeschöpft ist |

Frage den Status in Abständen von einigen Sekunden ab und beachte die [Limits](/limits). Bei `quota_paused` war der Upload erfolgreich: Lade den Beleg nicht mit einer neuen ID erneut hoch.

## Nachvollziehbarkeit

Jeder Upload wird im Protokoll des Belegs als Upload über einen API-Schlüssel vermerkt und dem verwendeten Schlüssel zugeordnet. Die Originaldatei rufst du mit [`GET /api/document/{id}/content`](https://developer.bimetrics.de/referenz/belege/get-document-content.md) ab.