# Beleg hochladen (https://developer.bimetrics.de/reference/documents/upload-document)

`POST https://app.bimetrics.de/api/document/`

operationId: `uploadDocument` · Berechtigung (Scope): `upload` · Bereich: Belege

Lädt genau eine Datei als neuen Beleg hoch und stößt die Erkennung an. Die Antwort ist ein Array mit genau einem Beleg. Das Formularfeld bestimmt die Belegart: `invoice[]` Ausgangsrechnung, `receipt[]` Eingangsbeleg, beides bindend; bei `auto[]` entscheidet die Erkennung mit den Daten deiner Firma. Kann sie nicht sicher entscheiden, bekommt der Beleg „Belegtyp prüfen“ (`kindReview`) und wird nicht gebucht, bis du den Belegtyp wählst. Unterstützt werden PDF, PNG, JPEG und XML-E-Rechnungen. `X-Upload-Request-Id` macht Wiederholungen sicher: Dieselbe ID mit identischer Datei, identischem Dateinamen und Feld liefert denselben Beleg, ohne weiteres Kontingent; dieselbe ID mit anderem Inhalt ergibt `409 UploadRequestConflict`. Für jeden neuen Beleg eine neue ID verwenden. Ist das Belegkontingent ausgeschöpft, wird der Beleg trotzdem gespeichert (`uploadDocument.ocrStatus` = `quota_paused`); dann keinen weiteren Upload mit neuer ID starten.

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

> **Achtung:** Erzeugt einen echten Beleg, verbraucht Kontingent und wird GoBD-protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

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

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `X-Upload-Request-Id` | header | ja | string | Idempotenzschlüssel des Uploads: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Für jeden neuen Beleg eine neue ID, bei Wiederholungen dieselbe. |

### Request-Body (`multipart/form-data`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `auto[]` | string (binary) | Belegart entscheidet die Erkennung; unsicher heißt „Belegtyp prüfen“ (`kindReview`). |
| `invoice[]` | string (binary) | Ausgangsrechnung. |
| `receipt[]` | string (binary) | Eingangsbeleg. |

### Beispiel

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

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Der angelegte oder bei Wiederholung derselbe Beleg, als Array mit genau einem Eintrag. | `application/json`: Array<UploadResult> |
| 400 | Ungültiger Upload, z. B. ohne gültige `X-Upload-Request-Id`, mit mehr als einer Datei oder einer Datei über 30 MiB; 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 |
| 402 | Das Belegkontingent ist erreicht (`LimitReached`, mit `context.limit` und `context.usage`), der Beleg wird nicht gespeichert. Nach einem Tarifwechsel mit derselben `X-Upload-Request-Id` erneut senden. | `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 |
| 409 | Die `X-Upload-Request-Id` gehört schon zu einem Upload mit anderer Datei, anderem Dateinamen oder anderem Feld (`UploadRequestConflict`). Kein vorübergehender Fehler: nicht mit derselben ID wiederholen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen, oder zu viele Belege der Firma warten auf die Verarbeitung (`DocumentQueueFull`); nach `Retry-After` Sekunden mit derselben `X-Upload-Request-Id` erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; den Upload später mit derselben `X-Upload-Request-Id` wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200

Array aus `UploadResult`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `bookingErrors` | Array<BookingError>, kann null sein | Buchungsfehler, Warnungen und Hinweise. Bei einem Fehler (`level` 30) bucht bimetrics den Beleg gar nicht oder nicht verlässlich, bis der Fehler behoben ist. bimetrics liefert nur Einträge der Buchungsmodelle, mit denen die Firma heute bucht; welches Modell das ist, steht in `accountingModel`. |
| `bookings` | Array<AccountBooking>, kann null sein | Buchungen des Belegs. |
| `cashDiscount` | CashDiscountSnapshot | Skonto einer in bimetrics erstellten Ausgangsrechnung; fehlt ohne Skonto. |
| `companyId` | string (uuid) | ID der Firma. |
| `contentSource` | string | Herkunft der Belegdaten: `auto` erkannt, `manual` erfasst, `collection` aus Dauerbuchung oder Buchungsvorlage. |
| `costCenterId` | string (uuid) | Kostenstelle oder Verteilung als ID; fehlt ohne. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `deliveryDate` | NaiveDate | Liefer- bzw. Leistungsdatum. |
| `documentContract` | DocumentContract | Die Dauerbuchung, aus der der Beleg entstand; sonst `null`. |
| `documentContractId` | string (uuid), kann null sein | ID der Dauerbuchung, aus der der Beleg entstand; sonst `null`. |
| `documentCurrency` | string | Belegwährung nach ISO 4217, wenn der Beleg nicht in Euro ist, z. B. `USD`; fehlt bei Euro. Gebucht wird mit den Beträgen der Positionen als Euro. Solange `euroAmountSource` fehlt, ist das der Betrag vom Beleg, und die App zeigt „Euro-Betrag fehlt“. Korrigieren mit `documentCurrency` in `PATCH /api/document/{id}`. |
| `documentSeries` | DocumentSeries | Die Buchungsvorlage, aus der der Beleg entstand; sonst `null`. |
| `documentSeriesId` | string (uuid), kann null sein | ID der Buchungsvorlage, aus der der Beleg entstand; sonst `null`. |
| `dueDate` | NaiveDate | Fälligkeitsdatum. |
| `duplicate` | boolean | Die Datei lag in der Firma schon als Beleg vor. Fehlt sonst. |
| `euroAmountSource` | string: `payment`, `person`, `bmf` | Woher der Euro-Betrag eines Belegs in Fremdwährung stammt: `payment` aus der zugeordneten Bankzahlung übernommen, `person` von einer Person eingetragen oder bestätigt (`euroTotalAmount` oder `euroAmountsConfirmed` in `PATCH /api/document/{id}`), `bmf` zum Monatskurs des BMF umgerechnet (`euroAtMonthlyRate`). Fehlt, solange der Euro-Betrag fehlt. |
| `id` | string (uuid) | ID des Belegs. |
| `importOrigin` | string, kann null sein | Eingangsweg: `upload`, `email`, `generated` (in bimetrics erstellt) oder `collection` (aus Dauerbuchung oder Buchungsvorlage). |
| `invoiceCorrections` | Array<Document> | Quellgebundene Rechnungskorrekturen des Originalbelegs. |
| `invoiceDate` | NaiveDate | Rechnungsdatum. |
| `invoiceNumber` | string | Rechnungsnummer. |
| `invoicePositions` | Array<DocumentInvoicePosition>, kann null sein | Positionen; `null`, solange nichts erkannt ist. |
| `invoiceRole` | string: `down_payment`, `final` | Rolle einer ausgestellten Rechnung im Auftrag: `down_payment` (Abschlag) oder `final` (Schlussrechnung); fehlt bei allen anderen Belegen. |
| `issuedInvoice` | DocumentIssuedInvoice | Vom Server ermittelter Ausstellungsstatus; fehlt bei gewöhnlichen importierten Belegen. Ausgestellte Rechnungen und Stornorechnungen können nicht verändert oder gelöscht werden. |
| `issuer` | DocumentIssuer | Aussteller. |
| `kind` | string: `invoice`, `receipt` | Belegart: `invoice` Ausgangsrechnung, `receipt` Eingangsbeleg. |
| `kindReview` | boolean | „Belegtyp prüfen“: Die Erkennung konnte nicht sicher entscheiden, ob Ausgangsrechnung oder Eingangsbeleg; `kind` ist nur die Vermutung. Bis jemand den Belegtyp wählt (`kind` in `PATCH /api/document/{id}`, auch mit demselben Wert, oder `POST /api/document/bulk/kind`), wird der Beleg nicht gebucht, nicht exportiert und nicht zugeordnet. Fehlt sonst. |
| `match` | Match | Zuordnung zu Umsätzen und anderen Belegen; `null` ohne Zuordnung. |
| `originalTotalAmount` | integer | Bruttosumme in der Belegwährung in Hundertsteln, auch bei Währungen ohne Nachkommastellen. Festgehalten, als die Währung erkannt oder gesetzt wurde. Fehlt bei Euro. |
| `paymentTerms` | string | Zahlungsbedingungen als Text. |
| `performancePeriodFrom` | NaiveDate | Beginn des Leistungszeitraums. |
| `performancePeriodTo` | NaiveDate | Ende des Leistungszeitraums. |
| `possibleDuplicateOfId` | string (uuid) | „Möglicher Doppelbeleg“: ID eines älteren Belegs derselben Firma, der wahrscheinlich dasselbe Papier ist, nur ein zweites Mal hochgeladen (anderer Scan, andere Datei). Belegart, Geschäftspartner und Vorzeichen des Bruttobetrags sind gleich, dazu entweder die Rechnungsnummer (Leerzeichen und Groß-/Kleinschreibung egal) bei höchstens 1 Cent Unterschied im Bruttobetrag, solange sich die Rechnungsdaten nicht widersprechen, oder das Rechnungsdatum bei höchstens 1 % Unterschied oder einer fast gleich großen Datei mit gleicher Seitenzahl ab zwei Seiten, solange sich die Rechnungsnummern nicht widersprechen. Passen mehrere, ist es der ähnlichste. Nur ein Hinweis: bimetrics sperrt und löscht nichts. Ist es ein Doppelbeleg, löschst du einen der beiden mit `DELETE /api/document/{id}`. Fehlt sonst, auch bei stornierten, ausgestellten und festgeschriebenen Belegen. |
| `recipient` | DocumentRecipient | Empfänger. |
| `recordedPayments` | Array<RecordedPayment> | Dokumentierte Bar- und Verrechnungszahlungen; keine Bankumsätze. |
| `remainingPaymentMinor` | integer | Nach Zuordnungen und dokumentierten Zahlungen verbleibender Betrag in Cent. |
| `reversesCorrectionDocumentId` | string (uuid) | Ausgestellte Korrektur, die dieser Gegenbeleg vollständig aufhebt. |
| `source` | string | Auslösender Zugang: web, api oder mcp. |
| `sourceInvoiceDocumentId` | string (uuid) | Unveränderter Originalbeleg, auf den sich eine Rechnungskorrektur bezieht. |
| `statedTotalAmount` | integer | Gesamtbetrag brutto, wie die Erkennung ihn auf dem Beleg gelesen hat, in Hundertsteln wie die Positionen (bei Fremdwährung in der Belegwährung). Weicht die Summe der Positionen um mehr als einen Cent je Position davon ab, zeigt die App „Die Summe der Positionen weicht vom Gesamtbetrag im Beleg ab.“, der Beleg steht unter „Zu prüfen“, und Meldungen.csv im DATEV-Export nennt beide Beträge. Gebucht wird mit den Positionen. Korrigieren oder mit 0 beenden („Summe passt so“) mit `statedTotalAmount` in `PATCH /api/document/{id}`. Nach der Übernahme eines Euro-Betrags (`euroAmountSource`) wird nicht mehr verglichen. Fehlt, wenn kein Gesamtbetrag gelesen wurde oder er nicht im Text des Belegs steht. |
| `updatedAt` | string (date-time) | Letzte Änderung, auch einer Zuordnung: Zuordnen, Aufheben und ein neuer offener Betrag (`match.amountOpen`) ändern den Wert. |
| `uploadDocument` | UploadDocument | Die hochgeladene Datei und der Stand ihrer Erkennung. |
| `uploadDocumentId` | string (uuid), kann null sein | ID der hochgeladenen Datei; `null` bei Belegen aus Dauerbuchungen oder Buchungsvorlagen. |
| `version` | string | Fachlicher Versionsdigest. Unverändert als expectedVersion bei Belegkorrektur oder Zahlung übergeben. |

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