bimetricsEntwickler
Belegpostfach

Anhang als Beleg übernehmen

Als Markdown ansehen

Benötigte Berechtigung:inbox:write(Postfach bearbeiten)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/email/inbox/item/{id}/attachment/{aid}/import

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

Übernimmt einen Anhang als Beleg, wie „Übernehmen“ in der App: bimetrics speichert die Datei, erkennt und bucht sie wie üblich, und sie zählt zum Kontingent. Hat die Firma diese Datei schon, entsteht kein zweiter Beleg (duplicate). Ein schon übernommener Anhang liefert seinen Beleg (alreadyImported). Ein nicht vorgeschlagener Anhang (preselected = false) ist meist die zweite Fassung derselben Rechnung, etwa die XML neben ihrem ZUGFeRD-PDF: Beide zu übernehmen legt die Rechnung zweimal an. Wartet kein vorgeschlagener Anhang mehr, wandert die Mail nach „Erledigt“ (mailArchived). Abgelehnt: eine Mail unter „Erledigt“ (409 InboxMailArchived, erst zurückholen), ein Anhang, den bimetrics nicht lesen kann (409 InboxAttachmentNotImportable), ein Anhang, dessen Beleg inzwischen gelöscht ist (409 InboxAttachmentDocumentDeleted), und bei vielen wartenden Belegen 429 DocumentQueueFull mit Retry-After. Eine Wiederholung mit gleichem Idempotency-Key legt nichts doppelt an.

Benötigt einen Schlüssel mit der Berechtigung inbox:write.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID der Mail (UUID).

Formatuuid
aid*string

ID eines Anhangs dieser Mail (UUID).

Header-Parameter

Idempotency-Key*string

Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.

Muster^[!-~]+$
Länge1 <= length <= 128

Antworten

Erfolg.

application/json
  1. response

Was das Übernehmen getan hat.

alreadyImported?boolean

Der Anhang war schon übernommen; jetzt ist nichts passiert.

documentId?string

ID des Belegs.

Formatuuid
duplicate?boolean

Die Firma hatte diese Datei schon; es entstand kein zweiter Beleg.

mailArchived?boolean

Kein vorgeschlagener Anhang wartet mehr; die Mail steht unter „Erledigt“.

replayed?boolean

True bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/email/inbox/item/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachment/string/import" -X POST \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001"
Beispielantwort
{  "alreadyImported": false,  "documentId": "3f6c2a10-7b1e-4c55-9a70-0d2b8e41c9f1",  "duplicate": false,  "mailArchived": true,  "replayed": false}

Mail unter „Erledigt“ ablegen POST

Legt eine Mail ab, wie „Ablegen“ in der App. Gelöscht wird nichts, und nicht übernommene Anhänge (`notImported`) bleiben lesbar. Eine schon abgelegte Mail behält ihr erstes Datum. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt. Benötigt einen Schlüssel mit der Berechtigung `inbox:write`.

Seite eines Anhangs ansehen GET

Liefert eine Seite eines Anhangs als Bild (Base64), wie die Vorschau im Postfach, nur für Anhänge mit `valid` = `true`, sonst `409 InboxAttachmentNotImportable`. `pageCount` nennt die Seiten; eine Seite dahinter kommt ohne `pages`. Der erste Aufruf rendert die Datei und kann einige Sekunden dauern. Benötigt einen Schlüssel mit der Berechtigung `inbox:read`.