Beleg-Upload

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

VoraussetzungenLink zu diesem Abschnitt kopieren

• Ein Schlüssel mit der Berechtigung upload (in der App: Belege hochladen).
• POST an POST /api/document/ als multipart/form-data.
• Genau eine Datei je Anfrage, in genau einem dieser Felder:

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

Upload-IDLink zu diesem Abschnitt kopieren

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.

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 wiederholenLink zu diesem Abschnitt kopieren

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.

AntwortLink zu diesem Abschnitt kopieren

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

[
  {
    "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 abfragenLink zu diesem Abschnitt kopieren

Nach dem Upload erkennt bimetrics die Belegdaten im Hintergrund. Den Stand fragst du mit GET /api/document/{id} ab, im Feld uploadDocument.ocrStatus:

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

NachvollziehbarkeitLink zu diesem Abschnitt kopieren

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 ab.