{
  "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<details>\n<summary>Beispielcode anzeigen</summary>\n<p><strong>Bash (curl)</strong></p>\n<pre class=\"binect-code\"><code># 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 @- &lt;&lt;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</code></pre>\n<p><strong>Python (requests)</strong></p>\n<pre class=\"binect-code\"><code>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())</code></pre>\n<p><strong>JavaScript (Node 18+, fetch)</strong></p>\n<pre class=\"binect-code\"><code>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());</code></pre>\n<p><strong>PHP (curl)</strong></p>\n<pre class=\"binect-code\"><code>&lt;?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\"    =&gt; [\"filename\" =&gt; \"brief.pdf\", \"content\" =&gt; $content],\n  \"options\"    =&gt; [\"simplex\" =&gt; true, \"color\" =&gt; false, \"envelope\" =&gt; \"DINLANG\",\n                   \"franking\" =&gt; \"DV_FRANKING\", \"product\" =&gt; \"NORMAL\"],\n  \"tenantId\" =&gt; \"kostenstelle-4711\",\n  \"externalReferenceId\" =&gt; \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n]);\n$ch = curl_init(\"$baseUrl/sendings/document\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST           =&gt; true,\n  CURLOPT_RETURNTRANSFER =&gt; true,\n  CURLOPT_USERPWD        =&gt; \"$email:$password\",\n  CURLOPT_HTTPHEADER     =&gt; [\"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS     =&gt; $payload,\n]);\n$resp = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE) . \"\\n\" . $resp . \"\\n\";</code></pre>\n</details>\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)",
    "x-i18n": {
      "de": "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<details>\n<summary>Beispielcode anzeigen</summary>\n<p><strong>Bash (curl)</strong></p>\n<pre class=\"binect-code\"><code># 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 @- &lt;&lt;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</code></pre>\n<p><strong>Python (requests)</strong></p>\n<pre class=\"binect-code\"><code>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())</code></pre>\n<p><strong>JavaScript (Node 18+, fetch)</strong></p>\n<pre class=\"binect-code\"><code>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());</code></pre>\n<p><strong>PHP (curl)</strong></p>\n<pre class=\"binect-code\"><code>&lt;?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\"    =&gt; [\"filename\" =&gt; \"brief.pdf\", \"content\" =&gt; $content],\n  \"options\"    =&gt; [\"simplex\" =&gt; true, \"color\" =&gt; false, \"envelope\" =&gt; \"DINLANG\",\n                   \"franking\" =&gt; \"DV_FRANKING\", \"product\" =&gt; \"NORMAL\"],\n  \"tenantId\" =&gt; \"kostenstelle-4711\",\n  \"externalReferenceId\" =&gt; \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n]);\n$ch = curl_init(\"$baseUrl/sendings/document\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST           =&gt; true,\n  CURLOPT_RETURNTRANSFER =&gt; true,\n  CURLOPT_USERPWD        =&gt; \"$email:$password\",\n  CURLOPT_HTTPHEADER     =&gt; [\"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS     =&gt; $payload,\n]);\n$resp = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE) . \"\\n\" . $resp . \"\\n\";</code></pre>\n</details>\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)",
      "en": "Welcome to the **Binect REST API** – the interface for sending documents as **physical mail** through mail service providers in Germany – **not exclusively via Deutsche Post**. Your documents are printed, enveloped, franked and delivered by our production partners.\n\n## Environments\n\n| Environment | URL | Purpose |\n| --- | --- | --- |\n| **Production** | https://app.binect.de | Real, chargeable dispatch |\n| **Test** | https://test-app.binect.de | Free of charge – **simulates** dispatch |\n\n- The two environments have **separate user management** – you need a **dedicated account** in each. Create accounts via the login page – [Production](https://app.binect.de/index.jsp?id=login) · [Test](https://test-app.binect.de/index.jsp?id=login).\n- The test environment may run a **more recent version** than production; **handling and response behaviour** are intentionally identical, however.\n\n## Sending in two steps\n\n1. **[`POST /documents`](#op:documents:uploadDocument:post:/documents)** – upload a document and have it validated.\n2. **[`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)** – hand an uploaded, valid document over for dispatch.\n\n## … or in a single step\n\n- **[`POST /sendings/document`](#op:sendings:uploadAndSendDocument:post:/sendings/document)** – shortcut: upload and, on successful validation, dispatch **directly**.\n\n**Editing & lifecycle:** While a document has not yet been released for dispatch, it can be modified via `/documents` (options, transformation, cover page, attachments) or deleted. Once successfully released for dispatch, `/sendings` is responsible.\n\n## Supported postal products\n\n- **Registered mail / Einschreiben** (Deutsche Post): Standard, Einwurf (drop-in), International – trackable all the way to the mailbox\n- **PremiumAdress** (Deutsche Post): Report, Basic *(paid activation required)*\n- **Franked** dispatch\n- **DV-prepaid** dispatch (DV-Freimachung – fast, maximum feature set)\n\n## Document requirements\n\n- Documents are transmitted as **PDF in Base64** format.\n- **PDF** and **PostScript (PS)** are allowed – **PDF preferred**. Maximum file size: **20 MB**.\n- Recommended print specs: **PDF/A-2b**, **embedded fonts**, **CMYK** colour space.\n- Sample letters: [DOCX template](/downloadFile?fileId=4) · [ODT template](/downloadFile?fileId=3) – please transmit as PDF (Base64).\n- Layout templates for address and exclusion zones: [download template](/downloadFile?fileId=24).\n- A document may contain at most **192 sheets** (192 pages simplex, 384 pages duplex).\n- **Production in Austria:** on request, customers from Austria can have documents produced in Austria together with Binect GmbH (`productionCountry: AT`).\n- **Addressing:** place the recipient address in the **address field** (visible in the window for window envelopes); keep the **exclusion zones** (franking, processing codes) clear. For exact positions see the [layout template](/downloadFile?fileId=24) and the FAQ [„Welche Datei- und Formatanforderungen gelten für meinen Brief?“](/index.jsp?id=faq#faq_5). If no valid address is detected in the correct area, it can be corrected via a transformation or a cover page.\n\n## Addressing & exclusion zones\n\nAll measurements are taken from the **top-left corner** of the page. The recipient and sender address must be positioned so that they are fully visible in the **window of a DIN-lang envelope**; the exclusion zones must be kept clear.\n\n| Area | Width | Height | From left | From top |\n| --- | --- | --- | --- | --- |\n| Recipient address field | 85 mm | 21 mm | 20 mm | 69 mm |\n| Sender address field | 85 mm | 5.5 mm | 20 mm | 45 mm |\n| DV exclusion zone | 85 mm | 17.5 mm | 20 mm | 51 mm |\n\n**DV validation:** Since **2022-09-27**, DV validation is the platform's new standard. The existing address and exclusion zones remain valid; for DV compatibility, **additionally** keep the DV exclusion zone listed above clear – it must contain **no content (text or images/graphics)**, because the **DV franking** is printed into it. [Download the layout template](/downloadFile?fileId=24).\n\n## Processing & deadlines\n\n- Hand-over to production by default at **14:30**; **cancellations** are possible until shortly before.\n- **Status queries** are only meaningful from **05:00 on the following day** – and only if the sending made the **14:30 dispatch window**, because the dispatch status is updated only then.\n- **Maintenance window:** every **Tuesday, 21:00–23:00**.\n\n## Custom attributes\n\n- Pass your **internal reference id** in the **`externalReferenceId`** field (ideally a UUID) – this makes the document findable later via **`GET /documents/findByExternalReferenceId`**.\n- **Cost-center billing?** Possible with individual invoicing via the **`tenantId`** field.\n\n## Validation & correction\n\n- Documents that **fail validation** can often be salvaged – e.g. via the **transformations** endpoint (move & scale) or the **cover-page** function – turning them into a dispatchable document.\n\n## Error handling on upload (HTTP 500)\n\n- On a **`500`** during upload, **always assume the document may nonetheless have arrived**.\n- **Recommendation:** send a unique **`externalReferenceId`** on upload and, on error, query it via **`GET /documents/findByExternalReferenceId`**:\n  - **match** → the document arrived (do not re-upload).\n  - **no match** → the document did **not** reach the service → re-upload.\n\n## Example code: `POST /sendings/document` (upload + send in one step)\n\nThe default URL is the **Test environment** (`https://test-app.binect.de/binectapi/v1`); for Production use `https://app.binect.de/binectapi/v1`. Authentication via **HTTP Basic** (email + password) - the credentials below are **placeholders**.\n\n<details>\n<summary>Show example code</summary>\n<p><strong>Bash (curl)</strong></p>\n<pre class=\"binect-code\"><code># 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 @- &lt;&lt;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</code></pre>\n<p><strong>Python (requests)</strong></p>\n<pre class=\"binect-code\"><code>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())</code></pre>\n<p><strong>JavaScript (Node 18+, fetch)</strong></p>\n<pre class=\"binect-code\"><code>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());</code></pre>\n<p><strong>PHP (curl)</strong></p>\n<pre class=\"binect-code\"><code>&lt;?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\"    =&gt; [\"filename\" =&gt; \"brief.pdf\", \"content\" =&gt; $content],\n  \"options\"    =&gt; [\"simplex\" =&gt; true, \"color\" =&gt; false, \"envelope\" =&gt; \"DINLANG\",\n                   \"franking\" =&gt; \"DV_FRANKING\", \"product\" =&gt; \"NORMAL\"],\n  \"tenantId\" =&gt; \"kostenstelle-4711\",\n  \"externalReferenceId\" =&gt; \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n]);\n$ch = curl_init(\"$baseUrl/sendings/document\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST           =&gt; true,\n  CURLOPT_RETURNTRANSFER =&gt; true,\n  CURLOPT_USERPWD        =&gt; \"$email:$password\",\n  CURLOPT_HTTPHEADER     =&gt; [\"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS     =&gt; $payload,\n]);\n$resp = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE) . \"\\n\" . $resp . \"\\n\";</code></pre>\n</details>\n\n## Authentication, billing & notes\n\n- **Authentication:** HTTP Basic Auth with **e-mail + password**; no other methods are currently available.\n- **Payment:** the default is **prepaid** (PayPal, credit card, Sofortüberweisung). On request, an account can be enabled for **invoicing (on account)**. Cost-center billing via the `tenantId` field (see above).\n- **Sales partners:** partner options can be discussed with sales ([info@binect.de](mailto:info@binect.de)).\n- **Notifications:** you must **poll actively** for new letter states (status endpoints). There is currently **no webhook interface**, though one may be added in the future.\n\n## Support & contact\n\n- **Technical questions / issues:** [kontakt@binect.de](mailto:kontakt@binect.de)\n- **Integration support / quote:** Binect Sales – [info@binect.de](mailto:info@binect.de)"
    },
    "title": "Binect REST API",
    "termsOfService": "/downloadFile?fileId=2",
    "contact": {
      "name": "kontakt@binect.de"
    }
  },
  "basePath": "/binectapi/v1",
  "schemes": [
    "https"
  ],
  "securityDefinitions": {
    "basicAuth": {
      "type": "basic",
      "description": "HTTP Basic authentication (username and password).",
        "x-i18n": {
          "de": "HTTP-Basic-Authentifizierung (Benutzername und Passwort).",
          "en": "HTTP Basic authentication (username and password)."
        }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "documents",
      "description": "Upload, validate, edit and query documents (before dispatch release).",
      "x-i18n": { "de": "Dokumente hochladen, validieren, bearbeiten und abfragen (vor der Versandfreigabe).", "en": "Upload, validate, edit and query documents (before dispatch release)." }
    },
    {
      "name": "status",
      "description": "Status queries for documents and sendings.",
      "x-i18n": { "de": "Status-Abfragen für Dokumente und Sendungen.", "en": "Status queries for documents and sendings." }
    },
    {
      "name": "corrections",
      "description": "Corrections to documents: transformations and cover page.",
      "x-i18n": { "de": "Korrekturen an Dokumenten: Transformationen und Deckblatt.", "en": "Corrections to documents: transformations and cover page." }
    },
    {
      "name": "attachments",
      "description": "Manage attachments (the attachment pool and per-document attachments).",
      "x-i18n": { "de": "Anhänge verwalten (Anhang-Pool und Dokument-Anhänge).", "en": "Manage attachments (the attachment pool and per-document attachments)." }
    },
    {
      "name": "sendings",
      "description": "Dispatch release, cancellation and dispatch status.",
      "x-i18n": { "de": "Versandfreigabe, Stornierung und Versandstatus.", "en": "Dispatch release, cancellation and dispatch status." }
    },
    {
      "name": "regmails",
      "description": "Registered mail: status and tracking.",
      "x-i18n": { "de": "Einschreiben: Status und Tracking.", "en": "Registered mail: status and tracking." }
    },
    {
      "name": "accounts",
      "description": "Account: balance, personal data, default shipping options, coworkers, journal.",
      "x-i18n": { "de": "Konto: Guthaben, persönliche Daten, Standard-Versandoptionen, Mitarbeiter, Journal.", "en": "Account: balance, personal data, default shipping options, coworkers, journal." }
    },
    {
      "name": "invoices",
      "description": "Invoices and their transactions.",
      "x-i18n": { "de": "Rechnungen und deren Transaktionen.", "en": "Invoices and their transactions." }
    }
  ],
  "externalDocs": {
    "description": "AI agents & integration overview (llms.txt)",
    "url": "/llms.txt"
  },
  "paths": {
    "/documents": {
      "post": {
        "tags": [
          "documents"
        ],
        "description": "Uploads a new document. The document is a **single letter** or a **serial letter** and contains a valid address in the address field while respecting the exclusion zones.\n\n**File formats:** **PDF** and **PostScript (PS)** are allowed – **PDF is preferred**. PDFs should conform to **PDF/A-2b** (embedded fonts, CMYK colour space). Maximum file size: **20 MB**.\n\n**Transfer:** The content is passed **Base64-encoded** in the `content` field.\n\n**Validation:** The document is validated. If validation fails, an optional correction (transformation, cover page) is offered where possible. The response contains a valid document or an `error` object.\n\n**Note:** The document is normalized with Ghostscript; we recommend a visual check via `GET /documents/{documentID}/pdf`.\n\n**Tip:** For fast dispatch with the maximum feature set, use **DV-Freimachung** (the modern franking method).\n\n**Status after upload** (`status.code` → `status.text`):\n- **2** – `ready to ship` (de `versandbereit`)\n- **7** – `faulty` (de `fehlerhaft`)\n\n**Reliability:** On HTTP `500` the upload may still have succeeded. Send an `externalReferenceId` and, in that case, verify via `GET /documents/findByExternalReferenceId` before re-uploading (a match means it arrived).",
        "x-i18n": {
          "de": "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).",
          "en": "Uploads a new document. The document is a **single letter** or a **serial letter** and contains a valid address in the address field while respecting the exclusion zones.\n\n**File formats:** **PDF** and **PostScript (PS)** are allowed – **PDF is preferred**. PDFs should conform to **PDF/A-2b** (embedded fonts, CMYK colour space). Maximum file size: **20 MB**.\n\n**Transfer:** The content is passed **Base64-encoded** in the `content` field.\n\n**Validation:** The document is validated. If validation fails, an optional correction (transformation, cover page) is offered where possible. The response contains a valid document or an `error` object.\n\n**Note:** The document is normalized with Ghostscript; we recommend a visual check via `GET /documents/{documentID}/pdf`.\n\n**Tip:** For fast dispatch with the maximum feature set, use **DV-Freimachung** (the modern franking method).\n\n**Status after upload** (`status.code` → `status.text`):\n- **2** – `ready to ship` (de `versandbereit`)\n- **7** – `faulty` (de `fehlerhaft`)\n\n**Reliability:** On HTTP `500` the upload may still have succeeded. Send an `externalReferenceId` and, in that case, verify via `GET /documents/findByExternalReferenceId` before re-uploading (a match means it arrived)."
        },
        "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": "Your internal customer/tenant number for this order (max. 32 characters). It is stored on the order and forwarded to production. Replaces the former `tenant` custom attribute.",
                  "x-i18n": {
                    "de": "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`.",
                    "en": "Your internal customer/tenant number for this order (max. 32 characters). It is stored on the order and forwarded to production. Replaces the former `tenant` custom attribute."
                  }
                },
                "externalReferenceId": {
                  "type": "string",
                  "maxLength": 64,
                  "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
                  "description": "Your internal reference id for this order (max. 64 characters); a **UUID** is the ideal format. Searchable via `GET /documents/findByExternalReferenceId`. Replaces the former `documentID` custom attribute.",
                  "x-i18n": {
                    "de": "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`.",
                    "en": "Your internal reference id for this order (max. 64 characters); a **UUID** is the ideal format. Searchable via `GET /documents/findByExternalReferenceId`. Replaces the former `documentID` custom attribute."
                  }
                },
                "externalReferenceIdUnique": {
                  "type": "boolean",
                  "default": false,
                  "description": "Opt-in duplicate protection. If `true`, the upload is rejected when another of your orders already carries this `externalReferenceId` (guards against accidental double submissions).",
                  "x-i18n": {
                    "de": "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).",
                    "en": "Opt-in duplicate protection. If `true`, the upload is rejected when another of your orders already carries this `externalReferenceId` (guards against accidental double submissions)."
                  }
                },
                "splitParams": {
                  "description": "For a serial letter, defines how it is split into individual letters. Use either `splitToken` or `splitAfterNumberOfPages`, not both.",
                  "x-i18n": {
                    "de": "Legt bei einem Serienbrief fest, wie er in einzelne Briefe aufgeteilt wird. Es darf entweder `splitToken` oder `splitAfterNumberOfPages` verwendet werden, nicht beides.",
                    "en": "For a serial letter, defines how it is split into individual letters. Use either `splitToken` or `splitAfterNumberOfPages`, not both."
                  },
                  "type": "object",
                  "properties": {
                    "splitToken": {
                      "type": "string",
                      "description": "Text token at which the serial letter is split into individual letters.",
                      "x-i18n": {
                        "de": "Text-Token, an dem der Serienbrief in einzelne Briefe aufgeteilt wird.",
                        "en": "Text token at which the serial letter is split into individual letters."
                      }
                    },
                    "splitAfterNumberOfPages": {
                      "type": "integer",
                      "format": "int32",
                      "description": "The serial letter is split every N pages.",
                      "x-i18n": {
                        "de": "Der Serienbrief wird alle N Seiten aufgeteilt.",
                        "en": "The serial letter is split every N pages."
                      }
                    }
                  },
                  "example": {
                    "splitToken": "Sehr geehrte"
                  }
                },
                "responseFormat": {
                  "$ref": "#/definitions/ResponseFormatEnum"
                }
              },
              "example": {
                "content": {
                  "filename": "musterbrief.pdf",
                  "content": "<Base64-encoded PDF>"
                },
                "tenantId": "kostenstelle-4711",
                "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document created – may be erroneous (check `status`; on code 7 see `error`).",
            "x-i18n": {
              "de": "Dokument angelegt – kann fehlerhaft sein (prüfen Sie `status`; bei Code 7 siehe `error`).",
              "en": "Document created – may be erroneous (check `status`; on code 7 see `error`)."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "413": {
            "description": "Request Entity Too Large – the limit is 20 MB.",
            "x-i18n": {
              "de": "Anfrage zu groß – das Limit beträgt 20 MB.",
              "en": "Request Entity Too Large – the limit is 20 MB."
            }
          }
        }
      },
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns all uploaded, **shippable** documents.\n\nShippable documents have `status.code` **2** – `ready to ship` (de `versandbereit`).\n\nOptionally, an `attributes` filter can be supplied: a JSON-formatted string – an array of `LetterAttribute`.",
        "x-i18n": {
          "de": "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`.",
          "en": "Returns all uploaded, **shippable** documents.\n\nShippable documents have `status.code` **2** – `ready to ship` (de `versandbereit`).\n\nOptionally, an `attributes` filter can be supplied: a JSON-formatted string – an array of `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": "A list of all shippable documents.",
            "x-i18n": {
              "de": "Liste aller versandfähigen Dokumente.",
              "en": "A list of all shippable documents."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Document"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      }
    },
    "/documents/status": {
      "get": {
        "tags": [
          "documents",
          "status"
        ],
        "description": "Returns the validation status of uploaded documents **before dispatch hand-over** – e.g. to check whether a letter is `ready to ship` (code 2) or `faulty` (code 7).\n\nEspecially useful after an upload with `responseFormat` = `SHORT`: in that case the upload returns **immediately, without the validation result**, and validation runs afterwards. Use this endpoint to retrieve the outcome later.\n\nThe query can optionally be narrowed to specific documents via `documentIds`. Each entry contains the `documentID` and the `status` (`code` + `text`):\n- **1** – `being created` (de `wird erstellt`) – validation still running\n- **2** – `ready to ship` (de `versandbereit`)\n- **7** – `faulty` (de `fehlerhaft`)",
        "x-i18n": {
          "de": "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`)",
          "en": "Returns the validation status of uploaded documents **before dispatch hand-over** – e.g. to check whether a letter is `ready to ship` (code 2) or `faulty` (code 7).\n\nEspecially useful after an upload with `responseFormat` = `SHORT`: in that case the upload returns **immediately, without the validation result**, and validation runs afterwards. Use this endpoint to retrieve the outcome later.\n\nThe query can optionally be narrowed to specific documents via `documentIds`. Each entry contains the `documentID` and the `status` (`code` + `text`):\n- **1** – `being created` (de `wird erstellt`) – validation still running\n- **2** – `ready to ship` (de `versandbereit`)\n- **7** – `faulty` (de `fehlerhaft`)"
        },
        "parameters": [
          {
            "name": "documentIds",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32"
            },
            "collectionFormat": "multi",
            "allowEmptyValue": false
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/DocumentStatus"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/documents/errors": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns all uploaded, **erroneous** documents.\n\nErroneous documents have `status.code` **7** – `faulty` (de `fehlerhaft`). Check the error message(s) in the `error` field and the preview via `GET /documents/{documentID}/pdf` or `/png`.",
        "x-i18n": {
          "de": "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`.",
          "en": "Returns all uploaded, **erroneous** documents.\n\nErroneous documents have `status.code` **7** – `faulty` (de `fehlerhaft`). Check the error message(s) in the `error` field and the preview via `GET /documents/{documentID}/pdf` or `/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": "A list of erroneous documents.",
            "x-i18n": {
              "de": "Liste der fehlerhaften Dokumente.",
              "en": "A list of erroneous documents."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Document"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      }
    },
    "/documents/findbyAttributes": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns all uploaded documents that are tagged with the given attributes.\n\nAt least one `key`/`value` pair is required. `key` and `value` are matched **by position** (`key[0]` pairs with `value[0]`, etc.); both arrays must therefore contain the **same number** of entries.",
        "x-i18n": {
          "de": "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.",
          "en": "Returns all uploaded documents that are tagged with the given attributes.\n\nAt least one `key`/`value` pair is required. `key` and `value` are matched **by position** (`key[0]` pairs with `value[0]`, etc.); both arrays must therefore contain the **same number** of entries."
        },
        "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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Document"
              }
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/documents/findByExternalReferenceId": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Looks up your orders by their `externalReferenceId` and returns their status. Set `full=true` for the full document objects, or `full=false` (default) for a minimal status (order id, status, externalReferenceId). Scoped to your own orders only – a foreign or unknown reference yields an empty result.",
        "x-i18n": {
          "de": "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.",
          "en": "Looks up your orders by their `externalReferenceId` and returns their status. Set `full=true` for the full document objects, or `full=false` (default) for a minimal status (order id, status, externalReferenceId). Scoped to your own orders only – a foreign or unknown reference yields an empty result."
        },
        "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": "Matching orders. With `full=false` a list of minimal statuses; with `full=true` a list of full `Document` objects.",
            "x-i18n": {
              "de": "Passende Aufträge. Bei `full=false` eine Liste minimaler Status; bei `full=true` eine Liste vollständiger `Document`-Objekte.",
              "en": "Matching orders. With `full=false` a list of minimal statuses; with `full=true` a list of full `Document` objects."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/DocumentReferenceStatus"
              }
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/documents/{documentID}": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns the referenced document. The document is a single letter, a serial letter or an `error` object.",
        "x-i18n": {
          "de": "Liefert das referenzierte Dokument. Das Dokument ist ein Einzelbrief, ein Serienbrief oder ein `error`-Objekt.",
          "en": "Returns the referenced document. The document is a single letter, a serial letter or an `error` object."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "documents"
        ],
        "description": "Deletes the referenced document. Only possible as long as the document has not yet been handed over for dispatch.",
        "x-i18n": {
          "de": "Löscht das referenzierte Dokument. Nur möglich, solange das Dokument noch nicht in den Versand gegeben wurde.",
          "en": "Deletes the referenced document. Only possible as long as the document has not yet been handed over for dispatch."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/status": {
      "get": {
        "tags": [
          "documents",
          "status"
        ],
        "description": "Returns the document's status (`code` + `text`; see the `Status` model for all codes).",
        "x-i18n": {
          "de": "Liefert den Status des Dokuments (`code` + `text`; alle Codes siehe Modell `Status`).",
          "en": "Returns the document's status (`code` + `text`; see the `Status` model for all codes)."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/DocumentStatus"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/options": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns the document's dispatch options (e.g. simplex/duplex, colour, franking, product, production country).",
        "x-i18n": {
          "de": "Liefert die Versandoptionen des Dokuments (z. B. Simplex/Duplex, Farbe, Freimachung, Produkt, Produktionsland).",
          "en": "Returns the document's dispatch options (e.g. simplex/duplex, colour, franking, product, production country)."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Options"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "put": {
        "tags": [
          "documents"
        ],
        "description": "Updates the document's dispatch options. Only possible while the document has not yet been handed over for dispatch.",
        "x-i18n": {
          "de": "Aktualisiert die Versandoptionen des Dokuments. Nur möglich, solange das Dokument noch nicht in den Versand gegeben wurde.",
          "en": "Updates the document's dispatch options. Only possible while the document has not yet been handed over for dispatch."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "options",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/Options"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Options"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/attributes": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns the document's attributes (custom `key`/`value` pairs).",
        "x-i18n": {
          "de": "Liefert die Attribute des Dokuments (benutzerdefinierte `key`/`value`-Paare).",
          "en": "Returns the document's attributes (custom `key`/`value` pairs)."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/LetterAttribute"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "post": {
        "tags": [
          "documents"
        ],
        "description": "Tags the document with attributes (custom `key`/`value` pairs). They can be used later to locate the document via `GET /documents/findbyAttributes`.\n\nAttributes can generally be set or changed at any time. For tenant/reference data please use the dedicated fields `tenantId` and `externalReferenceId` instead of custom attributes.",
        "x-i18n": {
          "de": "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.",
          "en": "Tags the document with attributes (custom `key`/`value` pairs). They can be used later to locate the document via `GET /documents/findbyAttributes`.\n\nAttributes can generally be set or changed at any time. For tenant/reference data please use the dedicated fields `tenantId` and `externalReferenceId` instead of 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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/LetterAttribute"
              }
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/attributes/{key}": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns the document's attribute for the specified `key`.",
        "x-i18n": {
          "de": "Liefert das Attribut des Dokuments zum angegebenen `key`.",
          "en": "Returns the document's attribute for the specified `key`."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/LetterAttribute"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "put": {
        "tags": [
          "documents"
        ],
        "description": "Sets or updates the `value` of the attribute for the specified `key`.",
        "x-i18n": {
          "de": "Setzt bzw. aktualisiert den `value` des Attributs zum angegebenen `key`.",
          "en": "Sets or updates the `value` of the attribute for the specified `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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/LetterAttribute"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "documents"
        ],
        "description": "Removes the attribute with the specified `key` from the document.",
        "x-i18n": {
          "de": "Entfernt das Attribut mit dem angegebenen `key` vom Dokument.",
          "en": "Removes the attribute with the specified `key` from the document."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/pdf": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns a PDF preview of the referenced document. Recommended for a visual check after upload or transformation.",
        "x-i18n": {
          "de": "Liefert eine PDF-Vorschau des referenzierten Dokuments. Empfohlen zur Sichtprüfung nach Upload oder Transformation.",
          "en": "Returns a PDF preview of the referenced document. Recommended for a visual check after upload or transformation."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "file"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/png": {
      "get": {
        "tags": [
          "documents"
        ],
        "description": "Returns a PNG preview of the referenced document.",
        "x-i18n": {
          "de": "Liefert eine PNG-Vorschau des referenzierten Dokuments.",
          "en": "Returns a PNG preview of the referenced document."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "file"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/transformations": {
      "put": {
        "tags": [
          "documents",
          "corrections"
        ],
        "description": "Applies a transformation to the document.\n\n- Without a `pages` list, only the **first page** is transformed. To transform **all** pages, pass `[-1]` as `pages`.\n- Each transformation is always applied to the **original** version of the document.\n- After a transformation the document is **validated again** – check `status` afterwards.\n\n**Geometry:**\n- `offsetX` / `offsetY` move the document horizontally / vertically in **mm**; the origin is the upper-left corner of the page.\n- `scaleX` / `scaleY` scale independently; factor `1` = 100 %, values `< 1` shrink. Scaling refers to the **centre** of the page.",
        "x-i18n": {
          "de": "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**.",
          "en": "Applies a transformation to the document.\n\n- Without a `pages` list, only the **first page** is transformed. To transform **all** pages, pass `[-1]` as `pages`.\n- Each transformation is always applied to the **original** version of the document.\n- After a transformation the document is **validated again** – check `status` afterwards.\n\n**Geometry:**\n- `offsetX` / `offsetY` move the document horizontally / vertically in **mm**; the origin is the upper-left corner of the page.\n- `scaleX` / `scaleY` scale independently; factor `1` = 100 %, values `< 1` shrink. Scaling refers to the **centre** of the page."
        },
        "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": "Document updated.",
            "x-i18n": {
              "de": "Dokument aktualisiert.",
              "en": "Document updated."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "documents",
          "corrections"
        ],
        "description": "Removes the applied transformation and rolls the document back to its original version.",
        "x-i18n": {
          "de": "Entfernt die angewendete Transformation und setzt das Dokument auf seine Originalversion zurück.",
          "en": "Removes the applied transformation and rolls the document back to its original version."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/coverpage": {
      "put": {
        "tags": [
          "documents",
          "corrections"
        ],
        "description": "Creates a cover page for the document. The recipient address is **mandatory**; the return address and the text shown below the address are optional.",
        "x-i18n": {
          "de": "Erzeugt ein Deckblatt für das Dokument. Die Empfängeradresse ist **Pflicht**; die Absenderadresse und der Text unterhalb der Adresse sind optional.",
          "en": "Creates a cover page for the document. The recipient address is **mandatory**; the return address and the text shown below the address are 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": "Optional text block on the cover page (subject, date and body text).",
                  "x-i18n": {
                    "de": "Optionaler Textblock auf dem Deckblatt (Betreff, Datum und Fließtext).",
                    "en": "Optional text block on the cover page (subject, date and body text)."
                  },
                  "type": "object",
                  "required": [
                    "text"
                  ],
                  "properties": {
                    "subject": {
                      "description": "Optional subject line on the cover page.",
                      "x-i18n": {
                        "de": "Optionale Betreffzeile auf dem Deckblatt.",
                        "en": "Optional subject line on the cover page."
                      },
                      "type": "string"
                    },
                    "date": {
                      "description": "Optional date on the cover page.",
                      "x-i18n": {
                        "de": "Optionales Datum auf dem Deckblatt.",
                        "en": "Optional date on the cover page."
                      },
                      "type": "string",
                      "format": "date"
                    },
                    "text": {
                      "description": "Body text on the cover page. Plain text only; start a new line with a line break (`\\n`).",
                      "x-i18n": {
                        "de": "Fließtext auf dem Deckblatt. Nur Klartext; eine neue Zeile mit einem Zeilenumbruch (`\\n`) beginnen.",
                        "en": "Body text on the cover page. Plain text only; start a new line with a line break (`\\n`)."
                      },
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document updated.",
            "x-i18n": {
              "de": "Dokument aktualisiert.",
              "en": "Document updated."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "documents",
          "corrections"
        ],
        "description": "Removes the cover page from the document.",
        "x-i18n": {
          "de": "Entfernt das Deckblatt vom Dokument.",
          "en": "Removes the cover page from the document."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/attachments": {
      "get": {
        "tags": [
          "documents",
          "attachments"
        ],
        "description": "Returns all attachments of the document.",
        "x-i18n": {
          "de": "Liefert alle Anhänge des Dokuments.",
          "en": "Returns all attachments of the document."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "List of the document's attachments.",
            "x-i18n": {
              "de": "Liste der Anhänge des Dokuments.",
              "en": "List of the document's attachments."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Attachment"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "post": {
        "tags": [
          "documents",
          "attachments"
        ],
        "description": "Uploads a new attachment and appends it to the document, after any attachments already appended. Returns the document's full attachment list.",
        "x-i18n": {
          "de": "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.",
          "en": "Uploads a new attachment and appends it to the document, after any attachments already appended. Returns the document's full attachment list."
        },
        "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": "If `true`, the attachment starts on the front of a new sheet.",
                  "x-i18n": {
                    "de": "Bei `true` beginnt der Anhang auf der Vorderseite eines neuen Blattes.",
                    "en": "If `true`, the attachment starts on the front of a new sheet."
                  },
                  "type": "boolean",
                  "default": true
                },
                "remarks": {
                  "description": "Free-text remarks for the attachment.",
                  "x-i18n": {
                    "de": "Freitext-Bemerkungen zum Anhang.",
                    "en": "Free-text remarks for the attachment."
                  },
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment created and appended to the document.",
            "x-i18n": {
              "de": "Anhang erstellt und an das Dokument angehängt.",
              "en": "Attachment created and appended to the document."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Attachment"
              }
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "patch": {
        "tags": [
          "documents",
          "attachments"
        ],
        "description": "Appends a list of already-uploaded attachments (by their IDs) to the document. Attachments already appended stay unchanged; the new ones are appended at the end in list order. Mind the order if it matters.",
        "x-i18n": {
          "de": "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.",
          "en": "Appends a list of already-uploaded attachments (by their IDs) to the document. Attachments already appended stay unchanged; the new ones are appended at the end in list order. Mind the order if it matters."
        },
        "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": "Attachments appended; the document's attachment list is returned.",
            "x-i18n": {
              "de": "Anhänge angehängt; die Anhangsliste des Dokuments wird zurückgegeben.",
              "en": "Attachments appended; the document's attachment list is returned."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account).",
            "x-i18n": {
              "de": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich).",
              "en": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "documents",
          "attachments"
        ],
        "description": "Detaches all attachments from the document. Only possible before dispatch release.",
        "x-i18n": {
          "de": "Entfernt alle Anhänge vom Dokument. Nur vor der Versandfreigabe möglich.",
          "en": "Detaches all attachments from the document. Only possible before dispatch release."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/documents/{documentID}/attachments/{attachmentID}": {
      "post": {
        "tags": [
          "documents",
          "attachments"
        ],
        "description": "Appends an already-uploaded attachment, identified by `attachmentID`, to the document – after any attachments already appended. Returns the document.",
        "x-i18n": {
          "de": "Hängt einen bereits hochgeladenen Anhang (per `attachmentID`) an das Dokument an – nach bereits angehängten Anhängen. Liefert das Dokument zurück.",
          "en": "Appends an already-uploaded attachment, identified by `attachmentID`, to the document – after any attachments already appended. Returns the document."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "attachmentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "documents",
          "attachments"
        ],
        "description": "Removes the attachment from the document.",
        "x-i18n": {
          "de": "Entfernt den Anhang vom Dokument.",
          "en": "Removes the attachment from the document."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "attachmentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/sendings": {
      "post": {
        "tags": [
          "sendings"
        ],
        "description": "Releases one or more already-uploaded, valid documents for dispatch – the **dispatch release**. Pass the `documentIds` of documents that are `ready to ship` (status code 2). Documents are handed to production by default at **14:30**.\n\nFrom this point on a document is managed via `/sendings` (status, cancellation), no longer via `/documents`.",
        "x-i18n": {
          "de": "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`.",
          "en": "Releases one or more already-uploaded, valid documents for dispatch – the **dispatch release**. Pass the `documentIds` of documents that are `ready to ship` (status code 2). Documents are handed to production by default at **14:30**.\n\nFrom this point on a document is managed via `/sendings` (status, cancellation), no longer via `/documents`."
        },
        "consumes": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "documentIds",
            "in": "body",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dispatch accepted – the response lists the documents and their status (a document may be faulty, code 7).",
            "x-i18n": {
              "de": "Versand angenommen – die Antwort listet die Dokumente und ihren Status (ein Dokument kann fehlerhaft sein, Code 7).",
              "en": "Dispatch accepted – the response lists the documents and their status (a document may be faulty, code 7)."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Document"
              }
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account).",
            "x-i18n": {
              "de": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich).",
              "en": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)."
            }
          }
        }
      },
      "get": {
        "tags": [
          "sendings"
        ],
        "description": "Returns all documents that have been released for dispatch or already delivered.\n\nStatus codes (`status.code` → `status.text`):\n- **3** – `processing` (de `in Verarbeitung`)\n- **4** – `printing` (de `im Druck`)\n- **5** – `sent` (de `versendet`)\n- **6** – `cancelled` (de `storniert`)\n- **7** – `faulty` (de `fehlerhaft`)\n\n**Timing:** after dispatch release the status is only meaningful from **05:00 on the following day**, and only if the sending made the **14:30 dispatch window**, because the status is updated only then.",
        "x-i18n": {
          "de": "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.",
          "en": "Returns all documents that have been released for dispatch or already delivered.\n\nStatus codes (`status.code` → `status.text`):\n- **3** – `processing` (de `in Verarbeitung`)\n- **4** – `printing` (de `im Druck`)\n- **5** – `sent` (de `versendet`)\n- **6** – `cancelled` (de `storniert`)\n- **7** – `faulty` (de `fehlerhaft`)\n\n**Timing:** after dispatch release the status is only meaningful from **05:00 on the following day**, and only if the sending made the **14:30 dispatch window**, because the status is updated only then."
        },
        "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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Document"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      },
      "put": {
        "tags": [
          "sendings"
        ],
        "description": "Cancels the dispatch of the listed documents (by `documentIds`). Only documents that have **not yet been shipped** can be cancelled; cancellation is possible until **shortly before the 14:30 dispatch window**.",
        "x-i18n": {
          "de": "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.",
          "en": "Cancels the dispatch of the listed documents (by `documentIds`). Only documents that have **not yet been shipped** can be cancelled; cancellation is possible until **shortly before the 14:30 dispatch window**."
        },
        "consumes": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "documentIds",
            "in": "body",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of document statuses (`documentID` and `status`). For a serial document, the statuses of the child documents are also listed.",
            "x-i18n": {
              "de": "Liste der Dokumentstatus (`documentID` und `status`). Bei einem Serienbrief werden auch die Status der Kind-Dokumente aufgeführt.",
              "en": "List of document statuses (`documentID` and `status`). For a serial document, the statuses of the child documents are also listed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/DocumentStatus"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account).",
            "x-i18n": {
              "de": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich).",
              "en": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)."
            }
          }
        }
      }
    },
    "/sendings/document": {
      "post": {
        "tags": [
          "sendings"
        ],
        "description": "Uploads a document and, if it validates successfully, sends it **directly** – combining [`POST /documents`](#op:documents:uploadDocument:post:/documents) and [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings) in a single call. The same file rules as for the upload apply (PDF/PS, PDF/A-2b, max **20 MB**, Base64).\n\n**Reliability:** On HTTP `500` the document may still have been created. Send a unique custom attribute (e.g. `documentID`) and verify via `GET /documents/findbyAttributes` before retrying.",
        "x-i18n": {
          "de": "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`.",
          "en": "Uploads a document and, if it validates successfully, sends it **directly** – combining [`POST /documents`](#op:documents:uploadDocument:post:/documents) and [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings) in a single call. The same file rules as for the upload apply (PDF/PS, PDF/A-2b, max **20 MB**, Base64).\n\n**Reliability:** On HTTP `500` the document may still have been created. Send a unique custom attribute (e.g. `documentID`) and verify via `GET /documents/findbyAttributes` before retrying."
        },
        "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": "Your internal customer/tenant number for this order (max. 32 characters). It is stored on the order and forwarded to production. Replaces the former `tenant` custom attribute.",
                  "x-i18n": {
                    "de": "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`.",
                    "en": "Your internal customer/tenant number for this order (max. 32 characters). It is stored on the order and forwarded to production. Replaces the former `tenant` custom attribute."
                  }
                },
                "externalReferenceId": {
                  "type": "string",
                  "maxLength": 64,
                  "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
                  "description": "Your internal reference id for this order (max. 64 characters); a **UUID** is the ideal format. Searchable via `GET /documents/findByExternalReferenceId`. Replaces the former `documentID` custom attribute.",
                  "x-i18n": {
                    "de": "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`.",
                    "en": "Your internal reference id for this order (max. 64 characters); a **UUID** is the ideal format. Searchable via `GET /documents/findByExternalReferenceId`. Replaces the former `documentID` custom attribute."
                  }
                },
                "externalReferenceIdUnique": {
                  "type": "boolean",
                  "default": false,
                  "description": "Opt-in duplicate protection. If `true`, the request is rejected when another of your orders already carries this `externalReferenceId` (guards against accidental double submissions).",
                  "x-i18n": {
                    "de": "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).",
                    "en": "Opt-in duplicate protection. If `true`, the request is rejected when another of your orders already carries this `externalReferenceId` (guards against accidental double submissions)."
                  }
                },
                "responseFormat": {
                  "$ref": "#/definitions/ResponseFormatEnum"
                }
              },
              "example": {
                "content": {
                  "filename": "musterbrief.pdf",
                  "content": "<Base64-encoded PDF>"
                },
                "tenantId": "kostenstelle-4711",
                "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document created and dispatched – may be faulty (check `status`; code 7 = faulty).",
            "x-i18n": {
              "de": "Dokument erstellt und versendet – kann fehlerhaft sein (prüfen Sie `status`; Code 7 = fehlerhaft).",
              "en": "Document created and dispatched – may be faulty (check `status`; code 7 = faulty)."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          },
          "413": {
            "description": "Request Entity Too Large – the limit is 20 MB.",
            "x-i18n": {
              "de": "Anfrage zu groß – das Limit beträgt 20 MB.",
              "en": "Request Entity Too Large – the limit is 20 MB."
            }
          }
        }
      }
    },
    "/sendings/status": {
      "get": {
        "tags": [
          "sendings",
          "status"
        ],
        "description": "Returns the dispatch status of documents that have been released for dispatch or already delivered. Optionally narrow via `documentIds`.\n\nStatus codes 3–7 (`status.code` → `status.text`; see the `Status` model):\n- **3** `processing` (de `in Verarbeitung`), **4** `printing` (de `im Druck`), **5** `sent` (de `versendet`), **6** `cancelled` (de `storniert`), **7** `faulty` (de `fehlerhaft`).\n\n**Timing:** meaningful only from **05:00 on the following day**, and only if the sending made the **14:30 dispatch window**.",
        "x-i18n": {
          "de": "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.",
          "en": "Returns the dispatch status of documents that have been released for dispatch or already delivered. Optionally narrow via `documentIds`.\n\nStatus codes 3–7 (`status.code` → `status.text`; see the `Status` model):\n- **3** `processing` (de `in Verarbeitung`), **4** `printing` (de `im Druck`), **5** `sent` (de `versendet`), **6** `cancelled` (de `storniert`), **7** `faulty` (de `fehlerhaft`).\n\n**Timing:** meaningful only from **05:00 on the following day**, and only if the sending made the **14:30 dispatch window**."
        },
        "parameters": [
          {
            "name": "documentIds",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32"
            },
            "collectionFormat": "multi",
            "allowEmptyValue": false
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/DocumentStatus"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/sendings/{documentID}/status": {
      "get": {
        "tags": [
          "sendings",
          "status"
        ],
        "description": "Returns the dispatch status of a single document that has been released for dispatch or already delivered (status codes 3–7; see the `Status` model).",
        "x-i18n": {
          "de": "Liefert den Versandstatus eines einzelnen Dokuments, das zum Versand freigegeben oder bereits zugestellt wurde (Statuscodes 3–7; siehe Modell `Status`).",
          "en": "Returns the dispatch status of a single document that has been released for dispatch or already delivered (status codes 3–7; see the `Status` model)."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/DocumentStatus"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/sendings/{documentID}": {
      "post": {
        "tags": [
          "sendings"
        ],
        "description": "Releases a single document for dispatch, if it has not yet been shipped (single-document variant of [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)).",
        "x-i18n": {
          "de": "Gibt ein einzelnes Dokument zum Versand frei, sofern es noch nicht versendet wurde (Einzel-Variante von [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)).",
          "en": "Releases a single document for dispatch, if it has not yet been shipped (single-document variant of [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings))."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "get": {
        "tags": [
          "sendings"
        ],
        "description": "Returns a referenced sending. The sending is a single letter, a serial letter or an `error` object.",
        "x-i18n": {
          "de": "Liefert eine referenzierte Sendung. Die Sendung ist ein Einzelbrief, ein Serienbrief oder ein `error`-Objekt.",
          "en": "Returns a referenced sending. The sending is a single letter, a serial letter or an `error` object."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Document"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      },
      "put": {
        "tags": [
          "sendings"
        ],
        "description": "Cancels the dispatch of a single document, if it has not yet been shipped (single-document variant of the cancellation).",
        "x-i18n": {
          "de": "Storniert den Versand eines einzelnen Dokuments, sofern es noch nicht versendet wurde (Einzel-Variante der Stornierung).",
          "en": "Cancels the dispatch of a single document, if it has not yet been shipped (single-document variant of the cancellation)."
        },
        "parameters": [
          {
            "in": "path",
            "name": "documentID",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Status"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "sendings"
        ],
        "description": "Deletes a finished document from the system – i.e. one that is cancelled, or delivered and sent. Use this to remove completed entries.",
        "x-i18n": {
          "de": "Löscht ein abgeschlossenes Dokument aus dem System – also ein storniertes oder ein zugestelltes und versendetes. Dient dem Entfernen erledigter Einträge.",
          "en": "Deletes a finished document from the system – i.e. one that is cancelled, or delivered and sent. Use this to remove completed entries."
        },
        "parameters": [
          {
            "in": "path",
            "name": "documentID",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/regmails/": {
      "get": {
        "tags": [
          "regmails",
          "sendings",
          "status"
        ],
        "description": "Returns status and tracking information for all registered-mail items (Einschreiben). Only items in delivery carry tracking information, which can be followed all the way to the mailbox.",
        "x-i18n": {
          "de": "Liefert Status- und Tracking-Informationen aller Einschreiben. Nur Einschreiben in Zustellung tragen Tracking-Informationen; diese lassen sich bis in den Briefkasten verfolgen.",
          "en": "Returns status and tracking information for all registered-mail items (Einschreiben). Only items in delivery carry tracking information, which can be followed all the way to the mailbox."
        },
        "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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/RegmailStatus"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      }
    },
    "/regmails/{documentID}": {
      "get": {
        "tags": [
          "regmails",
          "sendings",
          "status"
        ],
        "description": "Returns status and tracking information for a single registered-mail item (Einschreiben). Tracking information is available only once the item is in delivery and can be followed all the way to the mailbox.",
        "x-i18n": {
          "de": "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.",
          "en": "Returns status and tracking information for a single registered-mail item (Einschreiben). Tracking information is available only once the item is in delivery and can be followed all the way to the mailbox."
        },
        "parameters": [
          {
            "name": "documentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/RegmailStatus"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document not found – no registered-mail item exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Einschreiben (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no registered-mail item exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/attachments": {
      "post": {
        "tags": [
          "attachments"
        ],
        "description": "Uploads a new attachment to the attachment pool. The attachment can then be appended to documents (e.g. via `POST /documents/{documentID}/attachments/{attachmentID}`).",
        "x-i18n": {
          "de": "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}`).",
          "en": "Uploads a new attachment to the attachment pool. The attachment can then be appended to documents (e.g. via `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": "If `true`, the attachment starts on the front of a new sheet.",
                  "x-i18n": {
                    "de": "Bei `true` beginnt der Anhang auf der Vorderseite eines neuen Blattes.",
                    "en": "If `true`, the attachment starts on the front of a new sheet."
                  },
                  "type": "boolean",
                  "default": true
                },
                "remarks": {
                  "description": "Free-text remarks for the attachment.",
                  "x-i18n": {
                    "de": "Freitext-Bemerkungen zum Anhang.",
                    "en": "Free-text remarks for the attachment."
                  },
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment created in the pool.",
            "x-i18n": {
              "de": "Anhang im Pool erstellt.",
              "en": "Attachment created in the pool."
            },
            "schema": {
              "$ref": "#/definitions/Attachment"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "413": {
            "description": "Request Entity Too Large – the limit is 20 MB.",
            "x-i18n": {
              "de": "Anfrage zu groß – das Limit beträgt 20 MB.",
              "en": "Request Entity Too Large – the limit is 20 MB."
            }
          }
        }
      },
      "get": {
        "tags": [
          "attachments"
        ],
        "description": "Returns all attachments in the pool.",
        "x-i18n": {
          "de": "Liefert alle Anhänge im Pool.",
          "en": "Returns all attachments in the pool."
        },
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Attachment"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/attachments/{attachmentID}": {
      "get": {
        "tags": [
          "attachments"
        ],
        "description": "Returns the referenced attachment.",
        "x-i18n": {
          "de": "Liefert den referenzierten Anhang.",
          "en": "Returns the referenced attachment."
        },
        "parameters": [
          {
            "in": "path",
            "name": "attachmentID",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Attachment"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "attachments"
        ],
        "description": "Deletes the referenced attachment. Only possible if it is not currently appended to any not-yet-shipped document – detach it first via `DELETE /attachments/{attachmentID}/documents`.",
        "x-i18n": {
          "de": "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.",
          "en": "Deletes the referenced attachment. Only possible if it is not currently appended to any not-yet-shipped document – detach it first via `DELETE /attachments/{attachmentID}/documents`."
        },
        "parameters": [
          {
            "in": "path",
            "name": "attachmentID",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      }
    },
    "/attachments/{attachmentID}/pdf": {
      "get": {
        "tags": [
          "attachments"
        ],
        "description": "Returns a PDF preview of the referenced attachment.",
        "x-i18n": {
          "de": "Liefert eine PDF-Vorschau des referenzierten Anhangs.",
          "en": "Returns a PDF preview of the referenced attachment."
        },
        "parameters": [
          {
            "name": "attachmentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "file"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      }
    },
    "/attachments/{attachmentID}/png": {
      "get": {
        "tags": [
          "attachments"
        ],
        "description": "Returns a PNG preview of the referenced attachment's first page.",
        "x-i18n": {
          "de": "Liefert eine PNG-Vorschau der ersten Seite des referenzierten Anhangs.",
          "en": "Returns a PNG preview of the referenced attachment's first page."
        },
        "parameters": [
          {
            "name": "attachmentID",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "file"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          },
          "406": {
            "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document).",
            "x-i18n": {
              "de": "Nicht akzeptabel – die angeforderte Repräsentation kann nicht geliefert werden (z. B. keine Vorschau für dieses Dokument verfügbar).",
              "en": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)."
            }
          }
        }
      }
    },
    "/attachments/{attachmentID}/documents": {
      "get": {
        "tags": [
          "attachments"
        ],
        "description": "Returns all not-yet-shipped documents this attachment is appended to.",
        "x-i18n": {
          "de": "Liefert alle noch nicht versendeten Dokumente, an die dieser Anhang angehängt ist.",
          "en": "Returns all not-yet-shipped documents this attachment is appended to."
        },
        "parameters": [
          {
            "in": "path",
            "name": "attachmentID",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Document"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          }
        }
      },
      "patch": {
        "tags": [
          "attachments"
        ],
        "description": "Appends this attachment to all documents in the list. It is appended at the end of each document, after any attachments already present.",
        "x-i18n": {
          "de": "Hängt diesen Anhang an alle Dokumente der Liste an – jeweils am Ende des Dokuments, nach bereits vorhandenen Anhängen.",
          "en": "Appends this attachment to all documents in the list. It is appended at the end of each document, after any attachments already present."
        },
        "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": "Attachment appended to all documents in the list.",
            "x-i18n": {
              "de": "Anhang an alle Dokumente der Liste angehängt.",
              "en": "Attachment appended to all documents in the list."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/DocumentStatus"
              }
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account).",
            "x-i18n": {
              "de": "Dokument(e) nicht vorhanden – eine oder mehrere der angegebenen IDs wurden nicht gefunden (oder sind für diesen Account nicht zugänglich).",
              "en": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)."
            }
          }
        }
      },
      "delete": {
        "tags": [
          "attachments"
        ],
        "description": "Removes the referenced attachment from all documents that have not yet been shipped.",
        "x-i18n": {
          "de": "Entfernt den referenzierten Anhang aus allen noch nicht versendeten Dokumenten.",
          "en": "Removes the referenced attachment from all documents that have not yet been shipped."
        },
        "parameters": [
          {
            "in": "path",
            "name": "attachmentID",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/DocumentStatus"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Anhang nicht gefunden – zur angegebenen ID existiert kein Anhang (oder er ist für diesen Account nicht zugänglich).",
              "en": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)."
            }
          }
        }
      }
    },
    "/accounts": {
      "get": {
        "tags": [
          "accounts"
        ],
        "description": "Returns the account's financial data (e.g. balance).",
        "x-i18n": {
          "de": "Liefert die Finanzdaten des Accounts (z. B. Guthaben).",
          "en": "Returns the account's financial data (e.g. balance)."
        },
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Account"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/accounts/personaldata": {
      "get": {
        "tags": [
          "accounts"
        ],
        "description": "Returns the account's personal data.",
        "x-i18n": {
          "de": "Liefert die persönlichen Daten des Accounts.",
          "en": "Returns the account's personal data."
        },
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/User"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "User not found – no user exists for the given account or identifier.",
            "x-i18n": {
              "de": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer.",
              "en": "User not found – no user exists for the given account or identifier."
            }
          }
        }
      },
      "patch": {
        "tags": [
          "accounts"
        ],
        "description": "Updates the account's personal data.",
        "x-i18n": {
          "de": "Aktualisiert die persönlichen Daten des Accounts.",
          "en": "Updates the account's personal data."
        },
        "parameters": [
          {
            "name": "personalData",
            "in": "body",
            "required": true,
            "schema": {
              "description": "The customer's personal data.",
              "x-i18n": {
                "de": "Die persönlichen Daten des Kunden.",
                "en": "The customer's personal data."
              },
              "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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/User"
            }
          },
          "400": {
            "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values).",
            "x-i18n": {
              "de": "Ungültige Anfrage – die Anfrage ist fehlerhaft aufgebaut (z. B. fehlende Pflichtfelder oder ungültige Werte).",
              "en": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)."
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "User not found – no user exists for the given account or identifier.",
            "x-i18n": {
              "de": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer.",
              "en": "User not found – no user exists for the given account or identifier."
            }
          }
        }
      }
    },
    "/accounts/options": {
      "get": {
        "tags": [
          "accounts"
        ],
        "description": "Returns the default dispatch options assigned to the account (applied to new documents).",
        "x-i18n": {
          "de": "Liefert die Standard-Versandoptionen des Accounts (werden auf neue Dokumente angewendet).",
          "en": "Returns the default dispatch options assigned to the account (applied to new documents)."
        },
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Options"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "User not found – no user exists for the given account or identifier.",
            "x-i18n": {
              "de": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer.",
              "en": "User not found – no user exists for the given account or identifier."
            }
          }
        }
      },
      "put": {
        "tags": [
          "accounts"
        ],
        "description": "Updates the default dispatch options assigned to the account.",
        "x-i18n": {
          "de": "Aktualisiert die Standard-Versandoptionen des Accounts.",
          "en": "Updates the default dispatch options assigned to the account."
        },
        "parameters": [
          {
            "name": "defaultOptions",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Options"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "$ref": "#/definitions/Options"
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          },
          "404": {
            "description": "User not found – no user exists for the given account or identifier.",
            "x-i18n": {
              "de": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer.",
              "en": "User not found – no user exists for the given account or identifier."
            }
          }
        }
      }
    },
    "/accounts/coworkers": {
      "get": {
        "tags": [
          "accounts"
        ],
        "description": "Returns the account's coworkers (sub-users).",
        "x-i18n": {
          "de": "Liefert die Mitarbeiter (Unterbenutzer) des Accounts.",
          "en": "Returns the account's coworkers (sub-users)."
        },
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Coworker"
              }
            }
          },
          "403": {
            "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource.",
            "x-i18n": {
              "de": "Zugriff verweigert – fehlende oder ungültige Authentifizierung bzw. keine Berechtigung für diese Ressource.",
              "en": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource."
            }
          }
        }
      }
    },
    "/accounts/coworkers/{debitornumber}/journal/{month}": {
      "get": {
        "tags": [
          "accounts"
        ],
        "description": "Returns all transactions of the given month for a specific coworker (identified by `debitornumber`).",
        "x-i18n": {
          "de": "Liefert alle Transaktionen des angegebenen Monats für einen bestimmten Mitarbeiter (per `debitornumber`).",
          "en": "Returns all transactions of the given month for a specific coworker (identified by `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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Transaction"
              }
            }
          },
          "404": {
            "description": "User not found – no user exists for the given account or identifier.",
            "x-i18n": {
              "de": "Benutzer nicht gefunden – zum angegebenen Account bzw. Bezeichner existiert kein Benutzer.",
              "en": "User not found – no user exists for the given account or identifier."
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      }
    },
    "/accounts/journal/{month}": {
      "get": {
        "tags": [
          "accounts"
        ],
        "description": "Returns all transactions of the given month for the account.",
        "x-i18n": {
          "de": "Liefert alle Transaktionen des angegebenen Monats für den Account.",
          "en": "Returns all transactions of the given month for the 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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Transaction"
              }
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      }
    },
    "/invoices": {
      "get": {
        "tags": [
          "invoices"
        ],
        "description": "Returns references to all stored invoices.",
        "x-i18n": {
          "de": "Liefert Referenzen zu allen gespeicherten Rechnungen.",
          "en": "Returns references to all stored invoices."
        },
        "responses": {
          "200": {
            "description": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Invoice"
              }
            }
          }
        }
      }
    },
    "/invoices/{invoiceNumber}": {
      "get": {
        "tags": [
          "invoices"
        ],
        "description": "Returns all transactions of the invoice.",
        "x-i18n": {
          "de": "Liefert alle Transaktionen der Rechnung.",
          "en": "Returns all transactions of the invoice."
        },
        "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": "Successful response – the request was processed.",
            "x-i18n": {
              "de": "Erfolgreiche Antwort – die Anfrage wurde verarbeitet.",
              "en": "Successful response – the request was processed."
            },
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Transaction"
              }
            }
          },
          "413": {
            "description": "Requested amount of data is too large – please use `limit` and `offset`.",
            "x-i18n": {
              "de": "Zu viele Daten angefordert – bitte `limit` und `offset` verwenden.",
              "en": "Requested amount of data is too large – please use `limit` and `offset`."
            }
          }
        }
      }
    },
    "/invoices/{invoiceNumber}/pdf": {
      "get": {
        "tags": [
          "invoices"
        ],
        "description": "Returns the invoice as a PDF.",
        "x-i18n": {
          "de": "Liefert die Rechnung als PDF.",
          "en": "Returns the invoice as a PDF."
        },
        "parameters": [
          {
            "in": "path",
            "name": "invoiceNumber",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The invoice as a PDF.",
            "x-i18n": {
              "de": "Die Rechnung als PDF.",
              "en": "The invoice as a PDF."
            },
            "schema": {
              "type": "file"
            }
          },
          "404": {
            "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account).",
            "x-i18n": {
              "de": "Dokument nicht gefunden – zur angegebenen `documentID` existiert kein Dokument (oder es ist für diesen Account nicht zugänglich).",
              "en": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)."
            }
          }
        }
      }
    }
  },
  "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\u00dfe 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": "Type of document.\n- `Letter` – single letter\n- `SerialLetter` – serial letter (split into multiple letters)",
          "x-i18n": {
            "de": "Dokumenttyp.\n- `Letter` – Einzelbrief\n- `SerialLetter` – Serienbrief (in mehrere Briefe aufgeteilt)",
            "en": "Type of document.\n- `Letter` – single letter\n- `SerialLetter` – serial letter (split into multiple letters)"
          },
          "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": "Number of documents this attachment is currently appended to.",
          "x-i18n": {
            "de": "Anzahl der Dokumente, an die dieser Anhang aktuell angehängt ist.",
            "en": "Number of documents this attachment is currently appended to."
          },
          "type": "integer",
          "format": "int32"
        },
        "remarks": {
          "type": "string"
        }
      }
    },
    "Letter": {
      "type": "object",
      "required": [
        "letterType"
      ],
      "properties": {
        "letterType": {
          "description": "Type of letter content.\n- `LetterData` – valid letter data\n- `Error` – an error object (validation failed)",
          "x-i18n": {
            "de": "Art des Briefinhalts.\n- `LetterData` – gültige Briefdaten\n- `Error` – Fehler-Objekt (Validierung fehlgeschlagen)",
            "en": "Type of letter content.\n- `LetterData` – valid letter data\n- `Error` – an error object (validation failed)"
          },
          "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": "Recipient address as detected in the letter's address field. Format: each part in quotes, space-separated (company/name, name, street, ZIP + city).",
          "x-i18n": {
            "de": "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).",
            "en": "Recipient address as detected in the letter's address field. Format: each part in quotes, space-separated (company/name, name, street, ZIP + city)."
          },
          "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": "The attachments appended to this document. Only documents of `documentType` `Letter` can have attachments.",
          "x-i18n": {
            "de": "Die an dieses Dokument angehängten Anhänge. Nur Dokumente mit `documentType` `Letter` können Anhänge haben.",
            "en": "The attachments appended to this document. Only documents of `documentType` `Letter` can have attachments."
          },
          "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 at which the serial letter is split into individual letters.",
                      "x-i18n": {
                        "de": "Text-Token, an dem der Serienbrief in einzelne Briefe aufgeteilt wird.",
                        "en": "Text token at which the serial letter is split into individual letters."
                      }
        },
        "splitAfterNumberOfPages": {
          "type": "integer",
          "format": "int32",
          "description": "The serial letter is split every N pages.",
          "x-i18n": {
            "de": "Der Serienbrief wird alle N Seiten aufgeteilt.",
            "en": "The serial letter is split every N pages."
          }
        },
        "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 error code. A machine-readable, bilingual list (code → meaning) is published at /binectapi/error-codes.json.",
          "x-i18n": {
            "de": "Binect-Fehlercode. Eine maschinenlesbare, zweisprachige Liste (Code → Bedeutung) ist unter /binectapi/error-codes.json veröffentlicht.",
            "en": "Binect error code. A machine-readable, bilingual list (code → meaning) is published at /binectapi/error-codes.json."
          }
        },
        "text": {
          "type": "string",
          "description": "Human-readable error text with placeholders filled in.",
          "x-i18n": {
            "de": "Menschenlesbarer Fehlertext mit eingesetzten Platzhalterwerten.",
            "en": "Human-readable error text with placeholders filled in."
          }
        },
        "blankText": {
          "type": "string",
          "description": "Error text with placeholders for parameters. Placeholders are framed by %-symbols, e.g. `error on page number %pageNr% of your document`.",
          "x-i18n": {
            "de": "Fehlertext mit Platzhaltern für Parameter. Platzhalter sind von %-Zeichen umschlossen, z. B. `error on page number %pageNr% of your document`.",
            "en": "Error text with placeholders for parameters. Placeholders are framed by %-symbols, e.g. `error on page number %pageNr% of your document`."
          }
        },
        "parameters": {
          "type": "array",
          "description": "Values for the placeholders in `blankText`.",
          "x-i18n": {
            "de": "Werte für die Platzhalter in `blankText`.",
            "en": "Values for the placeholders in `blankText`."
          },
          "items": {
            "$ref": "#/definitions/ErrorParam"
          }
        },
        "errorOnPage": {
          "type": "integer",
          "format": "int32",
          "description": "Page of the document on which the error occurred.",
          "x-i18n": {
            "de": "Seite des Dokuments, auf der der Fehler aufgetreten ist.",
            "en": "Page of the document on which the error occurred."
          }
        }
      }
    },
    "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": "Sales-tax rate in percent, e.g. `19` for 19 % VAT.",
          "x-i18n": {
            "de": "Mehrwertsteuersatz in Prozent, z. B. `19` für 19 % USt.",
            "en": "Sales-tax rate in percent, e.g. `19` for 19 % VAT."
          }
        },
        "details": {
          "type": "array",
          "description": "Price breakdown by differing sales-tax rates (e.g. 19 % and 0 %).",
          "x-i18n": {
            "de": "Preisaufschlüsselung nach unterschiedlichen Steuersätzen (z. B. 19 % und 0 %).",
            "en": "Price breakdown by differing sales-tax rates (e.g. 19 % and 0 %)."
          },
          "items": {
            "$ref": "#/definitions/Price"
          }
        }
      },
      "example": {
        "priceBeforeTax": 78,
        "priceAfterTax": 93,
        "unit": "EUROCENT",
        "taxInPercent": 19
      }
    },
    "Options": {
      "type": "object",
      "properties": {
        "simplex": {
          "description": "Single-sided print if `true`; double-sided (duplex) if `false`.",
          "x-i18n": {
            "de": "Einseitiger Druck bei `true`; beidseitig (Duplex) bei `false`.",
            "en": "Single-sided print if `true`; double-sided (duplex) if `false`."
          },
          "type": "boolean"
        },
        "color": {
          "description": "Colour print if `true`; black & white if `false`.",
          "x-i18n": {
            "de": "Farbdruck bei `true`; Schwarz-Weiß bei `false`.",
            "en": "Colour print if `true`; black & white if `false`."
          },
          "type": "boolean"
        },
        "envelope": {
          "description": "Envelope format. Default is `DINLANG`.\n- `DINLANG` – DIN long (folded letter)\n- `C4` – C4 (unfolded, A4)",
          "x-i18n": {
            "de": "Umschlagformat. Standard ist `DINLANG`.\n- `DINLANG` – DIN lang (gefalteter Brief)\n- `C4` – C4 (ungefaltet, A4)",
            "en": "Envelope format. Default is `DINLANG`.\n- `DINLANG` – DIN long (folded letter)\n- `C4` – C4 (unfolded, A4)"
          },
          "type": "string",
          "enum": [
            "DINLANG",
            "C4"
          ],
          "example": "DINLANG"
        },
        "dvFranking": {
          "description": "If `true`, DV-Freimachung is mandatory and validation is stricter. **Deprecated** – use `franking` (`DV_FRANKING`) instead.",
          "x-i18n": {
            "de": "Bei `true` ist DV-Freimachung verpflichtend und die Validierung strenger. **Veraltet** – stattdessen `franking` (`DV_FRANKING`) verwenden.",
            "en": "If `true`, DV-Freimachung is mandatory and validation is stricter. **Deprecated** – use `franking` (`DV_FRANKING`) instead."
          },
          "type": "boolean"
        },
        "franking": {
          "$ref": "#/definitions/FrankingEnum"
        },
        "productionCountry": {
          "$ref": "#/definitions/ProductionCountryEnum"
        },
        "product": {
          "$ref": "#/definitions/ProductEnum"
        },
        "shippingDate": {
          "description": "Optional scheduled dispatch date (\"Versandtermin\"): the letter is released now but is produced and dispatched no earlier than this day.\nAccepts EITHER a fixed date in `YYYY-MM-DD` or `DD-MM-YYYY` format, OR a weekday: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`. For a weekday the next matching business day is used (if it is today's weekday, the following week's day is used). Only Monday–Friday are supported (no production on weekends). A fixed date must lie between tomorrow and 30 days ahead.\nOn `POST /documents` and `POST /sendings/document` a weekday is frozen to a fixed date at upload. On `PUT /documents/{documentID}/options` the field can only be changed while the document has not yet been released for dispatch. On `GET/PUT /accounts/options` (the account default) ONLY a weekday is accepted – a fixed date is rejected.\nTo explicitly set NO dispatch date, send an empty string (\"\"): on upload no dispatch date is applied and the account default is IGNORED; on `PUT /accounts/options` the configured account default is REMOVED. If the field is OMITTED entirely, the account default is inherited on upload (if configured) and kept unchanged on `/accounts/options`. In responses this field is only present when a dispatch date is set – as a fixed date for a document, as a weekday for the account default.",
          "x-i18n": {
            "de": "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.",
            "en": "Optional scheduled dispatch date: the letter is released now but is produced and dispatched no earlier than this day.\nAccepts EITHER a fixed date in `YYYY-MM-DD` or `DD-MM-YYYY` format, OR a weekday: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`. For a weekday the next matching business day is used. Only Monday–Friday are supported. On upload a weekday is frozen to a fixed date; on `/accounts/options` only a weekday is accepted. Send an empty string (\"\") for explicitly no dispatch date (ignores the account default on upload, removes it on /accounts/options); omit the field to inherit/keep the account default. Present in responses only when set."
          },
          "type": "string",
          "example": "2026-08-03"
        }
      },
      "example": {
        "simplex": true,
        "color": false,
        "envelope": "DINLANG",
        "franking": "DV_FRANKING",
        "productionCountry": "DE",
        "shippingDate": "2026-08-03"
      }
    },
    "FrankingEnum": {
      "description": "Franking method.\n- `STANDARD_FRANKING` – standard franking\n- `DV_FRANKING` – DV-Freimachung: modern method for fast dispatch with the maximum feature set (recommended)\n- `UNSPECIFIED` – not specified; the account default applies",
      "x-i18n": {
        "de": "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",
        "en": "Franking method.\n- `STANDARD_FRANKING` – standard franking\n- `DV_FRANKING` – DV-Freimachung: modern method for fast dispatch with the maximum feature set (recommended)\n- `UNSPECIFIED` – not specified; the account default applies"
      },
      "type": "string",
      "enum": [
        "UNSPECIFIED",
        "STANDARD_FRANKING",
        "DV_FRANKING"
      ]
    },
    "ProductionCountryEnum": {
      "description": "Country from which domestic mail is produced. International mail is always produced in Germany. Use requires prior approval by Binect.\n- `DE` – Germany\n- `AT` – Austria\n- `UNSPECIFIED` – not specified (default)",
      "x-i18n": {
        "de": "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)",
        "en": "Country from which domestic mail is produced. International mail is always produced in Germany. Use requires prior approval by Binect.\n- `DE` – Germany\n- `AT` – Austria\n- `UNSPECIFIED` – not specified (default)"
      },
      "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": "Postal product. Default is `NORMAL` (standard letter).\n- `NORMAL` – standard letter\n- `PREMIUMADRESS_BASIS` / `PREMIUMADRESS_REPORT` – Deutsche Post PREMIUMADRESS (recipient address-update service); for usage please contact kontakt@binect.de\n- `REGMAIL` – registered mail (Einschreiben)\n- `REGMAIL_DROP` – Einwurf-Einschreiben\n- `REGMAIL_INTERNATIONAL` – international registered mail",
      "x-i18n": {
        "de": "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",
        "en": "Postal product. Default is `NORMAL` (standard letter).\n- `NORMAL` – standard letter\n- `PREMIUMADRESS_BASIS` / `PREMIUMADRESS_REPORT` – Deutsche Post PREMIUMADRESS (recipient address-update service); for usage please contact kontakt@binect.de\n- `REGMAIL` – registered mail (Einschreiben)\n- `REGMAIL_DROP` – Einwurf-Einschreiben\n- `REGMAIL_INTERNATIONAL` – international registered mail"
      },
      "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": "The order id.",
          "x-i18n": {
            "de": "Die Auftrags-ID.",
            "en": "The order id."
          }
        },
        "status": {
          "$ref": "#/definitions/Status"
        },
        "externalReferenceId": {
          "type": "string",
          "description": "The external reference id this order was found by.",
          "x-i18n": {
            "de": "Die externe Referenz-ID, über die dieser Auftrag gefunden wurde.",
            "en": "The external reference id this order was found by."
          }
        }
      },
      "example": {
        "id": 4711,
        "status": {
          "code": 5,
          "text": "versendet"
        },
        "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
      }
    },
    "Status": {
      "type": "object",
      "required": [
        "code",
        "text"
      ],
      "properties": {
        "code": {
          "description": "The following status codes exist. The `text` is returned in the account's language (German or English):\n\n- **1** – `being created` (de `wird erstellt`)\n- **2** – `ready to ship` (de `versandbereit`)\n- **3** – `processing` (de `in Verarbeitung`)\n- **4** – `printing` (de `im Druck`)\n- **5** – `sent` (de `versendet`)\n- **6** – `cancelled` (de `storniert`)\n- **7** – `faulty` (de `fehlerhaft`)",
          "x-i18n": {
            "de": "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`)",
            "en": "The following status codes exist. The `text` is returned in the account's language (German or English):\n\n- **1** – `being created` (de `wird erstellt`)\n- **2** – `ready to ship` (de `versandbereit`)\n- **3** – `processing` (de `in Verarbeitung`)\n- **4** – `printing` (de `im Druck`)\n- **5** – `sent` (de `versendet`)\n- **6** – `cancelled` (de `storniert`)\n- **7** – `faulty` (de `fehlerhaft`)"
          },
          "type": "integer",
          "format": "int32"
        },
        "text": {
          "description": "Plain-text status, returned in the account's language (e.g. `ready to ship` / German `versandbereit`). See field `code` for the fixed mapping.",
          "x-i18n": {
            "de": "Status als Klartext, geliefert **in der Sprache des Accounts** (z. B. `versandbereit` / engl. `ready to ship`). Die feste Zuordnung siehe Feld `code`.",
            "en": "Plain-text status, returned in the account's language (e.g. `ready to ship` / German `versandbereit`). See field `code` for the fixed mapping."
          },
          "type": "string"
        }
      },
      "example": {
        "code": 2,
        "text": "versandbereit"
      }
    },
    "ResponseFormatEnum": {
      "description": "Defines the response format. Default is `FULL` (the response includes the validation result).\n\n`SHORT` returns the API response **immediately, without the validation result**; validation runs afterwards. Query the outcome via `GET /documents/status` or `GET /documents/{documentID}/status`.",
      "x-i18n": {
        "de": "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.",
        "en": "Defines the response format. Default is `FULL` (the response includes the validation result).\n\n`SHORT` returns the API response **immediately, without the validation result**; validation runs afterwards. Query the outcome via `GET /documents/status` or `GET /documents/{documentID}/status`."
      },
      "type": "string",
      "enum": [
        "FULL",
        "SHORT"
      ],
      "default": "FULL",
      "example": "FULL"
    },
    "Account": {
      "description": "Account data.",
      "x-i18n": {
        "de": "Account-Daten.",
        "en": "Account data."
      },
      "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": "The file content and file name. The content must be Base64-encoded.",
      "x-i18n": {
        "de": "Der Dateiinhalt und der Dateiname. Der Inhalt muss Base64-kodiert sein.",
        "en": "The file content and file name. The content must be Base64-encoded."
      },
      "type": "object",
      "required": [
        "filename",
        "content"
      ],
      "properties": {
        "filename": {
          "type": "string"
        },
        "content": {
          "type": "string",
          "format": "byte"
        }
      },
      "example": {
        "filename": "musterbrief.pdf",
        "content": "<Base64-encoded PDF>"
      }
    },
    "User": {
      "description": "The customer's personal data.",
      "x-i18n": {
        "de": "Die persönlichen Daten des Kunden.",
        "en": "The customer's personal data."
      },
      "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": "Data of a coworker (sub-user).",
      "x-i18n": {
        "de": "Daten eines Mitarbeiters (Unterbenutzer).",
        "en": "Data of a coworker (sub-user)."
      },
      "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": "Currency unit. `EUROCENT`: amounts are given in euro cents (e.g. `106` = 1.06 €).",
      "x-i18n": {
        "de": "Währungseinheit. `EUROCENT`: Beträge werden in Euro-Cent angegeben (z. B. `106` = 1,06 €).",
        "en": "Currency unit. `EUROCENT`: amounts are given in euro cents (e.g. `106` = 1.06 €)."
      },
      "type": "string",
      "enum": [
        "EUROCENT"
      ]
    },
    "Address": {
      "description": "An address.",
      "x-i18n": {
        "de": "Eine Adresse.",
        "en": "An address."
      },
      "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": "An invoice.",
      "x-i18n": {
        "de": "Eine Rechnung.",
        "en": "An invoice."
      },
      "type": "object",
      "required": [
        "id",
        "filename"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "filename": {
          "type": "string"
        },
        "totalAmount": {
          "$ref": "#/definitions/Price"
        },
        "date": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "Transaction": {
      "description": "A transaction – a single accounting entry (e.g. belonging to an invoice).",
      "x-i18n": {
        "de": "Eine Transaktion – ein einzelner Buchungsposten (z. B. zu einer Rechnung).",
        "en": "A transaction – a single accounting entry (e.g. belonging to an invoice)."
      },
      "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": "Debtor number (`debitornumber`) of the coworker the transaction belongs to.",
          "x-i18n": {
            "de": "Debitorennummer (`debitornumber`) des Mitarbeiters, zu dem die Transaktion gehört.",
            "en": "Debtor number (`debitornumber`) of the coworker the transaction belongs to."
          },
          "type": "string"
        }
      }
    },
    "Action": {
      "description": "Describes an action of a transaction.",
      "x-i18n": {
        "de": "Beschreibt eine Aktion einer Transaktion.",
        "en": "Describes an action of a transaction."
      },
      "type": "object",
      "required": [
        "code",
        "text"
      ],
      "properties": {
        "code": {
          "description": "The following action codes are defined:\n- **1** – sent\n- **2** – cancelled\n- **3** – delivery error",
          "x-i18n": {
            "de": "Folgende Aktionscodes sind definiert:\n- **1** – versendet\n- **2** – storniert\n- **3** – Zustellfehler",
            "en": "The following action codes are defined:\n- **1** – sent\n- **2** – cancelled\n- **3** – delivery error"
          },
          "type": "integer",
          "format": "int32"
        },
        "text": {
          "type": "string"
        }
      },
      "example": {
        "code": 1,
        "text": "is sent"
      }
    }
  }
}