{ "swagger": "2.0", "info": { "version": "1.1.0", "description": "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
\nShow example code\n

Bash (curl)

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

Python (requests)

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

JavaScript (Node 18+, fetch)

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

PHP (curl)

\n
<?php\n$baseUrl  = \"https://test-app.binect.de/binectapi/v1\"; // Prod: https://app.binect.de/binectapi/v1\n$email    = \"ihre-email@example.com\";\n$password = \"ihr-passwort\";\n$content = base64_encode(file_get_contents(\"brief.pdf\"));\n$payload = json_encode([\n  \"content\"    => [\"filename\" => \"brief.pdf\", \"content\" => $content],\n  \"options\"    => [\"simplex\" => true, \"color\" => false, \"envelope\" => \"DINLANG\",\n                   \"franking\" => \"DV_FRANKING\", \"product\" => \"NORMAL\"],\n  \"tenantId\" => \"kostenstelle-4711\",\n  \"externalReferenceId\" => \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n]);\n$ch = curl_init(\"$baseUrl/sendings/document\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST           => true,\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_USERPWD        => \"$email:$password\",\n  CURLOPT_HTTPHEADER     => [\"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS     => $payload,\n]);\n$resp = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE) . \"\\n\" . $resp . \"\\n\";
\n
\n\n## 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", "securityDefinitions": { "basicAuth": { "type": "basic", "description": "HTTP Basic authentication (username and password)." } }, "security": [ { "basicAuth": [] } ], "tags": [ { "name": "documents", "description": "Upload, validate, edit and query documents (before dispatch release)." }, { "name": "status", "description": "Status queries for documents and sendings." }, { "name": "corrections", "description": "Corrections to documents: transformations and cover page." }, { "name": "attachments", "description": "Manage attachments (the attachment pool and per-document attachments)." }, { "name": "sendings", "description": "Dispatch release, cancellation and dispatch status." }, { "name": "regmails", "description": "Registered mail: status and tracking." }, { "name": "accounts", "description": "Account: balance, personal data, default shipping options, coworkers, journal." }, { "name": "invoices", "description": "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).", "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." }, "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." }, "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)." }, "splitParams": { "description": "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." }, "splitAfterNumberOfPages": { "type": "integer", "format": "int32", "description": "The serial letter is split every N pages." } }, "example": { "splitToken": "Sehr geehrte" } }, "responseFormat": { "$ref": "#/definitions/ResponseFormatEnum" } }, "example": { "content": { "filename": "musterbrief.pdf", "content": "" }, "tenantId": "kostenstelle-4711", "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } } ], "responses": { "200": { "description": "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)." }, "403": { "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource." }, "413": { "description": "Request Entity Too Large – the limit is 20 MB." } }, "operationId": "uploadDocument" }, "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`.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "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`." } }, "operationId": "listShippableDocuments" } }, "/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`)", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "403": { "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource." } }, "operationId": "listDocumentValidationStatus" } }, "/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`.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "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`." } }, "operationId": "listFaultyDocuments" } }, "/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.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "400": { "description": "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." } }, "operationId": "findDocumentsByAttributes" } }, "/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.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentReferenceStatus" } } }, "400": { "description": "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." } } } }, "/documents/{documentID}": { "get": { "tags": [ "documents" ], "description": "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.", "schema": { "$ref": "#/definitions/Document" } }, "403": { "description": "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)." } }, "operationId": "getDocument" }, "delete": { "tags": [ "documents" ], "description": "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." }, "403": { "description": "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)." } }, "operationId": "deleteDocument" } }, "/documents/{documentID}/status": { "get": { "tags": [ "documents", "status" ], "description": "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.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "403": { "description": "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)." } }, "operationId": "getDocumentStatus" } }, "/documents/{documentID}/options": { "get": { "tags": [ "documents" ], "description": "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.", "schema": { "$ref": "#/definitions/Options" } }, "403": { "description": "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)." } }, "operationId": "getDocumentOptions" }, "put": { "tags": [ "documents" ], "description": "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.", "schema": { "$ref": "#/definitions/Options" } }, "403": { "description": "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)." } }, "operationId": "updateDocumentOptions" } }, "/documents/{documentID}/attributes": { "get": { "tags": [ "documents" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } }, "403": { "description": "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)." } }, "operationId": "listDocumentAttributes" }, "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.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } }, "400": { "description": "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." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "addDocumentAttributes" } }, "/documents/{documentID}/attributes/{key}": { "get": { "tags": [ "documents" ], "description": "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.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "403": { "description": "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)." } }, "operationId": "getDocumentAttribute" }, "put": { "tags": [ "documents" ], "description": "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.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "400": { "description": "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." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "setDocumentAttribute" }, "delete": { "tags": [ "documents" ], "description": "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." }, "403": { "description": "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)." } }, "operationId": "deleteDocumentAttribute" } }, "/documents/{documentID}/pdf": { "get": { "tags": [ "documents" ], "description": "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.", "schema": { "type": "file" } }, "403": { "description": "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)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getDocumentPdf" } }, "/documents/{documentID}/png": { "get": { "tags": [ "documents" ], "description": "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.", "schema": { "type": "file" } }, "403": { "description": "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)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getDocumentPng" } }, "/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.", "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.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "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." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "applyDocumentTransformation" }, "delete": { "tags": [ "documents", "corrections" ], "description": "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." }, "400": { "description": "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." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "resetDocumentTransformation" } }, "/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.", "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).", "type": "object", "required": [ "text" ], "properties": { "subject": { "description": "Optional subject line on the cover page.", "type": "string" }, "date": { "description": "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`).", "type": "string" } } } } } } ], "responses": { "200": { "description": "Document updated.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "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." }, "404": { "description": "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)." } }, "operationId": "setDocumentCoverPage" }, "delete": { "tags": [ "documents", "corrections" ], "description": "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." }, "403": { "description": "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)." } }, "operationId": "deleteDocumentCoverPage" } }, "/documents/{documentID}/attachments": { "get": { "tags": [ "documents", "attachments" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "403": { "description": "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)." } }, "operationId": "listDocumentAttachments" }, "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.", "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.", "type": "boolean", "default": true }, "remarks": { "description": "Free-text remarks for the attachment.", "type": "string" } } } } ], "responses": { "200": { "description": "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)." }, "403": { "description": "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)." } }, "operationId": "uploadDocumentAttachment" }, "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.", "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.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "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." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." } }, "operationId": "appendDocumentAttachments" }, "delete": { "tags": [ "documents", "attachments" ], "description": "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.", "schema": { "$ref": "#/definitions/Document" } }, "403": { "description": "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)." } }, "operationId": "deleteDocumentAttachments" } }, "/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.", "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.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "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." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "appendDocumentAttachment" }, "delete": { "tags": [ "documents", "attachments" ], "description": "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.", "schema": { "$ref": "#/definitions/Document" } }, "403": { "description": "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)." } }, "operationId": "removeDocumentAttachment" } }, "/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`.", "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).", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "400": { "description": "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." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." } }, "operationId": "releaseForDispatch" }, "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.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "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`." } }, "operationId": "listSendings" }, "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**.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "403": { "description": "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)." } }, "operationId": "cancelDispatch" } }, "/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.", "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." }, "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." }, "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)." }, "responseFormat": { "$ref": "#/definitions/ResponseFormatEnum" } }, "example": { "content": { "filename": "musterbrief.pdf", "content": "" }, "tenantId": "kostenstelle-4711", "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } } ], "responses": { "200": { "description": "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)." }, "403": { "description": "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)." }, "413": { "description": "Request Entity Too Large – the limit is 20 MB." } }, "operationId": "uploadAndSendDocument" } }, "/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**.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "403": { "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource." } }, "operationId": "listSendingStatus" } }, "/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).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "403": { "description": "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)." } }, "operationId": "getSendingStatus" } }, "/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)).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "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)." }, "403": { "description": "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)." } }, "operationId": "releaseDocumentForDispatch" }, "get": { "tags": [ "sendings" ], "description": "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.", "schema": { "$ref": "#/definitions/Document" } }, "403": { "description": "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)." } }, "operationId": "getSending" }, "put": { "tags": [ "sendings" ], "description": "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.", "schema": { "$ref": "#/definitions/Status" } }, "403": { "description": "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)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "cancelDocumentDispatch" }, "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.", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "403": { "description": "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)." } }, "operationId": "deleteSending" } }, "/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.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/RegmailStatus" } } }, "403": { "description": "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`." } }, "operationId": "listRegisteredMail" } }, "/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.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/RegmailStatus" } }, "403": { "description": "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)." } }, "operationId": "getRegisteredMail" } }, "/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}`).", "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.", "type": "boolean", "default": true }, "remarks": { "description": "Free-text remarks for the attachment.", "type": "string" } } } } ], "responses": { "200": { "description": "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)." }, "403": { "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource." }, "413": { "description": "Request Entity Too Large – the limit is 20 MB." } }, "operationId": "uploadAttachment" }, "get": { "tags": [ "attachments" ], "description": "Returns all attachments in the pool.", "responses": { "200": { "description": "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." } }, "operationId": "listAttachments" } }, "/attachments/{attachmentID}": { "get": { "tags": [ "attachments" ], "description": "Returns the referenced attachment.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Attachment" } }, "403": { "description": "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)." } }, "operationId": "getAttachment" }, "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`.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "403": { "description": "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)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "deleteAttachment" } }, "/attachments/{attachmentID}/pdf": { "get": { "tags": [ "attachments" ], "description": "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.", "schema": { "type": "file" } }, "403": { "description": "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)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getAttachmentPdf" } }, "/attachments/{attachmentID}/png": { "get": { "tags": [ "attachments" ], "description": "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.", "schema": { "type": "file" } }, "403": { "description": "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)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getAttachmentPng" } }, "/attachments/{attachmentID}/documents": { "get": { "tags": [ "attachments" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "403": { "description": "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)." } }, "operationId": "listAttachmentDocuments" }, "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.", "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "400": { "description": "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." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." } }, "operationId": "attachToDocuments" }, "delete": { "tags": [ "attachments" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "403": { "description": "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)." } }, "operationId": "detachFromDocuments" } }, "/accounts": { "get": { "tags": [ "accounts" ], "description": "Returns the account's financial data (e.g. balance).", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Account" } }, "403": { "description": "Forbidden – missing or invalid authentication, or insufficient permissions for this resource." } }, "operationId": "getAccount" } }, "/accounts/personaldata": { "get": { "tags": [ "accounts" ], "description": "Returns the account's personal data.", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/User" } }, "403": { "description": "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." } }, "operationId": "getPersonalData" }, "patch": { "tags": [ "accounts" ], "description": "Updates the account's personal data.", "parameters": [ { "name": "personalData", "in": "body", "required": true, "schema": { "description": "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.", "schema": { "$ref": "#/definitions/User" } }, "400": { "description": "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." }, "404": { "description": "User not found – no user exists for the given account or identifier." } }, "operationId": "updatePersonalData" } }, "/accounts/options": { "get": { "tags": [ "accounts" ], "description": "Returns the default dispatch options assigned to the account (applied to new documents).", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Options" } }, "403": { "description": "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." } }, "operationId": "getAccountOptions" }, "put": { "tags": [ "accounts" ], "description": "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.", "schema": { "$ref": "#/definitions/Options" } }, "403": { "description": "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." } }, "operationId": "updateAccountOptions" } }, "/accounts/coworkers": { "get": { "tags": [ "accounts" ], "description": "Returns the account's coworkers (sub-users).", "responses": { "200": { "description": "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." } }, "operationId": "listCoworkers" } }, "/accounts/coworkers/{debitornumber}/journal/{month}": { "get": { "tags": [ "accounts" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "404": { "description": "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`." } }, "operationId": "getCoworkerJournal" } }, "/accounts/journal/{month}": { "get": { "tags": [ "accounts" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "413": { "description": "Requested amount of data is too large – please use `limit` and `offset`." } }, "operationId": "getAccountJournal" } }, "/invoices": { "get": { "tags": [ "invoices" ], "description": "Returns references to all stored invoices.", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Invoice" } } } }, "operationId": "listInvoices" } }, "/invoices/{invoiceNumber}": { "get": { "tags": [ "invoices" ], "description": "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.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "413": { "description": "Requested amount of data is too large – please use `limit` and `offset`." } }, "operationId": "getInvoiceTransactions" } }, "/invoices/{invoiceNumber}/pdf": { "get": { "tags": [ "invoices" ], "description": "Returns the invoice as a PDF.", "parameters": [ { "in": "path", "name": "invoiceNumber", "required": true, "type": "string" } ], "responses": { "200": { "description": "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)." } }, "operationId": "getInvoicePdf" } } }, "definitions": { "Document": { "type": "object", "example": { "id": 4711, "filename": "letter.pdf", "numberOfPages": 1, "documentType": "Letter", "status": { "code": 2, "text": "versandbereit" }, "letter": { "letterType": "LetterData", "letterData": { "recipientAddress": "\"Musterfirma GmbH\" \"Max Mustermann\" \"Musterstraße 1\" \"12345 Musterstadt\"", "international": false, "options": { "simplex": true, "color": false, "envelope": "DINLANG", "franking": "DV_FRANKING", "product": "NORMAL", "productionCountry": "DE" }, "price": { "priceBeforeTax": 89, "priceAfterTax": 106, "unit": "EUROCENT", "taxInPercent": 19 }, "attributes": [ { "key": "documentID", "value": "DOC-2024-0001" } ] } } }, "required": [ "id", "filename", "status", "documentType" ], "properties": { "id": { "type": "integer", "format": "int32" }, "filename": { "type": "string" }, "numberOfPages": { "type": "integer", "format": "int32" }, "status": { "$ref": "#/definitions/Status" }, "documentType": { "description": "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.", "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)", "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).", "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.", "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." }, "splitAfterNumberOfPages": { "type": "integer", "format": "int32", "description": "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." }, "text": { "type": "string", "description": "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`." }, "parameters": { "type": "array", "description": "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." } } }, "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." }, "details": { "type": "array", "description": "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`.", "type": "boolean" }, "color": { "description": "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)", "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.", "type": "boolean" }, "franking": { "$ref": "#/definitions/FrankingEnum" }, "productionCountry": { "$ref": "#/definitions/ProductionCountryEnum" }, "product": { "$ref": "#/definitions/ProductEnum" }, "shippingDate": { "description": "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", "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)", "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", "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." }, "status": { "$ref": "#/definitions/Status" }, "externalReferenceId": { "type": "string", "description": "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`)", "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.", "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`.", "type": "string", "enum": [ "FULL", "SHORT" ], "default": "FULL", "example": "FULL" }, "Account": { "description": "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.", "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string" }, "content": { "type": "string", "format": "byte" } }, "example": { "filename": "musterbrief.pdf", "content": "" } }, "User": { "description": "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).", "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 €).", "type": "string", "enum": [ "EUROCENT" ] }, "Address": { "description": "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.", "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).", "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.", "type": "string" } } }, "Action": { "description": "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", "type": "integer", "format": "int32" }, "text": { "type": "string" } }, "example": { "code": 1, "text": "is sent" } } } }