{ "swagger": "2.0", "info": { "version": "1.4.0", "description": "Willkommen bei der **Binect REST API** – der Schnittstelle, um Dokumente als **physische Briefpost** über Versanddienstleister in Deutschland zu versenden – **nicht ausschließlich über die Deutsche Post**. Ihre Dokumente werden bei unseren Produktionspartnern gedruckt, kuvertiert, frankiert und zugestellt.\n\n## Umgebungen\n\n| Umgebung | URL | Zweck |\n| --- | --- | --- |\n| **Produktion** | https://app.binect.de | Echter, kostenpflichtiger Versand |\n| **Test** | https://test-app.binect.de | Kostenlos – **simuliert** den Versand |\n\n- Beide Umgebungen haben **getrennte Benutzerverwaltungen** – Sie benötigen in jeder Umgebung einen **eigenen Account**. Konten legen Sie über die Anmeldeseite an – [Produktion](https://app.binect.de/index.jsp?id=login) · [Test](https://test-app.binect.de/index.jsp?id=login).\n- Die Testumgebung kann einen **moderneren Stand** als die Produktion haben; **Handling und Antwortverhalten** sind jedoch bewusst identisch.\n\n## Versand in zwei Schritten\n\n1. **[`POST /documents`](#op:documents:uploadDocument:post:/documents)** – Dokument hochladen und validieren lassen.\n2. **[`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)** – ein hochgeladenes, valides Dokument in den Versand geben.\n\n## … oder Versand in einem Schritt\n\n- **[`POST /sendings/document`](#op:sendings:uploadAndSendDocument:post:/sendings/document)** – Kurzweg: hochladen und bei erfolgreicher Validierung **direkt** versenden.\n\n**Bearbeiten & Lebenszyklus:** Solange ein Dokument noch nicht zum Versand freigegeben ist, kann es über `/documents` geändert (Optionen, Transformation, Deckblatt, Anhänge) oder gelöscht werden. Ab der erfolgreichen **Versandfreigabe** ist `/sendings` zuständig.\n\n## Unterstützte Postprodukte\n\n- **Einschreiben** (Deutsche Post): Standard, Einwurf, International – Status bis in den Briefkasten nachverfolgbar\n- **PremiumAdress** (Deutsche Post): Report, Basic *(kostenpflichtige Freischaltung erforderlich)*\n- **Frankierter** Versand\n- **DV-freigemachter** Versand (DV-Freimachung – schnell, maximaler Funktionsumfang)\n\n## Dokumentvorgaben\n\n- Dokumente werden als **PDF im Base64-Format** übertragen.\n- Erlaubt sind **PDF** und **PostScript (PS)** – **PDF bevorzugt**. Maximale Dateigröße: **20 MB** (wirksamer Wert: `maxUploadSize` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)).\n- Empfohlene Druckvorgaben: **PDF/A-2b**, **eingebettete Schriften**, Farbraum **CMYK**.\n- Beispielbriefe: [DOCX-Vorlage](/downloadFile?fileId=4) · [ODT-Vorlage](/downloadFile?fileId=3) – bitte als PDF (Base64) übertragen.\n- Formatschablonen für Adress- und Sperrbereiche: [Schablone herunterladen](/downloadFile?fileId=24).\n- Ein Dokument darf maximal **192 Blatt** enthalten (Simplex 192 Seiten, Duplex 384 Seiten).\n- **Produktion in Österreich:** Auf Anfrage können Kunden aus Österreich gemeinsam mit der Binect GmbH in Österreich produzieren (`productionCountry: AT`).\n- **Adressierung:** Empfängeranschrift im **Anschriftenfeld** platzieren (bei Fensterumschlägen in der Fensterposition sichtbar); **Sperrbereiche** (Frankierung, Verarbeitungscodes) frei halten. Exakte Positionen siehe [Formatschablone herunterladen](/downloadFile?fileId=24) und FAQ [„Welche Datei- und Formatanforderungen gelten für meinen Brief?“](/index.jsp?id=faq#faq_5). Fehlt eine gültige Adresse im korrekten Bereich, kann per Transformation oder Deckblatt korrigiert werden.\n\n## Adressierung & Sperrbereiche\n\nAlle Maße ab der **oberen linken Ecke** der Seite. Empfänger- und Absenderadresse müssen so positioniert sein, dass sie im **Sichtfenster eines DIN-lang-Umschlags** vollständig sichtbar sind; die Sperrbereiche müssen frei bleiben.\n\n| Bereich | Breite | Höhe | Abstand links | Abstand oben |\n| --- | --- | --- | --- | --- |\n| Empfänger-Adressfeld | 85 mm | 21 mm | 20 mm | 69 mm |\n| Absender-Adressfeld | 85 mm | 5,5 mm | 20 mm | 45 mm |\n| DV-Sperrbereich | 85 mm | 17,5 mm | 20 mm | 51 mm |\n\n**DV-Validierung:** Seit dem **27.09.2022** ist die DV-Validierung der neue Standard der Plattform. Die bisherigen Adress- und Sperrbereiche bleiben gültig; für DV-Kompatibilität ist **zusätzlich** der oben genannte DV-Sperrbereich freizuhalten – er darf **keinerlei Inhalt (Text oder Bild/Grafik)** enthalten, da dort die **DV-Freimachung** aufgedruckt wird. [Formatschablone herunterladen](/downloadFile?fileId=24).\n\n## Verarbeitung & Fristen\n\n- Übergabe in die Produktion standardmäßig um **14:30 Uhr**; **Stornierungen** sind bis kurz davor möglich.\n- **Statusabfragen** sind erst **ab 05:00 Uhr des Folgetags** aussagekräftig – und nur, wenn die Sendung das **14:30-Versandfenster** erreicht hat, da der Versandstatus erst dann aktualisiert wird.\n- **Wartungsfenster:** jeden **Dienstag, 21:00–23:00 Uhr**.\n\n## Eigene Attribute (Custom-Attributes)\n\n- Übergeben Sie Ihre **interne Referenz-ID** im Feld **`externalReferenceId`** (ideal eine UUID) – so wird das Dokument später über **`GET /documents/findByExternalReferenceId`** auffindbar.\n- **Abrechnung mit Kostenstellen?** Bei individueller Rechnung über das Feld **`tenantId`** realisierbar.\n\n## Validierung & Korrektur\n\n- Dokumente, die **nicht positiv validiert** werden, lassen sich häufig retten – z. B. über die **Transformations-Schnittstelle** (Verschieben & Skalieren) oder die **Deckblatt-Funktion** – und so in ein versandfähiges Dokument überführen.\n\n## Fehlerantworten\n\n- Fehler kommen mit dem passenden **HTTP-Status** und einem **Klartext** als Rumpf (`Content-Type: text/plain;charset=UTF-8`), z. B. `Not Found: Document 4711 doesn't exist.` Werten Sie den **HTTP-Status** aus – der Text dient der Anzeige und kann sich ändern.\n- Wo ein **Binect-Fehlercode** vorliegt, steht er zusätzlich in der Kopfzeile **`X-Error-Code`** (z. B. `X-Error-Code: 4404`). Die Bedeutung aller Codes, zweisprachig: [`/binectapi/error-codes.json`](/binectapi/error-codes.json).\n- Erfolgreiche Antworten mit Daten sind **JSON**. Verlangt `Accept` ausschließlich ein anderes Format (z. B. nur `text/plain`), antwortet die API mit **`406`** (Code `4406`). `Accept: application/json` oder `*/*` ist immer richtig.\n- Kann die Anmeldung vorübergehend nicht geprüft werden, antwortet die API mit **`503`** und der Kopfzeile **`Retry-After`** (Code `4503`). Das ist kein Fehler Ihrer Anfrage: Wiederholen Sie sie nach der dort genannten Zahl von Sekunden.\n- Nach wiederholt **falschen Passwörtern** von Ihrer Adresse antwortet die API mit **`429`** und der Kopfzeile **`Retry-After`** (Code `4429`), ohne das Passwort zu prüfen. Wer das richtige Passwort von einer Adresse sendet, die sich schon erfolgreich angemeldet hat, wird nicht gebremst. Steht ein Login unter massivem Beschuss, weist die API Adressen, die sich noch nie erfolgreich angemeldet haben, bis zu 24 Stunden ab. API-Keys sind nie betroffen. Prüfen Sie das Passwort und wiederholen Sie erst nach der genannten Zahl von Sekunden – oder melden Sie sich mit einem API-Key an.\n\n## Fehlerbehandlung beim Upload (HTTP 500)\n\n- Bei einem **`500`** während des Uploads ist **immer davon auszugehen, dass das Dokument möglicherweise dennoch angekommen ist**.\n- **Empfehlung:** Geben Sie beim Upload eine eindeutige **`externalReferenceId`** mit und fragen Sie sie im Fehlerfall über **`GET /documents/findByExternalReferenceId`** ab:\n - **Treffer** → Dokument ist angekommen (nicht erneut hochladen).\n - **kein Treffer** → Dokument ist **nicht** im Service → erneut hochladen.\n\n## Beispielcode: `POST /sendings/document` (hochladen + direkt versenden)\n\nDefault-URL ist die **Testumgebung** (`https://test-app.binect.de/binectapi/v1`); für Produktion `https://app.binect.de/binectapi/v1`. Authentifizierung per **API-Key** (empfohlen, `Authorization: Bearer `) oder **HTTP Basic** (E-Mail + Passwort) - die Beispiele unten nutzen Basic, die Logindaten sind **Platzhalter**.\n\n
\nBeispielcode anzeigen\n

Bash (curl)

\n
# Default: Testumgebung. Produktion: https://app.binect.de/binectapi/v1\nBASE_URL=\"https://test-app.binect.de/binectapi/v1\"\nEMAIL=\"ihre-email@example.com\"\nPASSWORD=\"ihr-passwort\"\nB64=$(base64 -w0 brief.pdf)        # macOS: base64 -i brief.pdf\ncurl -s -u \"$EMAIL:$PASSWORD\" -H \"Content-Type: application/json\" \\\n  -X POST \"$BASE_URL/sendings/document\" -d @- <<JSON\n{\n  \"content\": { \"filename\": \"brief.pdf\", \"content\": \"$B64\" },\n  \"options\": { \"simplex\": true, \"color\": false, \"envelope\": \"DINLANG\", \"franking\": \"DV_FRANKING\", \"product\": \"NORMAL\" },\n  \"tenantId\": \"kostenstelle-4711\",\n  \"externalReferenceId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\"\n}\nJSON
\n

Python (requests)

\n
import base64, requests\nBASE_URL = \"https://test-app.binect.de/binectapi/v1\"  # Prod: https://app.binect.de/binectapi/v1\nEMAIL, PASSWORD = \"ihre-email@example.com\", \"ihr-passwort\"\nwith open(\"brief.pdf\", \"rb\") as fh:\n    content = base64.b64encode(fh.read()).decode()\nresp = requests.post(\n    f\"{BASE_URL}/sendings/document\",\n    auth=(EMAIL, PASSWORD),\n    json={\n        \"content\": {\"filename\": \"brief.pdf\", \"content\": content},\n        \"options\": {\"simplex\": True, \"color\": False, \"envelope\": \"DINLANG\",\n                    \"franking\": \"DV_FRANKING\", \"product\": \"NORMAL\"},\n        \"tenantId\": \"kostenstelle-4711\",\n        \"externalReferenceId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n    },\n)\nprint(resp.status_code, resp.json())
\n

JavaScript (Node 18+, fetch)

\n
import { readFile } from \"node:fs/promises\";\nconst BASE_URL = \"https://test-app.binect.de/binectapi/v1\"; // Prod: https://app.binect.de/binectapi/v1\nconst EMAIL = \"ihre-email@example.com\", PASSWORD = \"ihr-passwort\";\nconst content = (await readFile(\"brief.pdf\")).toString(\"base64\");\nconst auth = \"Basic \" + Buffer.from(`${EMAIL}:${PASSWORD}`).toString(\"base64\");\nconst resp = await fetch(`${BASE_URL}/sendings/document`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\", Authorization: auth },\n  body: JSON.stringify({\n    content: { filename: \"brief.pdf\", content },\n    options: { simplex: true, color: false, envelope: \"DINLANG\", franking: \"DV_FRANKING\", product: \"NORMAL\" },\n    tenantId: \"kostenstelle-4711\",\n    externalReferenceId: \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  }),\n});\nconsole.log(resp.status, await resp.json());
\n

PHP (curl)

\n
<?php\n$baseUrl  = \"https://test-app.binect.de/binectapi/v1\"; // Prod: https://app.binect.de/binectapi/v1\n$email    = \"ihre-email@example.com\";\n$password = \"ihr-passwort\";\n$content = base64_encode(file_get_contents(\"brief.pdf\"));\n$payload = json_encode([\n  \"content\"    => [\"filename\" => \"brief.pdf\", \"content\" => $content],\n  \"options\"    => [\"simplex\" => true, \"color\" => false, \"envelope\" => \"DINLANG\",\n                   \"franking\" => \"DV_FRANKING\", \"product\" => \"NORMAL\"],\n  \"tenantId\" => \"kostenstelle-4711\",\n  \"externalReferenceId\" => \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n]);\n$ch = curl_init(\"$baseUrl/sendings/document\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST           => true,\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_USERPWD        => \"$email:$password\",\n  CURLOPT_HTTPHEADER     => [\"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS     => $payload,\n]);\n$resp = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE) . \"\\n\" . $resp . \"\\n\";
\n
\n\n## Authentifizierung, Abrechnung & Hinweise\n\n- **Authentifizierung:** per **API-Key** (empfohlen) oder per HTTP Basic mit **E-Mail + Passwort**. API-Keys legen Sie im Kundenportal unter **Mein Konto → API-Keys** an. Dort legen Sie je Login auch fest, was die REST-API annimmt: nur das Passwort (Standard), Passwort und API-Key oder nur API-Keys. Senden Sie je Anfrage **genau eine** Anmeldung – den Key als `Authorization: Bearer `, als `X-API-Key: ` oder bei Clients, die nur Basic beherrschen, als Passwort (der Benutzername wird ignoriert, empfohlen ist Ihre E-Mail-Adresse). Ein Key bleibt gültig, wenn Sie Passwort oder E-Mail-Adresse ändern. Senden Sie einen Key **nie** als Query-Parameter in der URL. In der Swagger-UI autorisieren Sie nur eines der drei Verfahren. Angelegt, deaktiviert und gelöscht werden die Keys ausschließlich im Kundenportal unter **Mein Konto → API-Keys**; die REST-API verwaltet keine Keys. [`GET /accounts/authentication`](#op:accounts:getAuthentication:get:/accounts/authentication) zeigt, wie eine Anfrage angemeldet wurde und welche Client-IP-Adresse der Server sieht.\n- **Zahlung:** Standard ist **Prepaid** (PayPal, Kreditkarte, Sofortüberweisung). Auf Wunsch kann ein Konto auch **auf Rechnung** freigeschaltet werden. Kostenstellen-Abrechnung über das Feld `tenantId` (siehe oben).\n- **Vertriebspartner:** Partner-Optionen können mit dem Vertrieb ([info@binect.de](mailto:info@binect.de)) besprochen werden.\n- **Benachrichtigungen:** Über neue Briefzustände müssen Sie sich **aktiv** informieren (Status-Endpunkte abfragen). Eine **Webhook-Schnittstelle gibt es derzeit nicht**, ist für die Zukunft aber denkbar.\n\n## Support & Kontakt\n\n- **Technische Fragen / Probleme:** [kontakt@binect.de](mailto:kontakt@binect.de)\n- **Anbindungsunterstützung / Angebot:** Binect Vertrieb – [info@binect.de](mailto:info@binect.de)", "title": "Binect REST API", "termsOfService": "/downloadFile?fileId=2", "contact": { "name": "kontakt@binect.de" } }, "basePath": "/binectapi/v1", "securityDefinitions": { "basicAuth": { "type": "basic", "description": "HTTP-Basic-Authentifizierung mit E-Mail-Adresse und Passwort. Clients, die nur Basic beherrschen, können statt des Passworts einen API-Key senden: Der Benutzername wird dann ignoriert (empfohlen ist Ihre E-Mail-Adresse). Ein Passwort, das mit `bnct_` beginnt, gilt als API-Key. Senden Sie je Anfrage genau eine Anmeldung: zwei verschiedene Kopfzeilen `Authorization` oder `Authorization` zusammen mit einem API-Key in `X-API-Key` werden mit `400` und Fehlercode `44015` abgewiesen. Bei Logins, die nur API-Keys annehmen, wird das Passwort mit `403` und Fehlercode `44034` abgewiesen; kann die Anmeldung vorübergehend nicht geprüft werden, antwortet die API mit `503` und `Retry-After` (Fehlercode `4503`). Nach wiederholt falschen Passwörtern von derselben Adresse antwortet die API mit `429` und `Retry-After` (Fehlercode `4429`), ohne das Passwort zu prüfen." }, "bearerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API-Key in der Kopfzeile `Authorization`: `Authorization: Bearer ` (empfohlen). In der Swagger-UI fügen Sie den Key selbst ein (`bnct_…`); `Bearer ` wird automatisch ergänzt. API-Keys legen Sie im Kundenportal unter **Mein Konto → API-Keys** an; der vollständige Key wird nur einmal angezeigt, beim Anlegen. Ein ungültiger, deaktivierter oder abgelaufener Key wird mit `401` und Fehlercode `44012`, `44013` bzw. `44014` abgewiesen. Kann der Key vorübergehend nicht geprüft werden (kurze Störung oder zu viele gleichzeitige Prüfungen), antwortet die API mit `503` und `Retry-After` (Fehlercode `4503`)." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API-Key in der Kopfzeile `X-API-Key`: `X-API-Key: ` – in der Swagger-UI der einfachste Weg (nur den Key eingeben). Nur allein verwenden: Zusammen mit einer Kopfzeile `Authorization` wird die Anfrage mit `400` und Fehlercode `44015` abgewiesen. Kann der Key vorübergehend nicht geprüft werden (kurze Störung oder zu viele gleichzeitige Prüfungen), antwortet die API mit `503` und `Retry-After` (Fehlercode `4503`)." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "documents", "description": "Dokumente hochladen, validieren, bearbeiten und abfragen (vor der Versandfreigabe)." }, { "name": "status", "description": "Status-Abfragen für Dokumente und Sendungen." }, { "name": "corrections", "description": "Korrekturen an Dokumenten: Transformationen und Deckblatt." }, { "name": "attachments", "description": "Anhänge verwalten (Anhang-Pool und Dokument-Anhänge)." }, { "name": "sendings", "description": "Versandfreigabe, Stornierung und Versandstatus." }, { "name": "regmails", "description": "Einschreiben: Status und Tracking." }, { "name": "accounts", "description": "Konto: Guthaben, persönliche Daten, Standard-Versandoptionen, Mitarbeiter, Journal, API-Keys und Anmeldung." }, { "name": "invoices", "description": "Rechnungen und deren Transaktionen." } ], "externalDocs": { "description": "AI agents & integration overview (llms.txt)", "url": "/llms.txt" }, "paths": { "/documents": { "delete": { "tags": [ "documents" ], "description": "Löscht mehrere Dokumente, die **noch nicht zum Versand übergeben** wurden, in einer Anfrage – die Mengen-Variante von `DELETE /documents/{documentID}`, deren Verhalten unverändert bleibt.\n\nJede ID wird **für sich** versucht; eine nicht löschbare ID hält die übrigen nicht auf und lässt ihren Brief in diesem Moment unangetastet. Die Antwort ist immer `200` mit einem Eintrag je **verschiedener** angefragter ID, in der Reihenfolge der Anfrage – doppelte IDs werden zusammengefasst, **die Zuordnung erfolgt deshalb über `id`, niemals über die Position**. `deleted` sagt, ob gelöscht wurde, `error` nennt den Grund, wenn nicht: dieselben Fehlercodes wie die Einzel-Variante (`4404` unbekannt oder bereits gelöscht, `4403` fremdes Konto, `44091` Zustand erlaubt das Löschen nicht, `4500` harter Fehler), dazu `44092`, das nur diese Mengen-Variante liefert, für einen Serienbrief, den seine Einzelbriefe blockieren. **Jeden Eintrag prüfen; der HTTP-Status sagt nichts über die einzelnen Ergebnisse.**\n\nDas Löschen eines Serienbriefes löscht seine Einzelbriefe mit; `deletedChildren` nennt deren Anzahl, ohne sie aufzuzählen. Steht ein Einzelbrief zusammen mit seinem Serienbrief in derselben Anfrage, wird der Serienbrief zuerst bearbeitet, und der Einzelbrief meldet `deleted: true` mit `deletedAsChildOf` – nicht `4404`. Es gilt auch andersherum: das Löschen des **letzten** verbliebenen Einzelbriefs eines Serienbriefs löscht den Serienbrief mit, auch wenn dieser gar nicht angefragt war – er hat dann keinen eigenen Eintrag in der Antwort. Die Operation ist **nicht atomar**: ein Teilergebnis ist echt und wird nicht zurückgenommen.\n\nDie IDs werden als wiederholte Parameter übergeben (`?documentIds=17&documentIds=18`); eine Kommaliste wird **nicht** angenommen. Höchstens `maxDelete` IDs je Anfrage (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits), standardmäßig 250) – darüber `413` mit Fehlercode `44008`, und es wird nichts gelöscht.", "produces": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "query", "required": true, "type": "array", "collectionFormat": "multi", "items": { "type": "integer", "format": "int32" }, "description": "Die zu löschenden Dokument-IDs, als wiederholte Parameter." } ], "responses": { "200": { "description": "Erfolgreiche Antwort – ein Eintrag je angefragter ID. Einzelne IDs können trotzdem abgelehnt worden sein; `deleted` und `error` je Eintrag prüfen.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentDeletionStatus" } } }, "400": { "description": "Ungültige Anfrage – `documentIds` fehlt, ist leer oder trägt einen leeren Wert (`?documentIds=`). Fehlercode `4400`. Es wurde nichts gelöscht." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Anfrage zu groß – mehr IDs als `maxDelete` aus `GET /accounts/limits` zulässt (standardmäßig 250). Fehlercode `44008`. Es wurde nichts gelöscht; die Liste in Blöcke aufteilen." } }, "operationId": "deleteDocuments" }, "post": { "tags": [ "documents" ], "description": "Lädt ein neues Dokument hoch. Das Dokument ist ein **Einzelbrief** oder ein **Serienbrief** und enthält eine gültige Adresse im Anschriftenfeld; Sperrbereiche werden freigehalten.\n\n**Dateiformate:** Erlaubt sind **PDF** und **PostScript (PS)** – **bevorzugt PDF**. PDFs sollten dem Standard **PDF/A-2b** entsprechen (eingebettete Schriften, Farbraum CMYK). Maximale Dateigröße: **20 MB** (wirksamer Wert: `maxUploadSize` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)).\n\n**Übertragung:** Der Inhalt wird **Base64-kodiert** im Feld `content` übergeben.\n\n**Validierung:** Das Dokument wird geprüft. Schlägt die Validierung fehl, wird – sofern möglich – eine Korrektur (Transformation, Deckblatt) angeboten. Die Antwort enthält ein gültiges Dokument oder ein `error`-Objekt.\n\n**Hinweis:** Das Dokument wird für die Druckproduktion normalisiert; wir empfehlen eine Sichtprüfung über `GET /documents/{documentID}/pdf`.\n\n**Tipp:** Für schnellen Versand mit maximalem Funktionsumfang die **DV-Freimachung** (moderne Freimachungsart) verwenden.\n\n**Status nach dem Upload** (`status.code` → `status.text`):\n- **2** – `versandbereit` (engl. `ready to ship`)\n- **7** – `fehlerhaft` (engl. `faulty`)\n- **8** – `zugestellt` (engl. `delivered`) – nur Einschreiben, Endzustand\n- **9** – `zurückgelaufen` (engl. `returned to sender`) – nur Einschreiben, Endzustand\n\n**Zuverlässigkeit:** Bei HTTP `500` kann der Upload dennoch erfolgreich gewesen sein. Geben Sie eine `externalReferenceId` mit und prüfen Sie in diesem Fall vor einem erneuten Upload über `GET /documents/findByExternalReferenceId` (ein Treffer bedeutet: angekommen).", "parameters": [ { "name": "upload", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "options": { "$ref": "#/definitions/Options" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } }, "tenantId": { "type": "string", "maxLength": 32, "example": "kostenstelle-4711", "description": "Ihre interne Kunden-/Mandantennummer für diesen Auftrag (max. 32 Zeichen). Wird am Auftrag gespeichert und in die Produktion übergeben. Ersetzt das frühere Custom-Attribute `tenant`. Steuerzeichen (z. B. Tabulator, Zeilenumbruch), unsichtbare Formatierungszeichen und Sonderleerzeichen (z. B. geschütztes Leerzeichen) werden mit HTTP 400 abgewiesen; die Meldung nennt Position und Zeichen. Alte Custom-Attribute mit solchen Zeichen werden nicht übernommen." }, "externalReferenceId": { "type": "string", "maxLength": 64, "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "description": "Ihre interne Referenz-ID für diesen Auftrag (max. 64 Zeichen); ideal ist eine **UUID**. Suchbar über `GET /documents/findByExternalReferenceId`. Ersetzt das frühere Custom-Attribute `documentID`. Steuerzeichen (z. B. Tabulator, Zeilenumbruch), unsichtbare Formatierungszeichen und Sonderleerzeichen (z. B. geschütztes Leerzeichen) werden mit HTTP 400 abgewiesen; die Meldung nennt Position und Zeichen. Alte Custom-Attribute mit solchen Zeichen werden nicht übernommen." }, "externalReferenceIdUnique": { "type": "boolean", "default": false, "description": "Optionaler Doppel-Einlieferungsschutz. Bei `true` wird der Upload abgelehnt, wenn bereits ein anderer Ihrer Aufträge diese `externalReferenceId` trägt (Schutz vor versehentlichen Doppel-Einlieferungen)." }, "splitParams": { "description": "Legt bei einem Serienbrief fest, wie er in einzelne Briefe aufgeteilt wird. Es darf entweder `splitToken` oder `splitAfterNumberOfPages` verwendet werden, nicht beides.", "type": "object", "properties": { "splitToken": { "type": "string", "description": "Text-Token, an dem der Serienbrief in einzelne Briefe aufgeteilt wird." }, "splitAfterNumberOfPages": { "type": "integer", "format": "int32", "description": "Der Serienbrief wird alle N Seiten aufgeteilt." } }, "example": { "splitToken": "Sehr geehrte" } }, "responseFormat": { "$ref": "#/definitions/ResponseFormatEnum" } }, "example": { "content": { "filename": "musterbrief.pdf", "content": "" }, "tenantId": "kostenstelle-4711", "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } } ], "responses": { "200": { "description": "Dokument angelegt – kann fehlerhaft sein (prüfen Sie `status`; bei Code 7 siehe `error`).", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Anfrage zu groß – die Datei überschreitet die maximale Upload-Größe (20 MB, siehe `maxUploadSize` in `GET /accounts/limits`; für einen Serienbrief mit `splitParams` 60 MB, siehe `maxSerialLetterUploadSize`)." } }, "operationId": "uploadDocument" }, "get": { "tags": [ "documents" ], "description": "Liefert Dokumente **vor der Versandfreigabe**, jedes mit allen Details (Empfänger, Optionen, Anlagen, Preis) - also die Statusabfrage plus alles, was über den Brief bekannt ist.\n\nEnthalten sind Briefe, die noch validiert werden, und Briefe, die versandbereit sind:\n- **1** - `wird erstellt` (en `being created`) - Upload angenommen, Validierung läuft noch\n- **2** - `versandbereit` (en `ready to ship`)\n\nNicht enthalten: **fehlerhafte** Briefe (Code 7) - dafür `GET /documents/errors` - und alles nach der Versandfreigabe, das `GET /sendings` beantwortet.\n\nGeliefert werden nur die hochgeladenen Briefe selbst; die Einzelbriefe eines Serienbriefs stehen nicht in dieser Liste. Wer sie braucht, nimmt `GET /documents/status` oder `GET /status`.\n\nWeil jeder Eintrag das vollständige Dokument trägt, wächst die Antwort schnell. Ohne `limit` ist die Menge auf `maxRead` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) begrenzt (standardmäßig 500); darüber antwortet die Schnittstelle mit `413` und Fehlercode `44007`. Für reines Statuspollen sind `GET /documents/status` bzw. `GET /status` die richtige Wahl - um Größenordnungen kleiner und mit einer deutlich höheren Grenze.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Die Dokumente vor der Versandfreigabe, mit allen Details.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Antwort zu groß - mehr lesbare Dokumente als `maxRead` aus `GET /accounts/limits` zulässt (standardmäßig 500) oder `limit` darüber. Fehlercode `44007`. `limit` und `offset` verwenden." } }, "operationId": "listShippableDocuments" } }, "/documents/status": { "get": { "tags": [ "documents", "status" ], "description": "Liefert den Status von Dokumenten **vor der Versandfreigabe** - `documentID` sowie `status` (`code` und `text`), keine Dokumentdetails.\n\nBesonders nützlich nach einem Upload mit `responseFormat` = `SHORT`: der Upload antwortet dann sofort, ohne das Validierungsergebnis, und die Validierung läuft danach. Über diesen Endpunkt holt man das Ergebnis nach.\n\nStatuscodes in dieser Phase:\n- **1** - `wird erstellt` (en `being created`) - der Brief wartet auf die Validierung, wird validiert, wird in Einzelbriefe aufgeteilt (Serienbrief) oder bekommt gerade Anlagen angehängt\n- **2** - `versandbereit` (en `ready to ship`)\n- **7** - `fehlerhaft` (en `faulty`)\n\n`documentIds` ändert das Verhalten:\n- **mit** `documentIds`: genau die angefragten Dokumente, und zwar in **jedem** Zustand - eine Abfrage nach IDs ist nicht an die Phase gebunden. IDs, die nicht lesbar sind, werden weggelassen; `404` nur, wenn keine davon lesbar ist.\n- **ohne** `documentIds`: alle Dokumente des Kontos in dieser Phase, einschließlich der Einzelbriefe eines Serienbriefs (die über diese API einzeln versendet werden können). Entwürfe und im Webportal in Arbeit befindliche Briefe erscheinen nie - beides gibt es nur in der Weboberfläche.\n\nZum Blättern `limit` und `offset` verwenden. Ohne `limit` ist die Menge auf `maxReadStatus` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) begrenzt (standardmäßig 5000); darüber antwortet die Schnittstelle mit `413` und Fehlercode `44007`.\n\n**Bis wann geliefert wird:** ohne `documentIds` verlässt ein Brief diese Antwort mit der Versandfreigabe - danach beantwortet ihn `GET /sendings/status`. `GET /status` umspannt beide Phasen und hat diesen Bruch nicht.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "413": { "description": "Antwort zu groß - mehr lesbare Dokumente als `maxReadStatus` aus `GET /accounts/limits` zulässt (standardmäßig 5000) oder `limit` darüber. Fehlercode `44007`. `limit` und `offset` verwenden." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden - keine der in `documentIds` angegebenen IDs ist für dieses Konto lesbar. Ohne `documentIds` tritt dieser Code nicht auf; ein Konto ohne Briefe in dieser Phase erhält eine leere Liste mit 200." } }, "operationId": "listDocumentValidationStatus" } }, "/documents/errors": { "get": { "tags": [ "documents" ], "description": "Liefert alle hochgeladenen, **fehlerhaften** Dokumente.\n\nFehlerhafte Dokumente haben `status.code` **7** – `fehlerhaft` (engl. `faulty`). Prüfen Sie die Fehlermeldung(en) im Feld `error` sowie die Vorschau über `GET /documents/{documentID}/pdf` bzw. `/png`.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Liste der fehlerhaften Dokumente.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Antwort zu groß - mehr lesbare Dokumente als `maxRead` aus `GET /accounts/limits` zulässt (standardmäßig 500) oder `limit` darüber. Fehlercode `44007`. `limit` und `offset` verwenden." } }, "operationId": "listFaultyDocuments" } }, "/documents/findbyAttributes": { "get": { "tags": [ "documents" ], "description": "Liefert alle hochgeladenen Dokumente, die mit den angegebenen Attributen markiert sind.\n\nMindestens ein `key`/`value`-Paar ist erforderlich. `key` und `value` werden **paarweise nach Position** ausgewertet (`key[0]` gehört zu `value[0]` usw.); beide Arrays müssen daher **gleich viele** Einträge enthalten. Schlüssel und Werte werden genauso bereinigt wie beim Speichern (Steuer- und unsichtbare Formatierungszeichen entfernt, Tabulator/Zeilenumbruch/Sonderleerzeichen werden zu einem Leerzeichen) - ein Suchwert mit angehängtem Zeilenumbruch findet den gespeicherten Wert also trotzdem.", "parameters": [ { "name": "key", "in": "query", "required": true, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "value", "in": "query", "required": true, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "findDocumentsByAttributes" } }, "/documents/findByExternalReferenceId": { "get": { "tags": [ "documents" ], "description": "Sucht Ihre Aufträge anhand ihrer `externalReferenceId` und liefert deren Status. Mit `full=true` werden die vollständigen Dokument-Objekte geliefert, mit `full=false` (Standard) ein minimaler Status (Auftrags-ID, Status, externalReferenceId). Nur die eigenen Aufträge werden berücksichtigt – eine fremde oder unbekannte Referenz liefert ein leeres Ergebnis.", "parameters": [ { "name": "externalReferenceId", "in": "query", "required": true, "type": "string", "maxLength": 64 }, { "name": "full", "in": "query", "required": false, "type": "boolean", "default": false } ], "responses": { "200": { "description": "Passende Aufträge. Bei `full=false` eine Liste minimaler Status; bei `full=true` eine Liste vollständiger `Document`-Objekte.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentReferenceStatus" } } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "findDocumentsByExternalReferenceId" } }, "/documents/{documentID}": { "get": { "tags": [ "documents" ], "description": "Liefert das referenzierte Dokument. Das Dokument ist ein Einzelbrief, ein Serienbrief oder ein `error`-Objekt.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." } }, "operationId": "getDocument" }, "delete": { "tags": [ "documents" ], "description": "Löscht das angegebene Dokument. Nur möglich, solange es noch nicht zum Versand übergeben wurde.\n\nGelöscht werden kann nur, solange der Zustand des Briefes es zulässt. Ein Brief, der verarbeitet wird (wartet auf Validierung, wird validiert, Bezahlung oder Übergabe läuft), der in Produktion oder gedruckt ist oder für den ein Storno beantragt wurde, ist **nicht** löschbar - die Antwort ist dann `409` mit Fehlercode `44091`, und der Brief bleibt unangetastet. Bei einem Serienbrief muss jeder Einzelbrief löschbar sein.\n\nLöschen markiert den Brief als gelöscht; ein Brief, der bereits an die Produktion übergeben wurde, wird dadurch **nicht** zurückgerufen.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "409": { "description": "Konflikt - das Dokument existiert, kann in seinem aktuellen Zustand aber nicht gelöscht werden. Fehlercode `44091`. Nicht löschbar ist ein Brief, solange er verarbeitet wird, solange er in Produktion oder gedruckt ist und solange ein Storno beantragt ist; bei einem Serienbrief muss jeder Einzelbrief löschbar sein. Status abfragen und wiederholen, sobald ein Endzustand erreicht ist." }, "404": { "description": "Dokument nicht gefunden - zur `documentID` gibt es kein Dokument, oder es ist bereits als gelöscht markiert. Ein Dokument eines anderen Kontos ergibt `403`, ein vorhandenes, das gerade nicht löschbar ist, ergibt `409`." } }, "operationId": "deleteDocument" } }, "/documents/{documentID}/status": { "get": { "tags": [ "documents", "status" ], "description": "Liefert den Status eines einzelnen Dokuments (`code` und `text`; alle Codes stehen im Modell `Status`).\n\n**Nicht an die Phase gebunden**, anders als der Pfad vermuten lässt: eine Abfrage nach einer einzelnen ID wird in jedem Zustand beantwortet - vor der Versandfreigabe, danach und nach der Zustellung. Dieser Endpunkt, `GET /sendings/{documentID}/status` und `GET /status/{documentID}` liefern deshalb dasselbe; für neue Anbindungen ist `GET /status/{documentID}` der Name, der das auch sagt.\n\n`404` tritt nur auf, wenn das Dokument nicht existiert, zu einem anderen Konto gehört oder gelöscht ist - per `DELETE /documents/{documentID}` oder durch die Aufbewahrungsfrist.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getDocumentStatus" } }, "/documents/{documentID}/options": { "get": { "tags": [ "documents" ], "description": "Liefert die Versandoptionen des Dokuments (z. B. Simplex/Duplex, Farbe, Freimachung, Produkt, Produktionsland).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." } }, "operationId": "getDocumentOptions" }, "put": { "tags": [ "documents" ], "description": "Aktualisiert die Versandoptionen des Dokuments. Nur möglich, solange das Dokument noch nicht in den Versand gegeben wurde.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "options", "in": "body", "schema": { "$ref": "#/definitions/Options" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – der Zustand des Dokuments lässt keine neuen Versandoptionen zu. Ändern lassen sie sich nur bei Entwürfen sowie versandfähigen oder fehlerhaften Briefen; solange ein Brief verarbeitet wird, in Produktion ist oder versendet wurde, lautet die Antwort `409` mit Fehlercode `44099` (bis 7.5 war das `400` mit `4400`). Ein Mehrfachbrief ohne einen einzigen Einzelbrief (die Aufteilung hat keinen ergeben) antwortet `409` mit `44098` – seine Optionen haben nichts, worauf sie wirken könnten; bitte löschen und das Dokument erneut hochladen." } }, "operationId": "updateDocumentOptions" } }, "/documents/{documentID}/attributes": { "get": { "tags": [ "documents" ], "description": "Liefert die Attribute des Dokuments (benutzerdefinierte `key`/`value`-Paare).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "listDocumentAttributes" }, "post": { "tags": [ "documents" ], "description": "Versieht das Dokument mit Attributen (benutzerdefinierte `key`/`value`-Paare). Über diese lässt sich das Dokument später per `GET /documents/findbyAttributes` wiederfinden.\n\nAttribute können in der Regel jederzeit gesetzt oder geändert werden. Für Mandanten-/Referenz-Angaben nutzen Sie bitte die dedizierten Felder `tenantId` und `externalReferenceId` statt Custom-Attributes.", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" }, { "name": "attributes", "in": "body", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." } }, "operationId": "addDocumentAttributes" } }, "/documents/{documentID}/attributes/{key}": { "get": { "tags": [ "documents" ], "description": "Liefert das Attribut des Dokuments zum angegebenen `key`.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "key", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getDocumentAttribute" }, "put": { "tags": [ "documents" ], "description": "Setzt den `value` des Attributs zum angegebenen `key`: legt das Attribut an, wenn das Dokument es noch nicht hat (**201**), und ändert es sonst (**200**). Bei einem Serienbrief wird der Wert an seine Einzelbriefe weitergegeben.\n\n`value` wird als Formularfeld erwartet (`Content-Type: application/x-www-form-urlencoded`, Rumpf `value=…`). Er wird auch als Query-Parameter `?value=…` angenommen: Ein Request ohne Rumpf gilt als Formular, gleich welchen `Content-Type` er angibt – viele Clients senden standardmäßig einen –, und der Header darf auch ganz fehlen. Ein Rumpf in einem anderen Format (z. B. JSON) wird mit **415** abgewiesen.\n\nSteuerzeichen und unsichtbare Formatierungszeichen werden aus Schlüsseln und Werten entfernt; Tabulatoren, Zeilenumbrüche und Sonderleerzeichen werden zu einem Leerzeichen (am Anfang oder Ende: zu nichts). Solche Werte werden bereinigt angenommen, nicht abgewiesen - beim Lesen kommt der bereinigte Wert zurück.", "consumes": [ "application/x-www-form-urlencoded" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "key", "in": "path", "required": true, "type": "string" }, { "name": "value", "in": "formData", "required": true, "type": "string", "description": "Der Wert des Attributs – als Formularfeld oder alternativ als Query-Parameter." } ], "responses": { "200": { "description": "Geändert – das Attribut gab es schon, es wurde geändert.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "201": { "description": "Angelegt – das Dokument hatte dieses Attribut noch nicht; es wurde angelegt.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." }, "415": { "description": "Nicht unterstützter Content-Type – der Rumpf ist kein Formular: `value` als Formularfeld (`application/x-www-form-urlencoded`) oder als Query-Parameter `?value=…` senden." } }, "operationId": "setDocumentAttribute" }, "delete": { "tags": [ "documents" ], "description": "Entfernt das Attribut mit dem angegebenen `key` vom Dokument.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "key", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "deleteDocumentAttribute" } }, "/documents/{documentID}/pdf": { "get": { "tags": [ "documents" ], "description": "Liefert eine PDF-Vorschau des referenzierten Dokuments. Empfohlen zur Sichtprüfung nach Upload oder Transformation.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "file" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." } }, "operationId": "getDocumentPdf" } }, "/documents/{documentID}/png": { "get": { "tags": [ "documents" ], "description": "Liefert eine PNG-Vorschau des referenzierten Dokuments.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "file" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." } }, "operationId": "getDocumentPng" } }, "/documents/{documentID}/transformations": { "put": { "tags": [ "documents", "corrections" ], "description": "Wendet eine Transformation auf das Dokument an.\n\n- Ohne `pages`-Liste wird nur die **erste Seite** transformiert. Für **alle** Seiten `[-1]` als `pages` übergeben.\n- Jede Transformation wird stets auf die **Originalversion** des Dokuments angewendet.\n- Nach einer Transformation wird das Dokument **erneut validiert** – prüfen Sie danach den `status`.\n\n**Geometrie:**\n- `offsetX` / `offsetY` verschieben das Dokument horizontal / vertikal in **mm**; Ursprung ist die obere linke Ecke der Seite.\n- `scaleX` / `scaleY` skalieren unabhängig; Faktor `1` = 100 %, Werte `< 1` verkleinern. Die Skalierung bezieht sich auf die **Seitenmitte**.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "transformation", "in": "body", "required": true, "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "integer", "format": "int32" }, "example": [ -1 ], "default": [ 1 ] }, "scaleX": { "type": "number", "format": "double" }, "scaleY": { "type": "number", "format": "double" }, "offsetX": { "type": "number", "format": "double" }, "offsetY": { "type": "number", "format": "double" } } } } ], "responses": { "200": { "description": "Dokument aktualisiert.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." } }, "operationId": "applyDocumentTransformation" }, "delete": { "tags": [ "documents", "corrections" ], "description": "Entfernt die angewendete Transformation und setzt das Dokument auf seine Originalversion zurück.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." } }, "operationId": "resetDocumentTransformation" } }, "/documents/{documentID}/coverpage": { "put": { "tags": [ "documents", "corrections" ], "description": "Erzeugt ein Deckblatt für das Dokument. Die Empfängeradresse ist **Pflicht**; die Absenderadresse und der Text unterhalb der Adresse sind optional.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "coverPage", "in": "body", "schema": { "type": "object", "required": [ "receivingAddress" ], "properties": { "receivingAddress": { "$ref": "#/definitions/Address" }, "returnAddress": { "$ref": "#/definitions/Address" }, "coverText": { "description": "Optionaler Textblock auf dem Deckblatt (Betreff, Datum und Fließtext).", "type": "object", "required": [ "text" ], "properties": { "subject": { "description": "Optionale Betreffzeile auf dem Deckblatt.", "type": "string" }, "date": { "description": "Optionales Datum auf dem Deckblatt.", "type": "string", "format": "date" }, "text": { "description": "Fließtext auf dem Deckblatt. Nur Klartext; eine neue Zeile mit einem Zeilenumbruch (`\\n`) beginnen.", "type": "string" } } } } } } ], "responses": { "200": { "description": "Dokument aktualisiert.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." } }, "operationId": "setDocumentCoverPage" }, "delete": { "tags": [ "documents", "corrections" ], "description": "Entfernt das Deckblatt vom Dokument.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." } }, "operationId": "deleteDocumentCoverPage" } }, "/documents/{documentID}/attachments": { "get": { "tags": [ "documents", "attachments" ], "description": "Liefert alle Anhänge des Dokuments.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Liste der Anhänge des Dokuments.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "listDocumentAttachments" }, "post": { "tags": [ "documents", "attachments" ], "description": "Lädt einen neuen Anhang hoch und hängt ihn an das Dokument an – nach bereits angehängten Anhängen. Liefert die vollständige Anhangsliste des Dokuments zurück.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "appendAttachment", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "newSheet": { "description": "Bei `true` beginnt der Anhang auf der Vorderseite eines neuen Blattes. Fehlt das Feld, gilt die im Kundenportal unter **Mein Konto → Einstellungen** gewählte Vorgabe, sonst `true`. Bei beidseitigem Druck und ungerader Seitenzahl vor dem Anhang wird dafür eine Leerseite eingefügt; sie zählt zur Seitenzahl und wird berechnet.", "type": "boolean" }, "remarks": { "description": "Freitext-Bemerkungen zum Anhang.", "type": "string" } } } } ], "responses": { "200": { "description": "Anhang erstellt und an das Dokument angehängt.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten. Es wurde nichts angehängt." } }, "operationId": "uploadDocumentAttachment" }, "patch": { "tags": [ "documents", "attachments" ], "description": "Hängt eine Liste bereits hochgeladener Anhänge (per ID) an das Dokument an. Bereits angehängte Anhänge bleiben unverändert; die neuen werden in Listenreihenfolge am Ende angehängt. Auf die Reihenfolge achten, falls relevant.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "attachmentIDs", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "Anhänge angehängt; die Anhangsliste des Dokuments wird zurückgegeben.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten. Es wurde nichts angehängt." } }, "operationId": "appendDocumentAttachments" }, "delete": { "tags": [ "documents", "attachments" ], "description": "Entfernt alle Anhänge vom Dokument. Nur vor der Versandfreigabe möglich.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten." } }, "operationId": "deleteDocumentAttachments" } }, "/documents/{documentID}/attachments/{attachmentID}": { "post": { "tags": [ "documents", "attachments" ], "description": "Hängt einen bereits hochgeladenen Anhang (per `attachmentID`) an das Dokument an – nach bereits angehängten Anhängen. Liefert das Dokument zurück.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten. Es wurde nichts angehängt." } }, "operationId": "appendDocumentAttachment" }, "delete": { "tags": [ "documents", "attachments" ], "description": "Entfernt den Anhang vom Dokument.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang. Ein Anhang eines Dokuments eines anderen Accounts ergibt `403`." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Fragen Sie `documents/{documentID}/status` ab und versuchen Sie es danach erneut; ist die Beauftragung gescheitert, lässt sich der Brief wieder bearbeiten. Die Anlage bleibt angehängt." } }, "operationId": "removeDocumentAttachment" } }, "/sendings": { "delete": { "tags": [ "sendings" ], "description": "Löscht mehrere abgeschlossene Sendungen in einer Anfrage – stornierte, versendete, zugestellte oder zurückgelaufene. Die Mengen-Variante von `DELETE /sendings/{documentID}`, deren Verhalten unverändert bleibt.\n\nJede ID wird **für sich** versucht; eine nicht löschbare ID hält die übrigen nicht auf und lässt ihren Brief in diesem Moment unangetastet. Die Antwort ist immer `200` mit einem Eintrag je **verschiedener** angefragter ID, in der Reihenfolge der Anfrage – doppelte IDs werden zusammengefasst, **die Zuordnung erfolgt deshalb über `id`, niemals über die Position**. `deleted` sagt, ob gelöscht wurde, `error` nennt den Grund, wenn nicht: dieselben Fehlercodes wie die Einzel-Variante (`4404` unbekannt oder bereits gelöscht, `4403` fremdes Konto, `44091` Zustand erlaubt das Löschen nicht, `4500` harter Fehler), dazu `44092`, das nur diese Mengen-Variante liefert, für einen Serienbrief, den seine Einzelbriefe blockieren. **Jeden Eintrag prüfen; der HTTP-Status sagt nichts über die einzelnen Ergebnisse.**\n\nDas Löschen eines Serienbriefes löscht seine Einzelbriefe mit; `deletedChildren` nennt deren Anzahl, ohne sie aufzuzählen. Steht ein Einzelbrief zusammen mit seinem Serienbrief in derselben Anfrage, wird der Serienbrief zuerst bearbeitet, und der Einzelbrief meldet `deleted: true` mit `deletedAsChildOf` – nicht `4404`. Es gilt auch andersherum: das Löschen des **letzten** verbliebenen Einzelbriefs eines Serienbriefs löscht den Serienbrief mit, auch wenn dieser gar nicht angefragt war – er hat dann keinen eigenen Eintrag in der Antwort. Die Operation ist **nicht atomar**: ein Teilergebnis ist echt und wird nicht zurückgenommen.\n\nDie IDs werden als wiederholte Parameter übergeben (`?documentIds=17&documentIds=18`); eine Kommaliste wird **nicht** angenommen. Höchstens `maxDelete` IDs je Anfrage (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits), standardmäßig 250) – darüber `413` mit Fehlercode `44008`, und es wird nichts gelöscht.", "produces": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "query", "required": true, "type": "array", "collectionFormat": "multi", "items": { "type": "integer", "format": "int32" }, "description": "Die zu löschenden Dokument-IDs, als wiederholte Parameter." } ], "responses": { "200": { "description": "Erfolgreiche Antwort – ein Eintrag je angefragter ID. Einzelne IDs können trotzdem abgelehnt worden sein; `deleted` und `error` je Eintrag prüfen.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentDeletionStatus" } } }, "400": { "description": "Ungültige Anfrage – `documentIds` fehlt, ist leer oder trägt einen leeren Wert (`?documentIds=`). Fehlercode `4400`. Es wurde nichts gelöscht." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Anfrage zu groß – mehr IDs als `maxDelete` aus `GET /accounts/limits` zulässt (standardmäßig 250). Fehlercode `44008`. Es wurde nichts gelöscht; die Liste in Blöcke aufteilen." } }, "operationId": "deleteSendings" }, "post": { "tags": [ "sendings" ], "description": "Gibt ein oder mehrere bereits hochgeladene, valide Dokumente zum Versand frei – die **Versandfreigabe**. Übergeben Sie die `documentIds` von Dokumenten mit Status `versandbereit` (Code 2). Die Übergabe in die Produktion erfolgt standardmäßig um **14:30 Uhr**.\n\nAb diesem Zeitpunkt wird ein Dokument über `/sendings` verwaltet (Status, Stornierung), nicht mehr über `/documents`.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": false, "minLength": 1, "maxLength": 128, "description": "Optionaler, vom Client gewählter Schlüssel (z. B. eine UUID), der diese Anfrage gefahrlos wiederholbar macht. Geltung: dieser Account, diese Operation, für mindestens 7 Tage. Gleicher Schlüssel und gleicher Inhalt: die gespeicherte Antwort der ersten Anfrage wird mit `Idempotent-Replayed: true` erneut geliefert; es wird nichts doppelt bezahlt oder versendet. Gleicher Schlüssel mit anderem Inhalt: `422`, Fehlercode `44011`. Gleicher Schlüssel, während die erste Anfrage noch läuft: `409`, Fehlercode `44010`. Gespeichert werden nur erfolgreiche Antworten; nach einem Fehler darf der Schlüssel erneut verwendet werden. 1–128 druckbare ASCII-Zeichen, sonst `400`." } ], "responses": { "409": { "description": "Konflikt – eine Anfrage mit diesem `Idempotency-Key` wird noch verarbeitet. Fehlercode `44010`. Nach Abschluss der ersten Anfrage erneut versuchen." }, "422": { "description": "Nicht verarbeitbar – dieser `Idempotency-Key` wurde bereits mit anderem Inhalt verwendet. Fehlercode `44011`. Für eine neue Anfrage einen neuen Schlüssel verwenden." }, "200": { "headers": { "Idempotent-Replayed": { "type": "boolean", "description": "`true`, wenn dies die gespeicherte Antwort der ersten Anfrage mit demselben `Idempotency-Key` ist; es wurde nichts erneut verarbeitet. Fehlt bei der ersten Ausführung und ohne `Idempotency-Key`." } }, "description": "Versand angenommen – die Antwort listet die Dokumente und ihren Status (ein Dokument kann fehlerhaft sein, Code 7).", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." }, "413": { "description": "Anfrage zu groß – mehr documentIds als `maxSendings` aus `GET /accounts/limits` zulässt (standardmäßig 500). Fehlercode `44009`. Es wurde nichts bezahlt, eingeliefert oder storniert; die Liste in Blöcke aufteilen." } }, "operationId": "releaseForDispatch" }, "get": { "tags": [ "sendings" ], "description": "Liefert Dokumente **ab der Versandfreigabe**, jedes mit allen Details - also die Statusabfrage plus alles, was über die Sendung bekannt ist.\n\nStatuscodes (`status.code` -> `status.text`):\n- **1** - `wird erstellt` (en `being created`) - die Freigabe wird gerade abgewickelt (Bezahlung, Übergabe an die Produktion)\n- **3** - `in Verarbeitung` (en `processing`)\n- **4** - `im Druck` (en `printing`)\n- **5** - `versendet` (en `sent`)\n- **6** - `storniert` (en `cancelled`)\n- **7** - `fehlerhaft` (en `faulty`)\n- **8** - `zugestellt` (en `delivered`) - nur Einschreiben, Endzustand\n- **9** - `zurückgelaufen` (en `returned to sender`) - nur Einschreiben, Endzustand\n\nGeliefert werden nur die hochgeladenen Briefe selbst; die Einzelbriefe eines Serienbriefs stehen nicht in dieser Liste. Wer sie braucht, nimmt `GET /sendings/status` oder `GET /status`.\n\n**Zeitpunkt:** nach der Versandfreigabe ist der Status erst **ab 05:00 des Folgetags** aussagekräftig, und nur wenn die Sendung das **Versandfenster 14:30** erreicht hat - erst dann wird er fortgeschrieben.\n\nWeil jeder Eintrag das vollständige Dokument trägt, wächst die Antwort schnell. Ohne `limit` ist die Menge auf `maxRead` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) begrenzt (standardmäßig 500); darüber antwortet die Schnittstelle mit `413` und Fehlercode `44007`. Für reines Statuspollen sind `GET /sendings/status` bzw. `GET /status` die richtige Wahl.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Antwort zu groß - mehr lesbare Dokumente als `maxRead` aus `GET /accounts/limits` zulässt (standardmäßig 500) oder `limit` darüber. Fehlercode `44007`. `limit` und `offset` verwenden." } }, "operationId": "listSendings" }, "put": { "tags": [ "sendings" ], "description": "Storniert den Versand der angegebenen Dokumente (per `documentIds`). Nur **noch nicht versendete** Dokumente können storniert werden; eine Stornierung ist bis **kurz vor dem 14:30-Versandfenster** möglich.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "Liste der Dokumentstatus (`documentID` und `status`). Bei einem Serienbrief werden auch die Status der Kind-Dokumente aufgeführt.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." }, "413": { "description": "Anfrage zu groß – mehr documentIds als `maxSendings` aus `GET /accounts/limits` zulässt (standardmäßig 500). Fehlercode `44009`. Es wurde nichts bezahlt, eingeliefert oder storniert; die Liste in Blöcke aufteilen." } }, "operationId": "cancelDispatch" } }, "/sendings/document": { "post": { "tags": [ "sendings" ], "description": "Lädt ein Dokument hoch und versendet es bei erfolgreicher Validierung **direkt** – kombiniert [`POST /documents`](#op:documents:uploadDocument:post:/documents) und [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings) in einem Aufruf. Es gelten dieselben Dateiregeln wie beim Upload (PDF/PS, PDF/A-2b, max. **20 MB**, Base64).\n\n**Zuverlässigkeit:** Bei HTTP `500` kann das Dokument dennoch erstellt worden sein. Geben Sie eine eindeutige `externalReferenceId` mit und prüfen Sie vor einem erneuten Versuch über `GET /documents/findByExternalReferenceId` (ein Treffer bedeutet: angekommen) - oder senden Sie einen `Idempotency-Key`, dann versendet eine Wiederholung mit demselben Schlüssel nicht doppelt.", "consumes": [ "application/json" ], "parameters": [ { "name": "shipping", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "options": { "$ref": "#/definitions/Options" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } }, "tenantId": { "type": "string", "maxLength": 32, "example": "kostenstelle-4711", "description": "Ihre interne Kunden-/Mandantennummer für diesen Auftrag (max. 32 Zeichen). Wird am Auftrag gespeichert und in die Produktion übergeben. Ersetzt das frühere Custom-Attribute `tenant`. Steuerzeichen (z. B. Tabulator, Zeilenumbruch), unsichtbare Formatierungszeichen und Sonderleerzeichen (z. B. geschütztes Leerzeichen) werden mit HTTP 400 abgewiesen; die Meldung nennt Position und Zeichen. Alte Custom-Attribute mit solchen Zeichen werden nicht übernommen." }, "externalReferenceId": { "type": "string", "maxLength": 64, "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "description": "Ihre interne Referenz-ID für diesen Auftrag (max. 64 Zeichen); ideal ist eine **UUID**. Suchbar über `GET /documents/findByExternalReferenceId`. Ersetzt das frühere Custom-Attribute `documentID`. Steuerzeichen (z. B. Tabulator, Zeilenumbruch), unsichtbare Formatierungszeichen und Sonderleerzeichen (z. B. geschütztes Leerzeichen) werden mit HTTP 400 abgewiesen; die Meldung nennt Position und Zeichen. Alte Custom-Attribute mit solchen Zeichen werden nicht übernommen." }, "externalReferenceIdUnique": { "type": "boolean", "default": false, "description": "Optionaler Doppel-Einlieferungsschutz. Bei `true` wird die Anfrage abgelehnt, wenn bereits ein anderer Ihrer Aufträge diese `externalReferenceId` trägt (Schutz vor versehentlichen Doppel-Einlieferungen)." }, "responseFormat": { "$ref": "#/definitions/ResponseFormatEnum" } }, "example": { "content": { "filename": "musterbrief.pdf", "content": "" }, "tenantId": "kostenstelle-4711", "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": false, "minLength": 1, "maxLength": 128, "description": "Optionaler, vom Client gewählter Schlüssel (z. B. eine UUID), der diese Anfrage gefahrlos wiederholbar macht. Geltung: dieser Account, diese Operation, für mindestens 7 Tage. Gleicher Schlüssel und gleicher Inhalt: die gespeicherte Antwort der ersten Anfrage wird mit `Idempotent-Replayed: true` erneut geliefert; es wird nichts doppelt bezahlt oder versendet. Gleicher Schlüssel mit anderem Inhalt: `422`, Fehlercode `44011`. Gleicher Schlüssel, während die erste Anfrage noch läuft: `409`, Fehlercode `44010`. Gespeichert werden nur erfolgreiche Antworten; nach einem Fehler darf der Schlüssel erneut verwendet werden. 1–128 druckbare ASCII-Zeichen, sonst `400`." } ], "responses": { "409": { "description": "Konflikt – eine Anfrage mit diesem `Idempotency-Key` wird noch verarbeitet. Fehlercode `44010`. Nach Abschluss der ersten Anfrage erneut versuchen. Außerdem: Das Dokument existiert, kann in seinem aktuellen Zustand aber nicht versendet werden (fehlerhaft, noch in der Prüfung, in Beauftragung, bereits bezahlt oder versendet; bei einem Serienbrief muss jeder Einzelbrief versandbereit sein) – Fehlercode `44093`. Status über `documents/{documentID}/status` abfragen und erneut versuchen, sobald das Dokument versandbereit ist." }, "422": { "description": "Nicht verarbeitbar – dieser `Idempotency-Key` wurde bereits mit anderem Inhalt verwendet. Fehlercode `44011`. Für eine neue Anfrage einen neuen Schlüssel verwenden." }, "200": { "headers": { "Idempotent-Replayed": { "type": "boolean", "description": "`true`, wenn dies die gespeicherte Antwort der ersten Anfrage mit demselben `Idempotency-Key` ist; es wurde nichts erneut verarbeitet. Fehlt bei der ersten Ausführung und ohne `Idempotency-Key`." } }, "description": "Dokument erstellt und versendet – kann fehlerhaft sein (prüfen Sie `status`; Code 7 = fehlerhaft).", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." }, "413": { "description": "Anfrage zu groß – die Datei überschreitet die maximale Upload-Größe (20 MB, siehe `maxUploadSize` in `GET /accounts/limits`)." } }, "operationId": "uploadAndSendDocument" } }, "/sendings/status": { "get": { "tags": [ "sendings", "status" ], "description": "Liefert den Status von Dokumenten **ab der Versandfreigabe** - `documentID` sowie `status` (`code` und `text`), keine Dokumentdetails.\n\nStatuscodes in dieser Phase:\n- **1** - `wird erstellt` (en `being created`) - die Freigabe wird gerade abgewickelt (Bezahlung, Übergabe an die Produktion)\n- **3** `in Verarbeitung`, **4** `im Druck`, **5** `versendet`, **6** `storniert`, **7** `fehlerhaft`, **8** `zugestellt` (nur Einschreiben), **9** `zurückgelaufen` (nur Einschreiben)\n\n`documentIds` ändert das Verhalten:\n- **mit** `documentIds`: genau die angefragten Dokumente, und zwar in **jedem** Zustand - eine Abfrage nach IDs ist nicht an die Phase gebunden. IDs, die nicht lesbar sind, werden weggelassen; `404` nur, wenn keine davon lesbar ist.\n- **ohne** `documentIds`: alle Sendungen des Kontos, einschließlich der Einzelbriefe eines Serienbriefs.\n\nZum Blättern `limit` und `offset` verwenden. Ohne `limit` ist die Menge auf `maxReadStatus` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) begrenzt (standardmäßig 5000); darüber antwortet die Schnittstelle mit `413` und Fehlercode `44007`.\n\n**Ab wann geliefert wird:** ohne `documentIds` erscheint ein Brief hier erst mit der Versandfreigabe - davor beantwortet ihn `GET /documents/status`. `GET /status` umspannt beide Phasen und hat diesen Bruch nicht.\n\n**Zeitpunkt:** der Fortschritt ist erst **ab 05:00 des Folgetags** aussagekräftig, und nur wenn die Sendung das **Versandfenster 14:30** erreicht hat.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "413": { "description": "Antwort zu groß - mehr lesbare Dokumente als `maxReadStatus` aus `GET /accounts/limits` zulässt (standardmäßig 5000) oder `limit` darüber. Fehlercode `44007`. `limit` und `offset` verwenden." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Sendung nicht gefunden - keine der in `documentIds` angegebenen IDs ist für dieses Konto lesbar. Ohne `documentIds` tritt dieser Code nicht auf; ein Konto ohne Sendungen erhält eine leere Liste mit 200." } }, "operationId": "listSendingStatus" } }, "/sendings/{documentID}/status": { "get": { "tags": [ "sendings", "status" ], "description": "Liefert den Status eines einzelnen Dokuments (`code` und `text`; alle Codes stehen im Modell `Status`).\n\n**Nicht an die Phase gebunden**, anders als der Pfad vermuten lässt: eine Abfrage nach einer einzelnen ID wird in jedem Zustand beantwortet - vor der Versandfreigabe, danach und nach der Zustellung. Dieser Endpunkt, `GET /sendings/{documentID}/status` und `GET /status/{documentID}` liefern deshalb dasselbe; für neue Anbindungen ist `GET /status/{documentID}` der Name, der das auch sagt.\n\n`404` tritt nur auf, wenn das Dokument nicht existiert, zu einem anderen Konto gehört oder gelöscht ist - per `DELETE /documents/{documentID}` oder durch die Aufbewahrungsfrist.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getSendingStatus" } }, "/sendings/{documentID}": { "post": { "tags": [ "sendings" ], "description": "Gibt ein einzelnes Dokument zum Versand frei, sofern es noch nicht versendet wurde (Einzel-Variante von [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": false, "minLength": 1, "maxLength": 128, "description": "Optionaler, vom Client gewählter Schlüssel (z. B. eine UUID), der diese Anfrage gefahrlos wiederholbar macht. Geltung: dieser Account, diese Operation, für mindestens 7 Tage. Gleicher Schlüssel und gleicher Inhalt: die gespeicherte Antwort der ersten Anfrage wird mit `Idempotent-Replayed: true` erneut geliefert; es wird nichts doppelt bezahlt oder versendet. Gleicher Schlüssel mit anderem Inhalt: `422`, Fehlercode `44011`. Gleicher Schlüssel, während die erste Anfrage noch läuft: `409`, Fehlercode `44010`. Gespeichert werden nur erfolgreiche Antworten; nach einem Fehler darf der Schlüssel erneut verwendet werden. 1–128 druckbare ASCII-Zeichen, sonst `400`." } ], "responses": { "409": { "description": "Konflikt – eine Anfrage mit diesem `Idempotency-Key` wird noch verarbeitet. Fehlercode `44010`. Nach Abschluss der ersten Anfrage erneut versuchen. Außerdem: Das Dokument existiert, kann in seinem aktuellen Zustand aber nicht versendet werden (fehlerhaft, noch in der Prüfung, in Beauftragung, bereits bezahlt oder versendet; bei einem Serienbrief muss jeder Einzelbrief versandbereit sein) – Fehlercode `44093`. Status über `documents/{documentID}/status` abfragen und erneut versuchen, sobald das Dokument versandbereit ist." }, "422": { "description": "Nicht verarbeitbar – dieser `Idempotency-Key` wurde bereits mit anderem Inhalt verwendet. Fehlercode `44011`. Für eine neue Anfrage einen neuen Schlüssel verwenden." }, "200": { "headers": { "Idempotent-Replayed": { "type": "boolean", "description": "`true`, wenn dies die gespeicherte Antwort der ersten Anfrage mit demselben `Idempotency-Key` ist; es wurde nichts erneut verarbeitet. Fehlt bei der ersten Ausführung und ohne `Idempotency-Key`." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "releaseDocumentForDispatch" }, "get": { "tags": [ "sendings" ], "description": "Liefert eine referenzierte Sendung. Die Sendung ist ein Einzelbrief, ein Serienbrief oder ein `error`-Objekt.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." } }, "operationId": "getSending" }, "put": { "tags": [ "sendings" ], "description": "Storniert den Versand eines einzelnen Dokuments, sofern es noch nicht versendet wurde (Einzel-Variante der Stornierung).", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Status" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument. Ein Dokument eines anderen Accounts ergibt `403`." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." }, "409": { "description": "Konflikt – das Dokument wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und lässt sich noch nicht stornieren. Fehlercode `44090`. Fragen Sie `sendings/{documentID}/status` ab und versuchen Sie es nach der Beauftragung erneut; ob der Brief sich dann stornieren lässt, hängt von seinem neuen Zustand ab (sonst `406`)." } }, "operationId": "cancelDocumentDispatch" }, "delete": { "tags": [ "sendings" ], "description": "Löscht ein abgeschlossenes Dokument aus dem System - also ein storniertes oder ein zugestelltes und versendetes. Damit werden erledigte Einträge entfernt.\n\nGelöscht werden kann nur, solange der Zustand des Briefes es zulässt. Ein Brief, der verarbeitet wird (wartet auf Validierung, wird validiert, Bezahlung oder Übergabe läuft), der in Produktion oder gedruckt ist oder für den ein Storno beantragt wurde, ist **nicht** löschbar - die Antwort ist dann `409` mit Fehlercode `44091`, und der Brief bleibt unangetastet. Bei einem Serienbrief muss jeder Einzelbrief löschbar sein.\n\nLöschen markiert den Brief als gelöscht; ein Brief, der bereits an die Produktion übergeben wurde, wird dadurch **nicht** zurückgerufen.", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "409": { "description": "Konflikt - das Dokument existiert, kann in seinem aktuellen Zustand aber nicht gelöscht werden. Fehlercode `44091`. Nicht löschbar ist ein Brief, solange er verarbeitet wird, solange er in Produktion oder gedruckt ist und solange ein Storno beantragt ist; bei einem Serienbrief muss jeder Einzelbrief löschbar sein. Status abfragen und wiederholen, sobald ein Endzustand erreicht ist." }, "404": { "description": "Dokument nicht gefunden - zur `documentID` gibt es kein Dokument, oder es ist bereits als gelöscht markiert. Ein Dokument eines anderen Kontos ergibt `403`, ein vorhandenes, das gerade nicht löschbar ist, ergibt `409`." } }, "operationId": "deleteSending" } }, "/regmails/": { "get": { "tags": [ "regmails", "sendings", "status" ], "description": "Liefert Status und Sendungsverfolgung von Einschreiben - je Eintrag `documentID`, `product`, `status` (`code` und `text`) und, sobald vorhanden, `tracking` mit Sendungsnummer und Verfolgungs-Adresse.\n\nDie Sendungsverfolgung entsteht erst mit der Auslieferung; davor fehlt `tracking`. Danach ist sie bis zum Briefkasten verfolgbar, und der Status erreicht **8** `zugestellt` oder **9** `zurückgelaufen` - beides Endzustände, die es nur bei Einschreiben gibt.\n\n`documentIds` ändert das Verhalten:\n- **mit** `documentIds`: genau die angefragten Einschreiben. Gehört eine der IDs nicht zu diesem Konto, wird die Anfrage **vollständig** mit `403` abgelehnt - anders als bei `GET /status`, wo nicht lesbare IDs einzeln weggelassen werden.\n- **ohne** `documentIds`: alle Einschreiben des Kontos.\n\nZum Blättern `limit` und `offset` verwenden. Ohne `limit` ist die Menge auf `maxReadStatus` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) begrenzt (standardmäßig 5000); darüber antwortet die Schnittstelle mit `413` und Fehlercode `44007`.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/RegmailStatus" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Antwort zu groß - mehr Einschreiben als `maxReadStatus` aus `GET /accounts/limits` zulässt (standardmäßig 5000). Fehlercode `44007`. `limit` und `offset` verwenden." }, "404": { "description": "Nicht gefunden - keiner der angefragten Aufträge ist ein Einschreiben. Sie gehören alle zu diesem Konto; eine fremde oder unbekannte ID ergibt stattdessen `403`. Ohne `documentIds` tritt dieser Code nicht auf: ein Konto ohne Einschreiben erhält eine leere Liste mit 200." } }, "operationId": "listRegisteredMail" } }, "/regmails/{documentID}": { "get": { "tags": [ "regmails", "sendings", "status" ], "description": "Liefert Status und Sendungsverfolgung EINES Einschreibens (`product`, `status`, und sobald vorhanden `tracking`).\n\nDie Sendungsverfolgung entsteht erst mit der Auslieferung und ist dann bis zum Briefkasten verfolgbar; die Endzustände **8** `zugestellt` und **9** `zurückgelaufen` gibt es nur bei Einschreiben.\n\nDie Antwort ist ein einzelnes Objekt mit fest umrissenem Inhalt - es gibt darin keine Liste, die wachsen könnte. Deshalb hat dieser Endpunkt bewusst KEIN `limit`/`offset`: ein solcher Parameter wäre ohne Wirkung. Wer über mehrere Einschreiben blättern will, nimmt `GET /regmails` mit `documentIds`, `limit` und `offset`.\n\n`403` deckt beides ab: der Auftrag gehört einem anderen Konto ODER es gibt ihn nicht. Die beiden Fälle werden bewusst nicht unterschieden - so verrät die Antwort nicht, ob eine fremde ID existiert.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/RegmailStatus" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Nicht gefunden - der Auftrag gehört zu diesem Konto, ist aber kein Einschreiben; es gibt also keine Sendungsverfolgung dazu. Eine fremde oder unbekannte `documentID` ergibt `403`, nicht `404`." } }, "operationId": "getRegisteredMail" } }, "/status": { "get": { "tags": [ "status" ], "description": "Liefert den Status von Dokumenten in **jeder** Phase ihres Lebenszyklus - vor der Versandfreigabe, danach und nach der Zustellung. Anders als `GET /documents/status` und `GET /sendings/status` ist dieser Endpunkt nicht an eine Phase gebunden: dieselbe `documentID` wird vom Upload bis zum Endzustand beantwortet, eine Abfrageschleife genügt.\n\nGeliefert wird nur der Status - `documentID` sowie `status` (`code` und `text`); **keine Dokumentdetails**. Dafür `GET /documents/{documentID}` (vor der Versandfreigabe) bzw. `GET /sendings/{documentID}` (danach) verwenden.\n\n`documentIds` ändert das Verhalten:\n- **mit** `documentIds`: genau die angefragten Dokumente, in jedem Zustand. IDs, die nicht existieren, zu einem anderen Konto gehören oder gelöscht sind, werden weggelassen; `404` nur, wenn keine davon lesbar ist.\n- **ohne** `documentIds`: alle Dokumente des Kontos, einschließlich der Einzelbriefe eines Serienbriefs (die über diese API einzeln versendet werden können). Entwürfe und im Webportal in Arbeit befindliche Briefe werden nie geliefert.\n\nZum Blättern `limit` und `offset` verwenden. Ohne `limit` ist die Menge auf `maxReadStatus` aus [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) begrenzt (standardmäßig 5000); darüber antwortet die Schnittstelle mit `413` und Fehlercode `44007`.\n\nNichts geliefert wird, sobald ein Dokument gelöscht ist - per `DELETE /documents/{documentID}` oder durch die Aufbewahrungsfrist.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort - die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "413": { "description": "Antwort zu groß - mehr lesbare Dokumente als `maxReadStatus` aus `GET /accounts/limits` zulässt (standardmäßig 5000) oder `limit` darüber. Fehlercode `44007`. `limit` und `offset` verwenden." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden - keine der in `documentIds` angegebenen IDs ist für dieses Konto lesbar. Ohne `documentIds` tritt dieser Code nicht auf; ein Konto ohne Dokumente erhält eine leere Liste mit 200." } }, "operationId": "listLifecycleStatus" } }, "/status/{documentID}": { "get": { "tags": [ "status" ], "description": "Liefert den Status **eines** Dokuments in jeder Phase seines Lebenszyklus (`code` und `text`). Die `documentID` bleibt über den gesamten Lebenszyklus gültig: anders als die phasengebundenen Endpunkte antwortet dieser auch nach der Versandfreigabe und nach der Zustellung. Einzelbriefe eines Serienbriefs werden ebenfalls beantwortet.\n\nGeliefert wird nur der Status - **keine Dokumentdetails**; dafür `GET /documents/{documentID}` bzw. `GET /sendings/{documentID}` verwenden.\n\n`404` tritt nur auf, wenn das Dokument nicht existiert, zu einem anderen Konto gehört oder gelöscht ist - per `DELETE /documents/{documentID}` oder durch die Aufbewahrungsfrist.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort - die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden - das Dokument existiert nicht, gehört zu einem anderen Konto oder ist gelöscht." } }, "operationId": "getLifecycleStatus" } }, "/attachments": { "post": { "tags": [ "attachments" ], "description": "Lädt einen neuen Anhang in den Anhang-Pool hoch. Der Anhang kann anschließend an Dokumente angehängt werden (z. B. über `POST /documents/{documentID}/attachments/{attachmentID}`).", "consumes": [ "application/json" ], "parameters": [ { "name": "attachmentData", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "newSheet": { "description": "Bei `true` beginnt der Anhang auf der Vorderseite eines neuen Blattes. Fehlt das Feld, gilt die im Kundenportal unter **Mein Konto → Einstellungen** gewählte Vorgabe, sonst `true`. Bei beidseitigem Druck und ungerader Seitenzahl vor dem Anhang wird dafür eine Leerseite eingefügt; sie zählt zur Seitenzahl und wird berechnet.", "type": "boolean" }, "remarks": { "description": "Freitext-Bemerkungen zum Anhang.", "type": "string" } } } } ], "responses": { "200": { "description": "Anhang im Pool erstellt.", "schema": { "$ref": "#/definitions/Attachment" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Anfrage zu groß – die Datei überschreitet die maximale Upload-Größe (20 MB, siehe `maxUploadSize` in `GET /accounts/limits`)." } }, "operationId": "uploadAttachment" }, "get": { "tags": [ "attachments" ], "description": "Liefert alle Anhänge im Pool.", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "listAttachments" } }, "/attachments/{attachmentID}": { "get": { "tags": [ "attachments" ], "description": "Liefert den referenzierten Anhang.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Attachment" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." } }, "operationId": "getAttachment" }, "delete": { "tags": [ "attachments" ], "description": "Löscht den referenzierten Anhang. Nur möglich, wenn er an keinem noch nicht versendeten Dokument hängt – vorher per `DELETE /attachments/{attachmentID}/documents` lösen.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." } }, "operationId": "deleteAttachment" } }, "/attachments/{attachmentID}/pdf": { "get": { "tags": [ "attachments" ], "description": "Liefert eine PDF-Vorschau des referenzierten Anhangs.", "parameters": [ { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "file" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." } }, "operationId": "getAttachmentPdf" } }, "/attachments/{attachmentID}/png": { "get": { "tags": [ "attachments" ], "description": "Liefert eine PNG-Vorschau der ersten Seite des referenzierten Anhangs.", "parameters": [ { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "file" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." }, "406": { "description": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar)." } }, "operationId": "getAttachmentPng" } }, "/attachments/{attachmentID}/documents": { "get": { "tags": [ "attachments" ], "description": "Liefert alle noch nicht versendeten Dokumente, an die dieser Anhang angehängt ist.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." } }, "operationId": "listAttachmentDocuments" }, "patch": { "tags": [ "attachments" ], "description": "Hängt diesen Anhang an alle Dokumente der Liste an – jeweils am Ende des Dokuments, nach bereits vorhandenen Anhängen.", "consumes": [ "application/json" ], "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" }, { "name": "doumentIDs", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "Anhang an alle Dokumente der Liste angehängt.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." }, "409": { "description": "Konflikt – mindestens eines der Dokumente wird gerade beauftragt (zur Bezahlung und zum Versand freigegeben) und ist gesperrt, bis die Beauftragung abgeschlossen ist. Fehlercode `44090`. Die Anlage wurde an keines der Dokumente angehängt. Fragen Sie deren Status ab und versuchen Sie es danach erneut." } }, "operationId": "attachToDocuments" }, "delete": { "tags": [ "attachments" ], "description": "Entfernt den referenzierten Anhang aus allen noch nicht versendeten Dokumenten.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." } }, "operationId": "detachFromDocuments" } }, "/accounts": { "get": { "tags": [ "accounts" ], "description": "Liefert die Finanzdaten des Accounts (z. B. Guthaben).", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Account" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "getAccount" } }, "/accounts/limits": { "get": { "tags": [ "accounts" ], "description": "Liefert die wirksamen Schranken dieser Umgebung (Produktion bzw. Test): das höchste `limit` je Seite, die höchste Anzahl Ids je Mengenanfrage und die maximale Upload-Größe. Einmal beim Start lesen statt Vorgaben fest zu verdrahten; jedes `413` dieser API bezieht sich auf einen dieser Werte.", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Limits" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "getAccountLimits" } }, "/accounts/personaldata": { "get": { "tags": [ "accounts" ], "description": "Liefert die persönlichen Daten des Accounts.", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/User" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer." } }, "operationId": "getPersonalData" }, "patch": { "tags": [ "accounts" ], "description": "Aktualisiert die persönlichen Daten des Accounts.", "parameters": [ { "name": "personalData", "in": "body", "required": true, "schema": { "description": "Die persönlichen Daten des Kunden.", "type": "object", "properties": { "forename": { "type": "string" }, "surname": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "plz": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "title": { "type": "string" }, "phone": { "type": "string" }, "partnerId": { "type": "string" } } } } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/User" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer." } }, "operationId": "updatePersonalData" } }, "/accounts/options": { "get": { "tags": [ "accounts" ], "description": "Liefert die Standard-Versandoptionen des Accounts (werden auf neue Dokumente angewendet).", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer." } }, "operationId": "getAccountOptions" }, "put": { "tags": [ "accounts" ], "description": "Aktualisiert die Standard-Versandoptionen des Accounts.", "parameters": [ { "name": "defaultOptions", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Options" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer." } }, "operationId": "updateAccountOptions" } }, "/accounts/coworkers": { "get": { "tags": [ "accounts" ], "description": "Liefert die Mitarbeiter (Unterbenutzer) des Accounts.", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Coworker" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "listCoworkers" } }, "/accounts/coworkers/{debitornumber}/journal/{month}": { "get": { "tags": [ "accounts" ], "description": "Liefert alle Transaktionen des angegebenen Monats für einen bestimmten Mitarbeiter (per `debitornumber`).", "parameters": [ { "in": "path", "name": "debitornumber", "required": true, "type": "string" }, { "in": "path", "name": "month", "required": true, "type": "integer", "format": "int32" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" }, { "name": "order", "in": "query", "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "Sortierung nach Transaktions-Id: `asc` (älteste zuerst; Vorgabe) oder `desc` (neueste zuerst). Mit `desc` ist `offset=0` die jüngste Seite. Jeder andere Wert: `400`." } ], "responses": { "400": { "description": "Ungültige Anfrage – `order` ist weder `asc` noch `desc`, oder `limit`/`offset` sind ungültig. Fehlercode `4400`." }, "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer." }, "413": { "description": "Antwort zu groß – mehr Zeilen als `maxRead` aus `GET /accounts/limits` zulässt (standardmäßig 500) oder `limit` darüber. Fehlercode `44007`. `limit` (höchstens `maxRead`) und `offset` verwenden." } }, "operationId": "getCoworkerJournal" } }, "/accounts/journal/{month}": { "get": { "tags": [ "accounts" ], "description": "Liefert alle Transaktionen des angegebenen Monats für den Account.", "parameters": [ { "in": "path", "name": "month", "required": true, "type": "integer", "format": "int32" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" }, { "name": "order", "in": "query", "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "Sortierung nach Transaktions-Id: `asc` (älteste zuerst; Vorgabe) oder `desc` (neueste zuerst). Mit `desc` ist `offset=0` die jüngste Seite. Jeder andere Wert: `400`." } ], "responses": { "400": { "description": "Ungültige Anfrage – `order` ist weder `asc` noch `desc`, oder `limit`/`offset` sind ungültig. Fehlercode `4400`." }, "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Antwort zu groß – mehr Zeilen als `maxRead` aus `GET /accounts/limits` zulässt (standardmäßig 500) oder `limit` darüber. Fehlercode `44007`. `limit` (höchstens `maxRead`) und `offset` verwenden." } }, "operationId": "getAccountJournal" } }, "/accounts/authentication": { "get": { "tags": [ "accounts" ], "description": "Zeigt, wie diese Anfrage angemeldet wurde: das Verfahren (`PASSWORD` oder `API_KEY`), den Transportweg (`BASIC`, `BEARER`, `X_API_KEY`, `BASIC_BRIDGE` oder `RAW`), den Anmeldemodus dieses Logins (`authMode`) und die Client-IP-Adresse, die der Server sieht – gegen diese Adresse wird eine IP-Freigabeliste (`allowedIps`) geprüft. Mit einem API-Key angemeldet, beschreibt `apiKey` diesen Key (maskiert). Nützlich, um einen neuen Key oder die Einrichtung eines Clients zu prüfen.", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anmeldung dieser Anfrage.", "schema": { "$ref": "#/definitions/Authentication" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "getAuthentication" } }, "/invoices": { "get": { "tags": [ "invoices" ], "description": "Liefert Referenzen zu allen gespeicherten Rechnungen.", "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Invoice" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." } }, "operationId": "listInvoices" } }, "/invoices/{invoiceNumber}": { "get": { "tags": [ "invoices" ], "description": "Liefert alle Transaktionen der Rechnung.", "parameters": [ { "in": "path", "name": "invoiceNumber", "required": true, "type": "string" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Wirksame Seitengröße dieser Antwort: das gesendete `limit`, sonst die konfigurierte Schranke (siehe [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Fehlt, wenn die Antwort nicht geblättert wurde: Status-Abfragen mit ausdrücklichen `documentIds` liefern alle gefragten Ids auf einmal." }, "X-Page-Offset": { "type": "integer", "description": "Versatz dieser Seite (`0`, wenn keiner gesendet wurde)." }, "X-Next-Offset": { "type": "integer", "description": "Versatz der nächsten Seite. Nur vorhanden, wenn diese Seite voll war (so viele Zeilen wie `X-Page-Limit`), also weitere Zeilen folgen können. Fehlt die Kopfzeile, war dies die letzte Seite." }, "Link": { "type": "string", "description": "Web-Links (RFC 8288) auf die Nachbarseiten: `rel=\"next\"` nur, wenn diese Seite voll war, `rel=\"prev\"` nur bei `offset` über `0`. Die Pfade beginnen unter dem Basispfad der API und behalten alle Filter dieser Anfrage." } }, "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "413": { "description": "Antwort zu groß – mehr Zeilen als `maxRead` aus `GET /accounts/limits` zulässt (standardmäßig 500) oder `limit` darüber. Fehlercode `44007`. `limit` (höchstens `maxRead`) und `offset` verwenden." } }, "operationId": "getInvoiceTransactions" } }, "/invoices/{invoiceNumber}/pdf": { "get": { "tags": [ "invoices" ], "description": "Liefert die Rechnung als PDF.", "parameters": [ { "in": "path", "name": "invoiceNumber", "required": true, "type": "string" } ], "responses": { "200": { "description": "Die Rechnung als PDF.", "schema": { "type": "file" } }, "401": { "description": "Nicht angemeldet – keine oder fehlerhafte Zugangsdaten (z. B. keine Kopfzeile `Authorization` und kein API-Key in `X-API-Key`, unbekanntes Verfahren, ungültiges Base64; Fehlercode `4401`) oder ein ungültiger, deaktivierter bzw. abgelaufener API-Key (Fehlercodes `44012`, `44013`, `44014`). Die Kopfzeile `WWW-Authenticate` nennt das erwartete Verfahren: `Bearer realm=\"binectapi\"`, bei einem abgewiesenen Key mit `error=\"invalid_token\"`." }, "403": { "description": "Zugriff verweigert – falsche E-Mail-Adresse bzw. falsches Passwort, gesperrter Zugang oder keine Berechtigung für diese Ressource (Fehlercode `4403`). Mit Passwort außerdem: Die Passwort-Anmeldung ist für dieses Login abgeschaltet, es nimmt nur API-Keys an (`44034`). Mit API-Key außerdem: API-Keys sind für dieses Login nicht aktiviert (`44031`) oder vom Hauptkonto gesperrt (`44036`), der Key ist für diese IP-Adresse nicht freigegeben (`44032`) oder der Key darf nur lesen, die Anfrage schreibt aber (`44033`, `WWW-Authenticate` mit `error=\"insufficient_scope\"`)." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getInvoicePdf" } } }, "definitions": { "DocumentDeletionStatus": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer", "format": "int32", "description": "Die angefragte Dokument-ID." }, "deleted": { "type": "boolean", "description": "true, wenn diese Anfrage das Dokument gelöscht hat." }, "deletedChildren": { "type": "integer", "format": "int32", "description": "Anzahl der Einzelbriefe dieses Serienbriefs, die zusammen mit ihm gelöscht wurden. Nur bei Serienbriefen vorhanden, die auch **wirklich** gelöscht wurden – ein abgelehnter trägt kein `deletedChildren`; die IDs der Einzelbriefe werden nie aufgeführt. 0 bedeutet, dass der Serienbrief keine ungelöschten Einzelbriefe mehr hatte." }, "deletedAsChildOf": { "type": "integer", "format": "int32", "description": "Dieses Dokument ist ein Einzelbrief des Serienbriefs mit dieser ID, der in derselben Anfrage vorher gelöscht wurde; der Brief ist dabei mitgegangen. Steht anstelle eines Fehlers, weil das Dokument beim Eintreffen der Anfrage vorhanden war." }, "error": { "$ref": "#/definitions/Error" } }, "example": { "id": 4711, "deleted": true, "deletedChildren": 3 } }, "Document": { "type": "object", "example": { "id": 4711, "filename": "letter.pdf", "numberOfPages": 1, "documentType": "Letter", "status": { "code": 2, "text": "versandbereit" }, "letter": { "letterType": "LetterData", "letterData": { "recipientAddress": "\"Musterfirma GmbH\" \"Max Mustermann\" \"Musterstraße 1\" \"12345 Musterstadt\"", "international": false, "options": { "simplex": true, "color": false, "envelope": "DINLANG", "franking": "DV_FRANKING", "product": "NORMAL", "productionCountry": "DE" }, "price": { "priceBeforeTax": 89, "priceAfterTax": 106, "unit": "EUROCENT", "taxInPercent": 19 }, "attributes": [ { "key": "documentID", "value": "DOC-2024-0001" } ] } } }, "required": [ "id", "filename", "status", "documentType" ], "properties": { "id": { "type": "integer", "format": "int32" }, "filename": { "type": "string" }, "numberOfPages": { "description": "Seitenzahl des Briefs inklusive seiner Anhänge und der für den Druck eingefügten Leerseiten (Leerseite vor einem Anhang, der auf einem neuen Blatt beginnt; bei beidseitigem Druck die leere Rückseite eines Deckblatts). Das ist die Seitenzahl, die gedruckt und berechnet wird – vor wie nach dem Versand.", "type": "integer", "format": "int32" }, "status": { "$ref": "#/definitions/Status" }, "documentType": { "description": "Dokumenttyp.\n- `Letter` – Einzelbrief\n- `SerialLetter` – Serienbrief (in mehrere Briefe aufgeteilt)", "type": "string", "enum": [ "Letter", "SerialLetter" ] }, "letter": { "$ref": "#/definitions/Letter" }, "serialLetter": { "$ref": "#/definitions/SerialLetter" } } }, "Attachment": { "type": "object", "required": [ "id", "filename", "numberOfPages", "newSheet" ], "properties": { "id": { "type": "integer", "format": "int32" }, "filename": { "type": "string" }, "numberOfPages": { "type": "integer", "format": "int32" }, "newSheet": { "type": "boolean", "default": true }, "ntimesUsed": { "description": "Anzahl der Dokumente, an die dieser Anhang aktuell angehängt ist.", "type": "integer", "format": "int32" }, "remarks": { "type": "string" }, "validation": { "$ref": "#/definitions/ValidationResult" } } }, "ValidationResult": { "type": "object", "description": "Ergebnis der automatischen Dokumentprüfung: ob die Empfängeranschrift per Texterkennung (OCR) gelesen wurde und welche Korrekturen am Dokument vorgenommen wurden, damit es gedruckt und zugestellt werden kann. Ein fehlendes Feld heißt, dass für das Dokument keine Angabe vorliegt – etwa weil es geprüft wurde, bevor sie erfasst wurde. Es heißt nicht `false` bzw. „keine Korrektur“.", "example": { "ocrApplied": false, "corrections": [ "rotate" ], "validatedAt": "2026-10-21T09:14:03.120+02:00", "durationMs": 1834 }, "properties": { "ocrApplied": { "description": "`true`, wenn die Empfängeranschrift per Texterkennung (OCR) aus dem Dokument gelesen wurde. Solche Anschriften bitte besonders sorgfältig prüfen.", "type": "boolean" }, "corrections": { "description": "Automatisch vorgenommene Korrekturen; sie sind Teil der Prüfung und lassen sich nicht abwählen. Werte: `white` – Sperrbereich geweißt, `rotate` – Seite gedreht (ggf. skaliert), `shrink` – Anlage verkleinert, `pageformat` – Seitenformat korrigiert. Weitere Werte können hinzukommen; unbekannte Werte bitte als „sonstige Korrektur“ behandeln. Eine leere Liste heißt: geprüft, nichts musste korrigiert werden.", "type": "array", "items": { "type": "string" } }, "validatedAt": { "description": "Zeitpunkt der letzten Prüfung.", "type": "string", "format": "date-time" }, "durationMs": { "description": "Dauer der letzten Prüfung in Millisekunden, einschließlich Wartezeit.", "type": "integer", "format": "int32" } } }, "Letter": { "type": "object", "required": [ "letterType" ], "properties": { "letterType": { "description": "Art des Briefinhalts.\n- `LetterData` – gültige Briefdaten\n- `Error` – Fehler-Objekt (Validierung fehlgeschlagen)", "type": "string", "enum": [ "LetterData", "Error" ] }, "letterData": { "$ref": "#/definitions/LetterData" }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" } } } }, "LetterData": { "type": "object", "required": [ "recipientAddress", "price", "international", "options" ], "properties": { "recipientAddress": { "description": "Empfängeranschrift, wie sie im Anschriftenfeld des Briefs erkannt wurde. Format: jeder Teil in Anführungszeichen, durch Leerzeichen getrennt (Firma/Name, Name, Straße, PLZ + Ort).", "type": "string", "example": "\"Musterfirma\" \"Max Mustermann\" \"Musterstr. 20\" \"64342 Musterstadt\"" }, "price": { "$ref": "#/definitions/Price" }, "international": { "type": "boolean", "default": false, "example": false }, "options": { "$ref": "#/definitions/Options" }, "tracking": { "$ref": "#/definitions/Tracking" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } }, "attachments": { "description": "Die an dieses Dokument angehängten Anhänge. Nur Dokumente mit `documentType` `Letter` können Anhänge haben.", "type": "array", "items": { "$ref": "#/definitions/Attachment" } }, "validation": { "$ref": "#/definitions/ValidationResult" } } }, "SerialLetter": { "type": "object", "example": { "splitToken": "###NEXT###", "status": { "nrTotal": 50, "nrGenerated": 50, "nrSuccess": 49, "nrError": 1 } }, "properties": { "splitToken": { "type": "string", "description": "Text-Token, an dem der Serienbrief in einzelne Briefe aufgeteilt wird." }, "splitAfterNumberOfPages": { "type": "integer", "format": "int32", "description": "Der Serienbrief wird alle N Seiten aufgeteilt." }, "status": { "$ref": "#/definitions/SerialLetterStatus" }, "letters": { "type": "array", "items": { "$ref": "#/definitions/Document" } } } }, "SerialLetterStatus": { "type": "object", "required": [ "nrTotal", "nrGenerated", "nrSuccess", "nrError" ], "properties": { "nrTotal": { "type": "integer", "format": "int32" }, "nrGenerated": { "type": "integer", "format": "int32" }, "nrSuccess": { "type": "integer", "format": "int32" }, "nrError": { "type": "integer", "format": "int32" } } }, "Error": { "type": "object", "required": [ "code", "text", "blankText" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Binect-Fehlercode. Eine maschinenlesbare, zweisprachige Liste (Code → Bedeutung) ist unter /binectapi/error-codes.json veröffentlicht." }, "text": { "type": "string", "description": "Menschenlesbarer Fehlertext mit eingesetzten Platzhalterwerten." }, "blankText": { "type": "string", "description": "Fehlertext mit Platzhaltern für Parameter. Platzhalter sind von %-Zeichen umschlossen, z. B. `error on page number %pageNr% of your document`." }, "parameters": { "type": "array", "description": "Werte für die Platzhalter in `blankText`.", "items": { "$ref": "#/definitions/ErrorParam" } }, "errorOnPage": { "type": "integer", "format": "int32", "description": "Seite des Dokuments, auf der der Fehler aufgetreten ist." } } }, "Price": { "type": "object", "required": [ "priceBeforeTax", "priceAfterTax", "unit", "taxInPercent" ], "properties": { "priceBeforeTax": { "type": "integer", "format": "int32" }, "priceAfterTax": { "type": "integer", "format": "int32" }, "unit": { "$ref": "#/definitions/CurrencyEnum" }, "taxInPercent": { "type": "integer", "format": "int32", "description": "Mehrwertsteuersatz in Prozent, z. B. `19` für 19 % USt." }, "details": { "type": "array", "description": "Preisaufschlüsselung nach unterschiedlichen Steuersätzen (z. B. 19 % und 0 %).", "items": { "$ref": "#/definitions/Price" } } }, "example": { "priceBeforeTax": 78, "priceAfterTax": 93, "unit": "EUROCENT", "taxInPercent": 19 } }, "Options": { "type": "object", "properties": { "simplex": { "description": "Einseitiger Druck bei `true`; beidseitig (Duplex) bei `false`.", "type": "boolean" }, "color": { "description": "Farbdruck bei `true`; Schwarz-Weiß bei `false`.", "type": "boolean" }, "envelope": { "description": "Umschlagformat. Standard ist `DINLANG`.\n- `DINLANG` – DIN lang (gefalteter Brief)\n- `C4` – C4 (ungefaltet, A4)", "type": "string", "enum": [ "DINLANG", "C4" ], "example": "DINLANG" }, "dvFranking": { "description": "Bei `true` ist DV-Freimachung verpflichtend und die Validierung strenger. **Veraltet** – stattdessen `franking` (`DV_FRANKING`) verwenden.", "type": "boolean" }, "franking": { "$ref": "#/definitions/FrankingEnum" }, "productionCountry": { "$ref": "#/definitions/ProductionCountryEnum" }, "product": { "$ref": "#/definitions/ProductEnum" }, "shippingDate": { "description": "Optionaler Versandtermin: Der Brief wird jetzt freigegeben, aber erst ab diesem Tag produziert und versendet.\nAkzeptiert ENTWEDER ein festes Datum im Format `YYYY-MM-DD` oder `DD-MM-YYYY` ODER einen Wochentag: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`. Bei einem Wochentag wird der nächste zutreffende Werktag genommen (ist es der heutige Wochentag, der Tag der Folgewoche). Unterstützt sind nur Montag–Freitag (am Wochenende keine Produktion). Ein festes Datum muss zwischen morgen und 30 Tagen in der Zukunft liegen.\nBei `POST /documents` und `POST /sendings/document` wird ein Wochentag beim Upload zu einem festen Datum eingefroren. Bei `PUT /documents/{documentID}/options` ist eine Änderung nur möglich, solange das Dokument noch nicht zum Versand freigegeben wurde. Bei `GET/PUT /accounts/options` (Konto-Default) ist NUR ein Wochentag zulässig – ein festes Datum wird abgelehnt.\nFür ausdrücklich KEINEN Versandtermin einen leeren String (\"\") senden: beim Upload wird dann kein Versandtermin gesetzt und der Konto-Default IGNORIERT; bei `PUT /accounts/options` wird der konfigurierte Konto-Default ENTFERNT. Wird das Feld ganz WEGGELASSEN, wird beim Upload der Konto-Default übernommen (falls konfiguriert) und bei `/accounts/options` der bestehende Default unverändert behalten. In Antworten erscheint das Feld nur, wenn ein Versandtermin gesetzt ist – als festes Datum bei einem Dokument, als Wochentag beim Konto-Default.", "type": "string", "example": "2026-08-03" } }, "example": { "simplex": true, "color": false, "envelope": "DINLANG", "franking": "DV_FRANKING", "productionCountry": "DE", "shippingDate": "2026-08-03" } }, "FrankingEnum": { "description": "Freimachungsart.\n- `STANDARD_FRANKING` – Standard-Freimachung\n- `DV_FRANKING` – DV-Freimachung: moderne Methode für schnellen Versand mit maximalem Funktionsumfang (empfohlen)\n- `UNSPECIFIED` – nicht angegeben; es gilt die Account-Vorgabe", "type": "string", "enum": [ "UNSPECIFIED", "STANDARD_FRANKING", "DV_FRANKING" ] }, "ProductionCountryEnum": { "description": "Land, aus dem der Inlandsversand produziert wird. Internationaler Versand erfolgt immer aus Deutschland. Die Nutzung erfordert eine vorherige Freigabe durch Binect.\n- `DE` – Deutschland\n- `AT` – Österreich\n- `UNSPECIFIED` – nicht angegeben (Standard)", "type": "string", "enum": [ "UNSPECIFIED", "DE", "AT" ] }, "RegmailStatus": { "type": "object", "required": [ "id", "product", "status" ], "properties": { "id": { "type": "integer", "format": "int32" }, "product": { "$ref": "#/definitions/ProductEnum" }, "status": { "$ref": "#/definitions/Status" }, "tracking": { "$ref": "#/definitions/Tracking" } } }, "Tracking": { "type": "object", "properties": { "trackingId": { "type": "string" }, "trackingUrl": { "type": "string", "format": "uri" } } }, "ProductEnum": { "description": "Postprodukt. Standard ist `NORMAL` (Standardbrief).\n- `NORMAL` – Standardbrief\n- `PREMIUMADRESS_BASIS` / `PREMIUMADRESS_REPORT` – Deutsche Post PREMIUMADRESS (Empfänger-Adressaktualisierung); Nutzung bitte über kontakt@binect.de anfragen\n- `REGMAIL` – Einschreiben\n- `REGMAIL_DROP` – Einwurf-Einschreiben\n- `REGMAIL_INTERNATIONAL` – Einschreiben International", "type": "string", "enum": [ "NORMAL", "PREMIUMADRESS_BASIS", "PREMIUMADRESS_REPORT", "REGMAIL", "REGMAIL_DROP", "REGMAIL_INTERNATIONAL" ] }, "LetterAttribute": { "type": "object", "description": "Ein Custom-Attribut (Schlüssel/Wert) eines Dokuments. Steuerzeichen und unsichtbare Formatierungszeichen werden aus Schlüsseln und Werten entfernt; Tabulatoren, Zeilenumbrüche und Sonderleerzeichen werden zu einem Leerzeichen (am Anfang oder Ende: zu nichts). Solche Werte werden bereinigt angenommen, nicht abgewiesen - beim Lesen kommt der bereinigte Wert zurück.", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "example": { "key": "documentID", "value": "DOC-2024-0001" } }, "DocumentStatus": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "integer", "format": "int32" }, "status": { "$ref": "#/definitions/Status" } } }, "DocumentReferenceStatus": { "type": "object", "required": [ "id", "status", "externalReferenceId" ], "properties": { "id": { "type": "integer", "format": "int32", "description": "Die Auftrags-ID." }, "status": { "$ref": "#/definitions/Status" }, "externalReferenceId": { "type": "string", "description": "Die externe Referenz-ID, über die dieser Auftrag gefunden wurde." } }, "example": { "id": 4711, "status": { "code": 5, "text": "versendet" }, "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } }, "Status": { "type": "object", "required": [ "code", "text" ], "properties": { "code": { "description": "Folgende Statuscodes gibt es. Der `text` wird **in der Sprache des Accounts** geliefert (deutsch bzw. englisch):\n\n- **1** – `wird erstellt` (engl. `being created`)\n- **2** – `versandbereit` (engl. `ready to ship`)\n- **3** – `in Verarbeitung` (engl. `processing`)\n- **4** – `im Druck` (engl. `printing`)\n- **5** – `versendet` (engl. `sent`)\n- **6** – `storniert` (engl. `cancelled`)\n- **7** – `fehlerhaft` (engl. `faulty`)\n- **8** – `zugestellt` (engl. `delivered`) – nur Einschreiben, Endzustand\n- **9** – `zurückgelaufen` (engl. `returned to sender`) – nur Einschreiben, Endzustand", "type": "integer", "format": "int32" }, "text": { "description": "Status als Klartext, geliefert **in der Sprache des Accounts** (z. B. `versandbereit` / engl. `ready to ship`). Die feste Zuordnung siehe Feld `code`.", "type": "string" } }, "example": { "code": 2, "text": "versandbereit" } }, "ResponseFormatEnum": { "description": "Legt das Antwortformat fest. Standard ist `FULL` (die Antwort enthält das Validierungsergebnis).\n\n`SHORT` liefert die API-Antwort **sofort, ohne Validierungsergebnis**; die Validierung läuft danach. Den Ausgang anschließend über `GET /documents/status` bzw. `GET /documents/{documentID}/status` abfragen.\n\n**Unter hoher Last** werden `FULL`-Anfragen in eine Warteschlange gestellt statt abgewiesen: die Antwort kann dann mehrere Minuten dauern, ohne dass zwischendurch Daten fließen. Ein Client-Timeout von mindestens 15 Minuten ist deshalb ratsam. Bricht Ihr Client früher ab, wird das Dokument trotzdem verarbeitet – sichern Sie Wiederholungen mit einem `Idempotency-Key` (`POST /sendings`) oder mit `externalReferenceIdUnique` ab. Für große Mengen ist `SHORT` die bessere Wahl.", "type": "string", "enum": [ "FULL", "SHORT" ], "default": "FULL", "example": "FULL" }, "Account": { "description": "Account-Daten.", "type": "object", "required": [ "credit", "unit" ], "properties": { "credit": { "type": "integer", "format": "int32" }, "promotionCredit": { "type": "integer", "format": "int32" }, "creditLimit": { "type": "integer", "format": "int32" }, "unit": { "$ref": "#/definitions/CurrencyEnum" } } }, "Limits": { "description": "Wirksame Schranken dieser Umgebung. Eine fehlende Eigenschaft bedeutet: dafür ist keine Schranke konfiguriert.", "type": "object", "properties": { "maxRead": { "type": "integer", "format": "int32", "description": "Höchstes `limit` für `GET /documents`, `GET /sendings`, die Journale und `GET /invoices/{invoiceNumber}` (standardmäßig 500)." }, "maxReadStatus": { "type": "integer", "format": "int32", "description": "Höchstes `limit` für `GET /status`, `GET /documents/status`, `GET /sendings/status` und `GET /regmails/` (standardmäßig 5000)." }, "maxSendings": { "type": "integer", "format": "int32", "description": "Höchste Anzahl `documentIds` je `POST /sendings` und `PUT /sendings` (standardmäßig 500)." }, "maxDelete": { "type": "integer", "format": "int32", "description": "Höchste Anzahl `documentIds` je `DELETE /documents` und `DELETE /sendings` (standardmäßig 250)." }, "maxUploadSize": { "type": "integer", "format": "int64", "description": "Größte angenommene Datei je Upload, in Byte (in der Produktion 20 MB). Für Serienbriefe gilt eine eigene Grenze, siehe `maxSerialLetterUploadSize`." }, "maxSerialLetterUploadSize": { "type": "integer", "format": "int64", "description": "Größte angenommene Datei für einen Serienbrief (`POST /documents` mit `splitParams`), in Byte (standardmäßig 60 MB)." }, "maxApiKeys": { "type": "integer", "format": "int32", "description": "Höchste Anzahl API-Keys je Login; deaktivierte und abgelaufene Keys zählen mit (standardmäßig 10)." } } }, "ErrorParam": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "Content": { "description": "Der Dateiinhalt und der Dateiname. Der Inhalt muss Base64-kodiert sein.", "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string" }, "content": { "type": "string", "format": "byte" } }, "example": { "filename": "musterbrief.pdf", "content": "" } }, "User": { "description": "Die persönlichen Daten des Kunden.", "type": "object", "required": [ "email" ], "properties": { "debitornumber": { "type": "string" }, "email": { "type": "string", "format": "email" }, "forename": { "type": "string" }, "surname": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "plz": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "title": { "type": "string" }, "phone": { "type": "string" }, "partnerId": { "type": "string" } } }, "Coworker": { "description": "Daten eines Mitarbeiters (Unterbenutzer).", "type": "object", "required": [ "email" ], "properties": { "debitornumber": { "type": "string" }, "email": { "type": "string", "format": "email" }, "forename": { "type": "string" }, "surname": { "type": "string" }, "registrationDate": { "type": "string", "format": "date" }, "numberOfSendings": { "type": "integer", "format": "int32" }, "totalAmount": { "$ref": "#/definitions/Price" } } }, "CurrencyEnum": { "description": "Währungseinheit. `EUROCENT`: Beträge werden in Euro-Cent angegeben (z. B. `106` = 1,06 €).", "type": "string", "enum": [ "EUROCENT" ] }, "Address": { "description": "Eine Adresse.", "type": "object", "required": [ "name", "street", "zipCode", "city" ], "properties": { "name": { "type": "string" }, "nameExtend": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "zipCode": { "type": "string" }, "country": { "type": "string" } } }, "Invoice": { "description": "Eine Rechnung.", "type": "object", "required": [ "id", "filename" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "totalAmount": { "$ref": "#/definitions/Price" }, "date": { "type": "string", "format": "date" } } }, "Transaction": { "description": "Eine Transaktion – ein einzelner Buchungsposten (z. B. zu einer Rechnung).", "type": "object", "required": [ "id", "action", "date" ], "properties": { "id": { "type": "string" }, "action": { "$ref": "#/definitions/Action" }, "date": { "type": "string", "format": "date" }, "documentId": { "type": "string" }, "filename": { "type": "string" }, "amount": { "$ref": "#/definitions/Price" }, "numberOfPages": { "type": "integer", "format": "int32" }, "options": { "$ref": "#/definitions/Options" }, "status": { "$ref": "#/definitions/Status" }, "coworker": { "description": "Debitorennummer (`debitornumber`) des Mitarbeiters, zu dem die Transaktion gehört.", "type": "string" } } }, "Action": { "description": "Beschreibt eine Aktion einer Transaktion.", "type": "object", "required": [ "code", "text" ], "properties": { "code": { "description": "Folgende Aktionscodes sind definiert:\n- **1** – versendet\n- **2** – storniert\n- **3** – Zustellfehler", "type": "integer", "format": "int32" }, "text": { "type": "string" } }, "example": { "code": 1, "text": "is sent" } }, "ApiKey": { "description": "Ein API-Key eines Logins, ohne den Key selbst (maskiert).", "type": "object", "required": [ "keyId", "name", "maskedKey", "scope", "status", "createdAt", "createdVia", "usedLast24h", "lockedBySupport", "lockedByOwner", "expiryReminder" ], "properties": { "keyId": { "type": "string", "description": "Öffentlicher Teil des Keys (12 Zeichen); bezeichnet den Key in der URL." }, "name": { "type": "string", "maxLength": 64, "description": "Name des Keys, je Login eindeutig (ohne Unterscheidung von Groß- und Kleinschreibung)." }, "maskedKey": { "type": "string", "description": "Maskierter Key zum Wiedererkennen: `bnct__…`." }, "scope": { "$ref": "#/definitions/ApiKeyScopeEnum" }, "status": { "$ref": "#/definitions/ApiKeyStatusEnum" }, "allowedIps": { "type": "array", "items": { "type": "string" }, "description": "IP-Adressen oder CIDR-Bereiche, von denen aus der Key benutzt werden darf (normalisiert). Fehlt: jede Adresse." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Ablauf; fehlt: Der Key läuft nicht ab." }, "createdAt": { "type": "string", "format": "date-time", "description": "Zeitpunkt der Anlage." }, "createdVia": { "$ref": "#/definitions/ApiKeyChannelEnum" }, "statusChangedAt": { "type": "string", "format": "date-time", "description": "Letzte Deaktivierung bzw. Reaktivierung; fehlt: nie." }, "statusChangedVia": { "$ref": "#/definitions/ApiKeyChannelEnum" }, "lastUsedAt": { "type": "string", "format": "date-time", "description": "Letzte erfolgreiche Nutzung (aktualisiert etwa einmal pro Minute); fehlt: nie benutzt." }, "lastUsedIp": { "type": "string", "description": "Client-IP-Adresse der letzten erfolgreichen Nutzung." }, "usedLast24h": { "type": "boolean", "description": "Wurde der Key in den letzten 24 Stunden erfolgreich benutzt?" }, "lastRejectedAt": { "type": "string", "format": "date-time", "description": "Letzte Anfrage mit dem richtigen Key, die trotzdem abgewiesen wurde (z. B. IP-Adresse nicht freigegeben, Key deaktiviert oder abgelaufen); fehlt: keine." }, "lastRejectedIp": { "type": "string", "description": "Client-IP-Adresse dieser abgewiesenen Anfrage." }, "lastRejectedCode": { "type": "integer", "format": "int32", "description": "Fehlercode dieser abgewiesenen Anfrage (z. B. `44032`)." }, "lockedBySupport": { "type": "boolean", "description": "Vom Binect-Kundenservice deaktiviert: lässt sich nicht reaktivieren." }, "lockedByOwner": { "type": "boolean", "description": "Vom Hauptkonto dieses Logins gesperrt (nur bei Mitarbeiter-Logins): lässt sich hier nicht reaktivieren, nur das Hauptkonto gibt ihn frei." }, "expiryReminder": { "$ref": "#/definitions/ApiKeyExpiryReminder" } } }, "ApiKeyExpiryReminder": { "description": "Erinnerungen per E-Mail vor dem Ablauf eines API-Keys und eine E-Mail, wenn er abgelaufen ist; nur bei Keys mit Ablaufdatum. Die E-Mails gehen an die E-Mail-Adresse des Logins und enthalten weder den Key noch einen Link. Wird ein Key ohne `expiryReminder` angelegt, ist die Erinnerung mit `[30, 7, 1]` eingeschaltet.", "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "`false`: keine Erinnerung und keine E-Mail beim Ablauf." }, "daysBefore": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 365 }, "maxItems": 3, "description": "Bis zu 3 Zeitpunkte in Tagen vor dem Ablauf (1 bis 365, z. B. `[30, 7, 1]`; Doppelte zählen einmal); fehlt oder leer: nur die E-Mail beim Ablauf. Zeitpunkte, die beim Anlegen des Keys bzw. beim Ändern der Erinnerung schon erreicht sind, entfallen; werden mehrere zugleich fällig, geht eine E-Mail raus." } } }, "Authentication": { "description": "Wie eine Anfrage angemeldet wurde.", "type": "object", "required": [ "email", "authMode", "method", "transport" ], "properties": { "email": { "type": "string", "format": "email", "description": "E-Mail-Adresse des Logins." }, "authMode": { "$ref": "#/definitions/AuthModeEnum" }, "method": { "$ref": "#/definitions/AuthMethodEnum" }, "transport": { "$ref": "#/definitions/AuthTransportEnum" }, "clientIp": { "type": "string", "description": "Client-IP-Adresse, wie der Server sie sieht; eine IP-Freigabeliste wird gegen sie geprüft. Fehlt: nicht bekannt." }, "apiKey": { "$ref": "#/definitions/ApiKey" } } }, "ApiKeyScopeEnum": { "description": "Rechte eines API-Keys. `FULL`: alles, was das Login darf. `READ_ONLY`: nur lesende Anfragen (`GET`, `HEAD`, `OPTIONS`); alles andere wird mit `403` abgewiesen (Fehlercode `44033`).", "type": "string", "enum": [ "FULL", "READ_ONLY" ] }, "ApiKeyStatusEnum": { "description": "Status eines API-Keys. `ACTIVE`: nutzbar. `INACTIVE`: deaktiviert (von Ihnen oder vom Binect-Kundenservice). `EXPIRED`: abgelaufen.", "type": "string", "enum": [ "ACTIVE", "INACTIVE", "EXPIRED" ] }, "ApiKeyChannelEnum": { "description": "Woher eine Änderung an einem API-Key kam. `PORTAL`: Kundenportal. `REST`: REST-API, angemeldet mit Passwort. `KEY`: REST-API, angemeldet mit genau diesem Key (Selbstdeaktivierung). `OWNER`: Hauptkonto dieses Logins (bei Mitarbeiter-Logins). `ADMIN`: Binect-Kundenservice.", "type": "string", "enum": [ "PORTAL", "REST", "KEY", "OWNER", "ADMIN" ] }, "AuthModeEnum": { "description": "Was die REST-API für dieses Login annimmt. `PASSWORD`: nur E-Mail-Adresse und Passwort (Standard). `PASSWORD_AND_KEY`: Passwort und API-Keys. `KEY_ONLY`: nur API-Keys. Der Modus wird im Kundenportal unter **Mein Konto → API-Keys** gewählt; Kundenportal und SOAP-Schnittstelle nutzen immer das Passwort.", "type": "string", "enum": [ "PASSWORD", "PASSWORD_AND_KEY", "KEY_ONLY" ] }, "AuthMethodEnum": { "description": "Anmeldeverfahren einer Anfrage. `PASSWORD`: E-Mail-Adresse und Passwort. `API_KEY`: ein API-Key.", "type": "string", "enum": [ "PASSWORD", "API_KEY" ] }, "AuthTransportEnum": { "description": "Wie die Zugangsdaten übertragen wurden. `BASIC`: HTTP Basic mit E-Mail-Adresse und Passwort. `BEARER`: `Authorization: Bearer `. `X_API_KEY`: `X-API-Key: `. `BASIC_BRIDGE`: der API-Key in einer HTTP-Basic-Anmeldung. `RAW`: `Authorization: ` ohne Verfahren.", "type": "string", "enum": [ "BASIC", "BEARER", "X_API_KEY", "BASIC_BRIDGE", "RAW" ] } } }