{ "swagger": "2.0", "info": { "version": "1.1.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**.\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## 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`); fuer Produktion `https://app.binect.de/binectapi/v1`. Authentifizierung per **HTTP Basic** (E-Mail + Passwort) - die Logindaten unten 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:** HTTP Basic Auth mit **E-Mail + Passwort**; andere Verfahren sind derzeit nicht möglich.\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 (Benutzername und Passwort)." } }, "security": [ { "basicAuth": [] } ], "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." }, { "name": "invoices", "description": "Rechnungen und deren Transaktionen." } ], "externalDocs": { "description": "AI agents & integration overview (llms.txt)", "url": "/llms.txt" }, "paths": { "/documents": { "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**.\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 mit Ghostscript 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\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`." }, "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`." }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "413": { "description": "Anfrage zu groß – das Limit beträgt 20 MB." } }, "operationId": "uploadDocument" }, "get": { "tags": [ "documents" ], "description": "Liefert alle hochgeladenen, **versandfähigen** Dokumente.\n\nVersandfähige Dokumente haben `status.code` **2** – `versandbereit` (engl. `ready to ship`).\n\nOptional kann über `attributes` gefiltert werden: ein JSON-formatierter String – ein Array von `LetterAttribute`.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Liste aller versandfähigen Dokumente.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "413": { "description": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden." } }, "operationId": "listShippableDocuments" } }, "/documents/status": { "get": { "tags": [ "documents", "status" ], "description": "Liefert den Validierungsstatus hochgeladener Dokumente **vor der Versandübergabe** – z. B. um zu prüfen, ob ein Brief `versandbereit` (Code 2) oder `fehlerhaft` (Code 7) ist.\n\nBesonders nützlich nach einem Upload mit `responseFormat` = `SHORT`: Der Upload kehrt dann **sofort ohne Validierungsergebnis** zurück, die Validierung läuft anschließend. Über diesen Endpunkt lässt sich der Ausgang danach abfragen.\n\nOptional kann die Abfrage über `documentIds` auf bestimmte Dokumente eingegrenzt werden. Jeder Eintrag enthält die `documentID` und den `status` (`code` + `text`):\n- **1** – `wird erstellt` (engl. `being created`) – Validierung läuft noch\n- **2** – `versandbereit` (engl. `ready to ship`)\n- **7** – `fehlerhaft` (engl. `faulty`)", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } }, "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", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Liste der fehlerhaften Dokumente.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "413": { "description": "Zu viele Daten angefordert – bitte `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.", "parameters": [ { "name": "key", "in": "query", "required": true, "type": "array", "items": { "type": "string" }, "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "value", "in": "query", "required": true, "type": "array", "items": { "type": "string" }, "allowEmptyValue": false, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } }, "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, "allowEmptyValue": false }, { "name": "full", "in": "query", "required": false, "type": "boolean", "default": false, "allowEmptyValue": 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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } } } }, "/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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getDocument" }, "delete": { "tags": [ "documents" ], "description": "Löscht das referenzierte Dokument. Nur möglich, solange das Dokument noch nicht in den Versand gegeben wurde.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "deleteDocument" } }, "/documents/{documentID}/status": { "get": { "tags": [ "documents", "status" ], "description": "Liefert den Status des Dokuments (`code` + `text`; alle Codes siehe Modell `Status`).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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 bzw. aktualisiert den `value` des Attributs zum angegebenen `key`.", "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", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "400": { "description": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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": "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." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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.", "type": "boolean", "default": true }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." } }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich)." } }, "operationId": "removeDocumentAttachment" } }, "/sendings": { "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" } } } ], "responses": { "200": { "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." } }, "operationId": "releaseForDispatch" }, "get": { "tags": [ "sendings" ], "description": "Liefert alle Dokumente, die zum Versand freigegeben oder bereits zugestellt wurden.\n\nStatuscodes (`status.code` → `status.text`):\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\n**Zeitpunkt:** Nach der Versandfreigabe ist der Status erst **ab 05:00 Uhr des Folgetags** aussagekräftig – und nur, wenn die Sendung das **14:30-Versandfenster** erreicht hat, da der Status erst dann aktualisiert wird.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "413": { "description": "Zu viele Daten angefordert – bitte `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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." } }, "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 ein eindeutiges Custom-Attribute (z. B. `documentID`) mit und prüfen Sie vor einem erneuten Versuch über `GET /documents/findbyAttributes`.", "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`." }, "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`." }, "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" } } } ], "responses": { "200": { "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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ß – das Limit beträgt 20 MB." } }, "operationId": "uploadAndSendDocument" } }, "/sendings/status": { "get": { "tags": [ "sendings", "status" ], "description": "Liefert den Versandstatus von Dokumenten, die zum Versand freigegeben oder bereits zugestellt wurden. Optional über `documentIds` eingrenzbar.\n\nStatuscodes 3–7 (`status.code` → `status.text`; siehe Modell `Status`):\n- **3** `in Verarbeitung` (engl. `processing`), **4** `im Druck` (engl. `printing`), **5** `versendet` (engl. `sent`), **6** `storniert` (engl. `cancelled`), **7** `fehlerhaft` (engl. `faulty`).\n\n**Zeitpunkt:** erst **ab 05:00 Uhr des Folgetags** aussagekräftig – und nur, wenn die Sendung das **14:30-Versandfenster** erreicht hat.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } }, "operationId": "listSendingStatus" } }, "/sendings/{documentID}/status": { "get": { "tags": [ "sendings", "status" ], "description": "Liefert den Versandstatus eines einzelnen Dokuments, das zum Versand freigegeben oder bereits zugestellt wurde (Statuscodes 3–7; siehe Modell `Status`).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } ], "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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": "cancelDocumentDispatch" }, "delete": { "tags": [ "sendings" ], "description": "Löscht ein abgeschlossenes Dokument aus dem System – also ein storniertes oder ein zugestelltes und versendetes. Dient dem Entfernen erledigter Einträge.", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "deleteSending" } }, "/regmails/": { "get": { "tags": [ "regmails", "sendings", "status" ], "description": "Liefert Status- und Tracking-Informationen aller Einschreiben. Nur Einschreiben in Zustellung tragen Tracking-Informationen; diese lassen sich bis in den Briefkasten verfolgen.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/RegmailStatus" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "413": { "description": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden." } }, "operationId": "listRegisteredMail" } }, "/regmails/{documentID}": { "get": { "tags": [ "regmails", "sendings", "status" ], "description": "Liefert Status- und Tracking-Informationen eines einzelnen Einschreibens. Tracking-Informationen liegen nur bei Einschreiben in Zustellung vor und lassen sich bis in den Briefkasten verfolgen.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "$ref": "#/definitions/RegmailStatus" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Einschreiben (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getRegisteredMail" } }, "/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.", "type": "boolean", "default": true }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "413": { "description": "Anfrage zu groß – das Limit beträgt 20 MB." } }, "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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "404": { "description": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich)." } }, "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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } }, "operationId": "getAccount" } }, "/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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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)." }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." }, "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" } } }, "403": { "description": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource." } }, "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", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "404": { "description": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer." }, "413": { "description": "Zu viele Daten angefordert – bitte `limit` 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", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "413": { "description": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden." } }, "operationId": "getAccountJournal" } }, "/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" } } } }, "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", "allowEmptyValue": false, "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32", "allowEmptyValue": false } ], "responses": { "200": { "description": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "413": { "description": "Zu viele Daten angefordert – bitte `limit` 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" } }, "404": { "description": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich)." } }, "operationId": "getInvoicePdf" } } }, "definitions": { "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": { "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" } } }, "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" } } } }, "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", "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`)", "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.", "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" } } }, "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" } } } }