{ "openapi": "3.0.3", "info": { "title": "paywise Mahnservice API", "version": "v1", "description": "Public REST API for the paywise Mahnservice (pre-collection dunning), an alternative input path to the bookkeeping integrations (Lexware Office, sevDesk) and the CSV import.\n\nAuthentication uses a Bearer token (the same token works for the Inkasso API). Each token is bound to a company and a legacy access mode: `test` or `production`. Access mode is a data-isolation lane, not the API environment: modern credentials use `production` in both production and sandbox. Read `/info/`'s `environment` (`production` or `sandbox`) to identify the environment serving your request.\n\nResources: token introspection (`/info/`), debtors (create/list/get), and the invoice lifecycle -- submit (held), upload the invoice PDF (multipart or base64; scanned asynchronously, poll the document `status`), release for dunning, report payments, cancel / write off, and read the dunning state (`dunning_state`, the dunning flow and the sent dunnings with their fees), pause and resume the dunning, and read the dunning-flow configuration (`/dunning-flows/`). Webhooks notify you about `invoice.created`, `invoice.paid`, `invoice.cancelled`, `invoice.written_off`, `dunning.level_advanced` and `dunning.handed_to_collection`. Test-mode invoices are visible everywhere but never dunned, and their events only reach test-mode endpoints.\n\nContract: requests are JSON only (documents may also be multipart); unknown or read-only body fields and unknown query parameters are rejected with `400`; list pages take `limit` (1-100, default 10) and `offset`. Errors are English and machine-readable: every error body is `{detail, code[, errors]}` -- branch on `code` (`validation_error` with per-field `errors`, `not_authenticated`, `permission_denied` -- the token lacks the scope, `subscription_required` -- no active Mahnservice subscription (writes other than payment reporting), `company_locked` -- the account is locked by paywise (every write), `not_found`, `unsupported_media_type`, `request_too_large`, `throttled`, `unexpected_body`, and the documented `409` codes). A repeat submission of an invoice number that was cancelled, written off or archived is a `409` (`invoice_cancelled` / `invoice_written_off` / `invoice_archived`), not a replay. `HEAD` mirrors `GET` and never writes. Every response carries `X-Paywise-Request-Id`, `X-Paywise-Environment` and `Cache-Control: private, no-store`. Token scopes apply: `mahnservice:debtors:read` / `:write` and `mahnservice:invoices:read` / `:write` (a `:write` grant includes `:read`; keys minted with the full `*` grant have everything). Rate limits: 600 requests per minute per key and per company, shared with the Case Management API, plus per-operation windows of 600 reads or 120 writes per minute; a `429` carries `Retry-After`." }, "paths": { "/mahnservice/v1/debtors/": { "get": { "operationId": "list-debtors", "description": "Lists debtors in the token's company and access mode. Optional customer_number (exact, case-sensitive) and email (exact, case-insensitive primary email) filters combine with AND. The response stays paginated and may contain multiple matches. Blank or invalid filters return 400 with field errors.", "summary": "List debtors", "parameters": [ { "in": "query", "name": "customer_number", "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "Exact, case-sensitive customer number. A blank value is invalid." }, { "in": "query", "name": "email", "schema": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "description": "Exact, case-insensitive match on the current primary email shown in the debtor response. A blank or malformed value is invalid." }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page; defaults to 10.", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "offset", "required": false, "in": "query", "description": "Zero-based index of the first result; defaults to 0.", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "tags": [ "Debtors" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDebtorList" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:debtors:read" ] }, "post": { "operationId": "create-debtor", "description": "Creates a new debtor on every call; this operation is not idempotent. Store the returned UUID for reuse. List debtors with customer_number and/or email to find existing matches first; neither field is unique and lookup does not prevent concurrent duplicate creates.", "summary": "Create a debtor", "tags": [ "Debtors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebtorRequest" } } }, "required": true }, "security": [ { "tokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Debtor" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:debtors:write" ], "parameters": [] } }, "/mahnservice/v1/debtors/{uuid}/": { "get": { "operationId": "get-debtor", "description": "The debtors of your Mahnservice account.\n\nCreating a debtor requires an active subscription; list and retrieve\nstay available through a subscription lapse. All scoped to the token's\ncompany and access mode.", "summary": "Get a debtor", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the debtor in this request." } ], "tags": [ "Debtors" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Debtor" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:debtors:read" ] } }, "/mahnservice/v1/dunning-flows/": { "get": { "operationId": "list-dunning-flows", "description": "Includes historical versions referenced by existing invoices. The current is_default configuration sorts first. is_active is a kill switch, not a latest-version indicator.", "summary": "List dunning flows", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page; defaults to 10.", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "offset", "required": false, "in": "query", "description": "Zero-based index of the first result; defaults to 0.", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "tags": [ "Dunning flows" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDunningFlowList" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] } }, "/mahnservice/v1/dunning-flows/{uuid}/": { "get": { "operationId": "get-dunning-flow", "description": "Read-only dunning-flow (Mahnlauf) configuration. Flows are company\nconfig with no test/production split, so both token modes read the same\nflows; configuration itself stays in the paywise portal (design D-portal:\nthe public API keeps flows read-only).", "summary": "Get a dunning flow", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the dunning flow in this request." } ], "tags": [ "Dunning flows" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningFlow" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] } }, "/mahnservice/v1/info/": { "get": { "operationId": "get-token-info", "description": "Returns the company, the API environment (production/sandbox), and the bearer token's legacy access mode. Use environment to identify the sandbox: modern credentials use access_mode production in both environments.", "summary": "Get token info", "tags": [ "Info" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInfo" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-required-scopes": [], "parameters": [] } }, "/mahnservice/v1/invoices/": { "get": { "operationId": "list-invoices", "description": "Invoices for the public Mahnservice API: the full lifecycle.\n\nSubmit creates a *held* invoice -- no dunning process exists until\n/release creates one. Release enrolls the invoice into the dunning flow\n(active when the company's Mahnlauf is activated, pending until then;\nparked paused under company or debtor holds). PATCH corrects an invoice\nwhile it is still held -- the only correction window there is, because\nsubmit is idempotent on the invoice number and ignores changed fields,\nand after release the dunning history already references the amount and\nthe due date. Payments, cancel and write-off settle or end the claim.\nAll scoped to the token's company; the debtor is referenced by UUID.\n\nWrite actions apply only to API-submitted invoices; bookkeeping-synced\ninvoices are readable here but owned by their bookkeeping system. Payment\nreporting stays open through a subscription lapse -- a lapsed customer\nmust still be able to stop dunning on a paid invoice.", "summary": "List invoices", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page; defaults to 10.", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "offset", "required": false, "in": "query", "description": "Zero-based index of the first result; defaults to 0.", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedInvoiceList" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] }, "post": { "operationId": "create-invoice", "description": "Idempotent on invoice_number (per company + access mode). A repeat submission returns 200 with the EXISTING invoice and does NOT apply any changed fields; a genuinely new invoice returns 201. To correct a submitted invoice, PATCH it while it is still held -- do not invent a second invoice_number for it. The invoice PDF is attached separately (POST .../documents/); release waits until a supplied document reaches ready. 409 (codes: invoice_cancelled, invoice_written_off, invoice_archived) when the number belongs to an invoice that was cancelled, written off or archived: such a row takes no correction any more -- submit the corrected invoice under a new invoice number.", "summary": "Submit an invoice", "tags": [ "Invoices" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } }, "required": true }, "security": [ { "tokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "held": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "held", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-02T08:00:00Z" }, "summary": "Submitted; awaiting explicit release" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "held": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "held", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-02T08:00:00Z" }, "summary": "Submitted; awaiting explicit release" }, "active": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "active", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Released; dunning process active" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ], "parameters": [] } }, "/mahnservice/v1/invoices/{uuid}/": { "get": { "operationId": "get-invoice", "description": "Invoices for the public Mahnservice API: the full lifecycle.\n\nSubmit creates a *held* invoice -- no dunning process exists until\n/release creates one. Release enrolls the invoice into the dunning flow\n(active when the company's Mahnlauf is activated, pending until then;\nparked paused under company or debtor holds). PATCH corrects an invoice\nwhile it is still held -- the only correction window there is, because\nsubmit is idempotent on the invoice number and ignores changed fields,\nand after release the dunning history already references the amount and\nthe due date. Payments, cancel and write-off settle or end the claim.\nAll scoped to the token's company; the debtor is referenced by UUID.\n\nWrite actions apply only to API-submitted invoices; bookkeeping-synced\ninvoices are readable here but owned by their bookkeeping system. Payment\nreporting stays open through a subscription lapse -- a lapsed customer\nmust still be able to stop dunning on a paid invoice.", "summary": "Get an invoice", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "held": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "held", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-02T08:00:00Z" }, "summary": "Submitted; awaiting explicit release" }, "pending": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "pending", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Released; awaiting dunning-flow activation" }, "active": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "active", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Released; dunning process active" }, "paused": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "paused", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Dunning process paused" }, "completed": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "completed", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Dunning ladder completed with an outstanding balance" }, "paid": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "paid", "archived": false, "has_document": false, "document": null, "balance": "0.00", "paid_amount": "250.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Fully paid" }, "cancelled": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "cancelled", "archived": false, "has_document": false, "document": null, "balance": "0.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Cancelled" }, "written_off": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "written_off", "archived": false, "has_document": false, "document": null, "balance": "0.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Written off" }, "inkasso": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "inkasso", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Covered by debt collection" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] }, "patch": { "operationId": "correct-invoice", "description": "Corrects a still-held invoice (submitted, not yet released). Submit is idempotent and ignores changed fields, so this is the only way to fix a typo without inventing a second invoice_number for a number that belongs to the client's own accounting system. Partial: only the fields present in the body change. Writable are invoice_number, amount, currency, due_date, document_date, your_reference and debtor; company and access_mode come from the token and are never writable, and the lifecycle fields (dunning_state, archived, has_document, balance) change only through their own endpoints. Renaming invoice_number moves the idempotency key with it, so a later submit of the OLD number creates a new invoice. A corrected due_date re-derives the open/overdue status. The invoice PDF is replaced through POST .../documents/, which is held-only for the same reason. 409 (codes: already_released -- nothing is correctable once dunning has started, cancel it and submit a corrected invoice instead; invoice_archived; invoice_paid / invoice_cancelled / invoice_written_off; duplicate_invoice_number; not_api_invoice).", "summary": "Correct a held invoice", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedInvoiceRequest" } } } }, "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "held": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "held", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-02T08:00:00Z" }, "summary": "Submitted; awaiting explicit release" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/cancel/": { "post": { "operationId": "cancel-invoice", "description": "Marks the invoice cancelled and stops its dunning process. Idempotent; 409 (codes: invoice_paid, invoice_written_off, invoice_in_inkasso -- the invoice was handed to debt collection, contact support to retract it; not_api_invoice) when the invoice is already settled otherwise, at debt collection, or belongs to a bookkeeping integration.", "summary": "Cancel an invoice (Storno)", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "cancelled": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "cancelled", "archived": false, "has_document": false, "document": null, "balance": "0.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Cancelled" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/documents/": { "get": { "operationId": "list-invoice-documents", "description": "The document attached to this invoice (at most one), with its ingestion status: pending (scanning), ready, rejected (malware scan) or failed (the scan could not complete or the content was invalid/oversized). size and download_url are null unless ready.", "summary": "List the invoice documents", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentRead" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] }, "post": { "operationId": "create-invoice-document", "description": "Exactly one of multipart file or JSON {\"base64\"}. PDF only, 10 MB. Replaces the current document while the invoice is held; the response is the pending document. Re-post to replace a rejected or failed document. 409 (codes: already_released after release; invoice_paid / invoice_cancelled / invoice_written_off; invoice_in_inkasso; invoice_archived; not_api_invoice).", "summary": "Attach the invoice PDF", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DocumentCreateRequest" } }, "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DocumentCreateRequest" } ], "not": { "required": [ "file" ] }, "description": "A JSON body carries the document as base64 content; the file part is accepted only with multipart/form-data." } } }, "required": true }, "security": [ { "tokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/documents/{document_uuid}/": { "get": { "operationId": "get-invoice-document", "description": "Poll this to track ingestion: status moves pending -> ready, or to rejected on malware detection, or to failed when the scan could not complete or the content was invalid/oversized. A rejected or failed document is replaced by posting new bytes to .../documents/.", "summary": "Get an invoice document", "parameters": [ { "in": "path", "name": "document_uuid", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true, "description": "UUID of the invoice document in this request." }, { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] } }, "/mahnservice/v1/invoices/{uuid}/documents/{document_uuid}/download/": { "get": { "operationId": "download-invoice-document", "description": "Returns the scanned PDF bytes while the document is ready; 404 otherwise. Never cached (private, no-store).", "summary": "Download the invoice document", "parameters": [ { "in": "path", "name": "document_uuid", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true, "description": "UUID of the invoice document in this request." }, { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] } }, "/mahnservice/v1/invoices/{uuid}/dunning/": { "get": { "operationId": "get-invoice-dunning", "description": "The dunning process of this invoice: state (held until release), pause state, current level, next action date, the dunning flow, and the history of sent dunnings with their fees.", "summary": "Get the dunning state", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningState" }, "examples": { "held": { "value": { "state": "held", "pause_reason": null, "paused_at": null, "current_level": null, "next_action_date": null, "dunning_flow": null, "dunnings": [] }, "summary": "Submitted; awaiting explicit release" }, "active": { "value": { "state": "active", "pause_reason": null, "paused_at": null, "current_level": 1, "next_action_date": "2026-09-04T00:00:00+02:00", "dunning_flow": { "id": "73000000-0000-4000-8000-000000000001", "name": "Standard reminders", "levels": 3, "level_count": 3 }, "dunnings": [] }, "summary": "Released; dunning process active" }, "pending": { "value": { "state": "pending", "pause_reason": null, "paused_at": null, "current_level": 1, "next_action_date": "2026-09-04T00:00:00+02:00", "dunning_flow": { "id": "73000000-0000-4000-8000-000000000001", "name": "Standard reminders", "levels": 3, "level_count": 3 }, "dunnings": [] }, "summary": "Released; awaiting dunning-flow activation" }, "paused": { "value": { "state": "paused", "pause_reason": "user", "paused_at": "2026-09-03T09:00:00Z", "current_level": 1, "next_action_date": "2026-09-04T00:00:00+02:00", "dunning_flow": { "id": "73000000-0000-4000-8000-000000000001", "name": "Standard reminders", "levels": 3, "level_count": 3 }, "dunnings": [] }, "summary": "Dunning process paused" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] } }, "/mahnservice/v1/invoices/{uuid}/dunning/pause/": { "post": { "operationId": "pause-dunning", "description": "Pauses dunning for this invoice (pause_reason \"user\"). Idempotent on a repeat. 409 (codes: not_released, invoice_in_inkasso, already_paused -- paused under a different hold, invalid_status, invoice_paid / invoice_cancelled / invoice_written_off, not_api_invoice) when there is no dunning process yet or it is paused otherwise, settled or at debt collection.", "summary": "Pause the dunning process", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningState" }, "examples": { "paused": { "value": { "state": "paused", "pause_reason": "user", "paused_at": "2026-09-03T09:00:00Z", "current_level": 1, "next_action_date": "2026-09-04T00:00:00+02:00", "dunning_flow": { "id": "73000000-0000-4000-8000-000000000001", "name": "Standard reminders", "levels": 3, "level_count": 3 }, "dunnings": [] }, "summary": "Dunning process paused" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/dunning/resume/": { "post": { "operationId": "resume-dunning", "description": "Resumes a paused dunning process: back to ACTIVE once the company's Mahnlauf is activated, PENDING until then. A company-wide hold (dunning paused for the whole company by you or by paywise) outranks the per-invoice resume. 409 (codes: not_released, not_paused, company_paused, invoice_in_inkasso, complaint_requires_letter, stripe_connection_revoked, invoice_paid / invoice_cancelled / invoice_written_off, not_api_invoice).", "summary": "Resume the dunning process", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningState" }, "examples": { "active": { "value": { "state": "active", "pause_reason": null, "paused_at": null, "current_level": 1, "next_action_date": "2026-09-04T00:00:00+02:00", "dunning_flow": { "id": "73000000-0000-4000-8000-000000000001", "name": "Standard reminders", "levels": 3, "level_count": 3 }, "dunnings": [] }, "summary": "Released; dunning process active" }, "pending": { "value": { "state": "pending", "pause_reason": null, "paused_at": null, "current_level": 1, "next_action_date": "2026-09-04T00:00:00+02:00", "dunning_flow": { "id": "73000000-0000-4000-8000-000000000001", "name": "Standard reminders", "levels": 3, "level_count": 3 }, "dunnings": [] }, "summary": "Released; awaiting dunning-flow activation" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/payments/": { "get": { "operationId": "list-invoice-payments", "description": "All payments of this invoice, newest value date first (unpaginated).", "summary": "List reported payments", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:read" ] }, "post": { "operationId": "report-payment", "description": "Reports a payment. A partial payment reduces the balance while dunning continues over the full amount; once the reported total covers the invoice amount, the invoice is marked paid and dunning stops (except at dunning_state \"inkasso\": the payment is recorded but the state is owned by the debt-collection side). Retry-safe: an identical repeat (same amount, value_date and non-empty reference) returns 200 with the existing payment instead of double-counting. 409 (codes: duplicate_payment -- identical payment WITHOUT a reference already exists, add a distinct reference to record a genuine second payment; invoice_cancelled; invoice_written_off; not_api_invoice). Open through a subscription lapse, refused (403 company_locked) while the account is locked by paywise.", "summary": "Report a payment", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } }, "required": true }, "security": [ { "tokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/release/": { "post": { "operationId": "release-invoice", "description": "Creates the dunning process for a held invoice (the second step of the two-step submission). The process starts ACTIVE when the company's Mahnlauf is activated, PENDING until then, and is parked PAUSED under a company- or debtor-level pause. Releasing an already-released invoice is a no-op returning the current state. When the invoice is already covered by a debt-collection case, the process is created directly in dunning_state \"inkasso\" (200). 409 (codes: invoice_archived, invoice_settled, no_default_dunning_flow, not_api_invoice, document_not_ready) when ingestion/scanning is incomplete, the invoice is archived/settled, no default dunning flow is configured, or the invoice belongs to a bookkeeping integration.", "summary": "Release a held invoice for dunning", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "pending": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "pending", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Released; awaiting dunning-flow activation" }, "active": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "active", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Released; dunning process active" }, "paused": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "paused", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Dunning process paused" }, "inkasso": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "inkasso", "archived": false, "has_document": false, "document": null, "balance": "250.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Covered by debt collection" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } }, "/mahnservice/v1/invoices/{uuid}/write-off/": { "post": { "operationId": "write-off-invoice", "description": "Marks the claim written off and stops its dunning process. Idempotent; 409 (codes: invoice_paid, invoice_cancelled, invoice_in_inkasso -- the invoice was handed to debt collection, contact support to retract it; not_api_invoice) when the invoice is already settled otherwise, at debt collection, or belongs to a bookkeeping integration.", "summary": "Write off an invoice (Ausbuchung)", "parameters": [ { "in": "path", "name": "uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID of the invoice in this request." } ], "tags": [ "Invoices" ], "security": [ { "tokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "written_off": { "value": { "id": "71000000-0000-4000-8000-000000000001", "invoice_number": "INV-2026-1042", "amount": "250.00", "currency": "EUR", "due_date": "2026-09-01", "document_date": "2026-08-18", "your_reference": "CUSTOMER-1042", "debtor": "72000000-0000-4000-8000-000000000001", "access_mode": "production", "dunning_state": "written_off", "archived": false, "has_document": false, "document": null, "balance": "0.00", "paid_amount": "0.00", "overpaid": false, "created": "2026-09-02T08:00:00Z", "updated": "2026-09-03T09:00:00Z" }, "summary": "Written off" } } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "", "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "500": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "401": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "403": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "429": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Integer seconds to wait before retrying a throttled request.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } }, "404": { "description": "Standard error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Paywise-Request-Id": { "description": "Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored.", "schema": { "type": "string", "format": "uuid" } }, "X-Paywise-Environment": { "description": "Environment that produced the response.", "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, "Cache-Control": { "description": "Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "mahnservice:invoices:write" ] } } }, "components": { "schemas": { "AccessModeEnum": { "enum": [ "test", "production" ], "type": "string", "description": "* `test` - Test\n* `production` - Production" }, "CaseDocumentStatusEnum": { "enum": [ "pending", "ready", "rejected", "failed" ], "type": "string", "description": "* `pending` - pending\n* `ready` - ready\n* `rejected` - rejected\n* `failed` - failed" }, "ChannelEnum": { "enum": [ "email", "letter", "both" ], "type": "string", "description": "* `email` - E-Mail\n* `letter` - Brief\n* `both` - E-Mail & Brief" }, "CountryEnum": { "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "UM", "US", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "* `AF` - AF\n* `AX` - AX\n* `AL` - AL\n* `DZ` - DZ\n* `AS` - AS\n* `AD` - AD\n* `AO` - AO\n* `AI` - AI\n* `AQ` - AQ\n* `AG` - AG\n* `AR` - AR\n* `AM` - AM\n* `AW` - AW\n* `AU` - AU\n* `AT` - AT\n* `AZ` - AZ\n* `BS` - BS\n* `BH` - BH\n* `BD` - BD\n* `BB` - BB\n* `BY` - BY\n* `BE` - BE\n* `BZ` - BZ\n* `BJ` - BJ\n* `BM` - BM\n* `BT` - BT\n* `BO` - BO\n* `BQ` - BQ\n* `BA` - BA\n* `BW` - BW\n* `BV` - BV\n* `BR` - BR\n* `IO` - IO\n* `BN` - BN\n* `BG` - BG\n* `BF` - BF\n* `BI` - BI\n* `CV` - CV\n* `KH` - KH\n* `CM` - CM\n* `CA` - CA\n* `KY` - KY\n* `CF` - CF\n* `TD` - TD\n* `CL` - CL\n* `CN` - CN\n* `CX` - CX\n* `CC` - CC\n* `CO` - CO\n* `KM` - KM\n* `CG` - CG\n* `CD` - CD\n* `CK` - CK\n* `CR` - CR\n* `CI` - CI\n* `HR` - HR\n* `CU` - CU\n* `CW` - CW\n* `CY` - CY\n* `CZ` - CZ\n* `DK` - DK\n* `DJ` - DJ\n* `DM` - DM\n* `DO` - DO\n* `EC` - EC\n* `EG` - EG\n* `SV` - SV\n* `GQ` - GQ\n* `ER` - ER\n* `EE` - EE\n* `SZ` - SZ\n* `ET` - ET\n* `FK` - FK\n* `FO` - FO\n* `FJ` - FJ\n* `FI` - FI\n* `FR` - FR\n* `GF` - GF\n* `PF` - PF\n* `TF` - TF\n* `GA` - GA\n* `GM` - GM\n* `GE` - GE\n* `DE` - DE\n* `GH` - GH\n* `GI` - GI\n* `GR` - GR\n* `GL` - GL\n* `GD` - GD\n* `GP` - GP\n* `GU` - GU\n* `GT` - GT\n* `GG` - GG\n* `GN` - GN\n* `GW` - GW\n* `GY` - GY\n* `HT` - HT\n* `HM` - HM\n* `VA` - VA\n* `HN` - HN\n* `HK` - HK\n* `HU` - HU\n* `IS` - IS\n* `IN` - IN\n* `ID` - ID\n* `IR` - IR\n* `IQ` - IQ\n* `IE` - IE\n* `IM` - IM\n* `IL` - IL\n* `IT` - IT\n* `JM` - JM\n* `JP` - JP\n* `JE` - JE\n* `JO` - JO\n* `KZ` - KZ\n* `KE` - KE\n* `KI` - KI\n* `KW` - KW\n* `KG` - KG\n* `LA` - LA\n* `LV` - LV\n* `LB` - LB\n* `LS` - LS\n* `LR` - LR\n* `LY` - LY\n* `LI` - LI\n* `LT` - LT\n* `LU` - LU\n* `MO` - MO\n* `MG` - MG\n* `MW` - MW\n* `MY` - MY\n* `MV` - MV\n* `ML` - ML\n* `MT` - MT\n* `MH` - MH\n* `MQ` - MQ\n* `MR` - MR\n* `MU` - MU\n* `YT` - YT\n* `MX` - MX\n* `FM` - FM\n* `MD` - MD\n* `MC` - MC\n* `MN` - MN\n* `ME` - ME\n* `MS` - MS\n* `MA` - MA\n* `MZ` - MZ\n* `MM` - MM\n* `NA` - NA\n* `NR` - NR\n* `NP` - NP\n* `NL` - NL\n* `NC` - NC\n* `NZ` - NZ\n* `NI` - NI\n* `NE` - NE\n* `NG` - NG\n* `NU` - NU\n* `NF` - NF\n* `KP` - KP\n* `MK` - MK\n* `MP` - MP\n* `NO` - NO\n* `OM` - OM\n* `PK` - PK\n* `PW` - PW\n* `PS` - PS\n* `PA` - PA\n* `PG` - PG\n* `PY` - PY\n* `PE` - PE\n* `PH` - PH\n* `PN` - PN\n* `PL` - PL\n* `PT` - PT\n* `PR` - PR\n* `QA` - QA\n* `RE` - RE\n* `RO` - RO\n* `RU` - RU\n* `RW` - RW\n* `BL` - BL\n* `SH` - SH\n* `KN` - KN\n* `LC` - LC\n* `MF` - MF\n* `PM` - PM\n* `VC` - VC\n* `WS` - WS\n* `SM` - SM\n* `ST` - ST\n* `SA` - SA\n* `SN` - SN\n* `RS` - RS\n* `SC` - SC\n* `SL` - SL\n* `SG` - SG\n* `SX` - SX\n* `SK` - SK\n* `SI` - SI\n* `SB` - SB\n* `SO` - SO\n* `ZA` - ZA\n* `GS` - GS\n* `KR` - KR\n* `SS` - SS\n* `ES` - ES\n* `LK` - LK\n* `SD` - SD\n* `SR` - SR\n* `SJ` - SJ\n* `SE` - SE\n* `CH` - CH\n* `SY` - SY\n* `TW` - TW\n* `TJ` - TJ\n* `TZ` - TZ\n* `TH` - TH\n* `TL` - TL\n* `TG` - TG\n* `TK` - TK\n* `TO` - TO\n* `TT` - TT\n* `TN` - TN\n* `TR` - TR\n* `TM` - TM\n* `TC` - TC\n* `TV` - TV\n* `UG` - UG\n* `UA` - UA\n* `AE` - AE\n* `GB` - GB\n* `UM` - UM\n* `US` - US\n* `UY` - UY\n* `UZ` - UZ\n* `VU` - VU\n* `VE` - VE\n* `VN` - VN\n* `VG` - VG\n* `VI` - VI\n* `WF` - WF\n* `EH` - EH\n* `YE` - YE\n* `ZM` - ZM\n* `ZW` - ZW" }, "CurrencyEnum": { "enum": [ "EUR", "USD", "GBP", "CHF" ], "type": "string", "description": "* `EUR` - EUR\n* `USD` - USD\n* `GBP` - GBP\n* `CHF` - CHF" }, "Debtor": { "type": "object", "description": "A Mahnservice debtor. Create it with a name and an optional email and\naddress; those become the debtor's contact channels for dunning. The\naccess mode and the owning company are taken from the token, never the\npayload, so a legacy test-mode token can only create test debtors.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 255 }, "type": { "allOf": [ { "$ref": "#/components/schemas/TypeEnum" } ], "default": "company", "description": "Whether the debtor is a private person (person) or an organization (company). Defaults to company when omitted during creation." }, "customer_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your customer number for this debtor. Optional and not unique; debtor creation always creates a new record. Use the debtor list customer_number filter to look up existing records." }, "email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254, "description": "Primary email address used for dunning notices. Null when no primary email is recorded." }, "address": { "$ref": "#/components/schemas/DebtorAddress", "description": "Postal address for dunning letters. Missing street, postal code and city values are returned as empty strings." }, "access_mode": { "allOf": [ { "$ref": "#/components/schemas/AccessModeEnum" } ], "readOnly": true, "description": "Legacy data-isolation mode inherited from the creating token. Modern credentials use production in both production and sandbox; this field does not select the API environment." }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "access_mode", "created", "id", "name", "updated" ] }, "DebtorAddress": { "type": "object", "description": "The debtor's postal address (the dunning-letter recipient).", "properties": { "street": { "type": "string", "maxLength": 255 }, "zip_code": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "country": { "allOf": [ { "$ref": "#/components/schemas/CountryEnum" } ], "default": "DE", "description": "Country of the debtor's postal address as a two-letter ISO 3166-1 code (case-insensitive on input, upper-case in responses). Defaults to DE (Germany) when omitted." } }, "required": [ "city", "street", "zip_code" ] }, "DebtorAddressRequest": { "type": "object", "description": "The debtor's postal address (the dunning-letter recipient).", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 255 }, "zip_code": { "type": "string", "minLength": 1, "maxLength": 20 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "allOf": [ { "$ref": "#/components/schemas/CountryEnum" } ], "default": "DE", "description": "Country of the debtor's postal address as a two-letter ISO 3166-1 code (case-insensitive on input, upper-case in responses). Defaults to DE (Germany) when omitted." } }, "required": [ "city", "street", "zip_code" ] }, "DebtorRequest": { "type": "object", "description": "A Mahnservice debtor. Create it with a name and an optional email and\naddress; those become the debtor's contact channels for dunning. The\naccess mode and the owning company are taken from the token, never the\npayload, so a legacy test-mode token can only create test debtors.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "allOf": [ { "$ref": "#/components/schemas/TypeEnum" } ], "default": "company", "description": "Whether the debtor is a private person (person) or an organization (company). Defaults to company when omitted during creation." }, "customer_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your customer number for this debtor. Optional and not unique; debtor creation always creates a new record. Use the debtor list customer_number filter to look up existing records." }, "email": { "type": "string", "format": "email", "nullable": true, "minLength": 1, "maxLength": 254, "description": "Primary email address used for dunning notices. Omit or set null to create the debtor without an email contact." }, "address": { "$ref": "#/components/schemas/DebtorAddressRequest", "description": "Postal address for dunning letters. Optional as a whole; when present, street, zip_code and city are all required." } }, "required": [ "name" ] }, "DocumentCreateRequest": { "type": "object", "description": "Exactly one of `file` (multipart) or `base64`. PDF only.\n\nA document is only ever the bytes the client itself transmits. `url` is\nrejected as an unknown field rather than silently ignored, and the error\nnever echoes the value back -- a presigned source URL carries credentials\nin its query string.", "properties": { "file": { "type": "string", "format": "binary", "description": "Invoice PDF supplied as multipart form-data. Provide exactly one of file or base64. Maximum file size: 10 MiB (10,485,760 bytes); maximum PDF length: 100 pages. Each invoice holds one PDF; uploading again replaces it while the invoice is held. Oversized files are rejected during upload; processing failures appear as status failed." }, "base64": { "type": "string", "minLength": 1, "maxLength": 15029589, "description": "Base64-encoded complete PDF; a data: prefix is accepted. Provide exactly one of base64 or file. Maximum decoded document size: 10 MiB (10,485,760 bytes); maximum PDF length: 100 pages. Each invoice holds one PDF; uploading again replaces it while the invoice is held. Oversized files are rejected during upload; processing failures appear as status failed." }, "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional filename override. Defaults to the uploaded file's name for multipart or document.pdf for base64." } }, "anyOf": [ { "title": "Base64 document", "required": [ "base64" ], "not": { "anyOf": [ { "required": [ "file" ] }, { "required": [ "url" ] } ] } }, { "title": "Multipart file", "required": [ "file" ], "not": { "anyOf": [ { "required": [ "base64" ] }, { "required": [ "url" ] } ] } } ] }, "DocumentRead": { "type": "object", "description": "Read shape of an invoice document.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "filename": { "type": "string", "readOnly": true, "nullable": true, "description": "Stored document filename, or null when no filename is available." }, "mime_type": { "type": "string", "readOnly": true, "nullable": true, "description": "Document media type (application/pdf for an accepted PDF), or null when unavailable." }, "size": { "type": "integer", "readOnly": true, "nullable": true, "description": "Document size in bytes. Null before ready, and may remain null if the size of a legacy document cannot be retrieved." }, "status": { "allOf": [ { "$ref": "#/components/schemas/CaseDocumentStatusEnum" } ], "readOnly": true, "description": "Document ingestion state: pending while processing, ready after acceptance, rejected when content is rejected, or failed when ingestion/scanning cannot complete. Replace a rejected or failed document while the invoice is held to try again." }, "download_url": { "type": "string", "format": "uri", "readOnly": true, "nullable": true, "description": "Authenticated API URL for downloading the invoice PDF; null unless the document is ready." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "Creation time of the stable document resource; unchanged when its contents are replaced." }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "download_url", "filename", "id", "mime_type", "size", "status", "updated_at" ] }, "DocumentSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/CaseDocumentStatusEnum" } ], "readOnly": true, "description": "Document ingestion state: pending while processing, ready after acceptance, rejected when content is rejected, or failed when ingestion/scanning cannot complete. Replace a rejected or failed document while the invoice is held to try again." }, "download_url": { "type": "string", "format": "uri", "readOnly": true, "nullable": true, "description": "Authenticated API URL for downloading the invoice PDF; null unless the document is ready." } }, "required": [ "download_url", "id", "status" ] }, "Dunning": { "type": "object", "description": "One sent (or attempted) dunning notice.", "properties": { "level": { "type": "integer", "readOnly": true, "description": "One-based dunning level for this sent or attempted notice." }, "channel": { "allOf": [ { "$ref": "#/components/schemas/ChannelEnum" } ], "readOnly": true, "description": "Delivery channel for this notice: email, postal letter, or both." }, "state": { "allOf": [ { "$ref": "#/components/schemas/MahnserviceMahnungStatusEnum" } ], "readOnly": true, "description": "Delivery state of this individual notice, separate from the invoice's dunning process state. manual means manual sending is required." }, "sent_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "description": "Time the notice was sent; null if no send time is recorded." }, "error_message": { "type": "string", "readOnly": true, "nullable": true, "description": "Public explanation of the notice's delivery error, or null when no error is recorded." }, "dunning_fee": { "allOf": [ { "$ref": "#/components/schemas/DunningFee" } ], "readOnly": true, "nullable": true, "description": "Fee charged with this notice, recorded at send time; null if no fee was charged. Later flow changes do not change this historical amount." } }, "required": [ "channel", "dunning_fee", "error_message", "level", "sent_at", "state" ] }, "DunningFee": { "type": "object", "description": "The Mahngebühr charged with a sent Mahnung (snapshotted at send time).", "properties": { "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,6}(?:\\.\\d{0,2})?$", "readOnly": true, "description": "Dunning fee in EUR, recorded at send time." }, "charged_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "amount", "charged_at" ] }, "DunningFlow": { "type": "object", "description": "A configured dunning flow (Mahnlauf). `levels` is the ordered level\nconfiguration; `level_count` matches the summary shape embedded in\n`GET /invoices/{uuid}/dunning/`.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "is_default": { "type": "boolean", "readOnly": true, "description": "Current enrollment configuration. Non-default rows include historical versions still referenced by existing invoices; is_active does not identify the latest version." }, "is_activated": { "type": "boolean", "readOnly": true, "description": "Whether sending has been activated for this flow in the paywise portal. Released invoices remain pending until activation, unless another hold applies." }, "is_active": { "type": "boolean", "readOnly": true, "description": "False = the flow was deactivated by paywise (no new enrollments; invoices already running on it continue). Not a deletion." }, "fees_enabled": { "type": "boolean", "readOnly": true, "description": "Master switch for dunning fees. A level's fee is charged only when this and the level's fee_enabled are true." }, "level_count": { "type": "integer", "readOnly": true }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/DunningFlowLevel" }, "readOnly": true, "description": "Dunning-level configurations in level order. Flow configuration is read-only through this API." } }, "required": [ "fees_enabled", "id", "is_activated", "is_active", "is_default", "level_count", "levels", "name" ] }, "DunningFlowLevel": { "type": "object", "description": "One escalation level of a dunning flow.", "properties": { "level": { "type": "integer", "readOnly": true, "description": "One-based position of this level in the dunning flow." }, "days_after_previous": { "type": "integer", "readOnly": true, "description": "Delay in days after the previous level; for level 1, measured from the invoice due date." }, "channel": { "allOf": [ { "$ref": "#/components/schemas/ChannelEnum" } ], "readOnly": true, "description": "Configured delivery channel for this level: email, postal letter, or both." }, "fee_enabled": { "type": "boolean", "readOnly": true, "description": "Whether this level charges a dunning fee; effective only when the flow's fees_enabled is also true." }, "fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,6}(?:\\.\\d{0,2})?$", "readOnly": true, "description": "Configured dunning fee for this level in EUR. Charged only when both the flow and this level enable fees." } }, "required": [ "channel", "days_after_previous", "fee_amount", "fee_enabled", "level" ] }, "DunningFlowSummary": { "type": "object", "description": "The flow the process runs on (summary; the full config lives at\nGET /dunning-flows/). Fixed shape, not a free-form dict, so SDK\ngenerators get real types.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "levels": { "type": "integer", "readOnly": true, "description": "Number of levels (same value as level_count; kept for compatibility)." }, "level_count": { "type": "integer", "readOnly": true } }, "required": [ "id", "level_count", "levels", "name" ] }, "DunningState": { "type": "object", "description": "The dunning state of one invoice: the dunning process plus the history\nof sent notices. A held, never-released invoice reports the held shape\nwith no process.", "properties": { "state": { "allOf": [ { "$ref": "#/components/schemas/MahnserviceDunningStateEnum" } ], "readOnly": true, "nullable": true, "description": "Current dunning process state. held means an API invoice awaits release; an invoice settled while held reports paid, cancelled, or written_off. Null means a bookkeeping invoice has never been enrolled." }, "pause_reason": { "allOf": [ { "$ref": "#/components/schemas/PauseReasonEnum" } ], "readOnly": true, "nullable": true, "description": "Reason recorded for the process hold (manual user pause, subscription, administrator, debtor hold, or disconnected integration); null when no reason is recorded." }, "paused_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "description": "Time the process entered its current pause. Null when not paused, when no process exists, or when a legacy pause has no recorded timestamp." }, "current_level": { "type": "integer", "readOnly": true, "nullable": true, "description": "One-based next dunning level. It can be one beyond the final configured level after the last notice; null when no dunning process exists." }, "next_action_date": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "description": "Scheduled time of the next dunning action, which can be a notice or automatic debt-collection handover. Null when no action is scheduled or no process exists." }, "dunning_flow": { "allOf": [ { "$ref": "#/components/schemas/DunningFlowSummary" } ], "readOnly": true, "nullable": true, "description": "Flow assigned to this invoice's dunning process, which can be an older configuration version. Null when no process or assigned flow exists." }, "dunnings": { "type": "array", "items": { "$ref": "#/components/schemas/Dunning" }, "readOnly": true, "description": "History of sent or attempted dunning notices. Empty when the invoice has no dunning process." } }, "required": [ "current_level", "dunning_flow", "dunnings", "next_action_date", "pause_reason", "paused_at", "state" ] }, "EnvironmentEnum": { "enum": [ "production", "sandbox" ], "type": "string" }, "Invoice": { "type": "object", "description": "A Mahnservice invoice. Created *held*: no dunning process exists until\n`POST /invoices/{uuid}/release/` creates one. The debtor is referenced\nby UUID and must belong to the same company. Company and environment come\nfrom the token, never the payload. Submitting is idempotent on the\ninvoice number.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "invoice_number": { "type": "string", "maxLength": 100, "description": "Your invoice number. POST with the same number within the same company and access mode returns the existing API invoice without applying changed fields. Correct an existing held invoice with PATCH." }, "amount": { "type": "string", "format": "decimal", "pattern": "^[0-9]{1,10}(?:\\.[0-9]{1,2})?$", "description": "Full invoice amount in the invoice currency, expressed in major units (for example 123.45). API submissions must be greater than zero. Partial reported payments reduce balance while dunning continues over this full amount." }, "currency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyEnum" } ], "default": "EUR", "description": "ISO 4217 currency code for the invoice amount and reported balance (EUR, USD, GBP or CHF). Input is normalized to uppercase. Defaults to EUR when omitted during creation. Dunning fees are charged in EUR." }, "due_date": { "type": "string", "format": "date", "description": "Invoice payment due date (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not before document_date). The first dunning level is scheduled using this date plus its configured delay; API invoices must still be explicitly released before dunning." }, "document_date": { "type": "string", "format": "date", "nullable": true, "description": "Issue date of the invoice (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not after due_date), or null if not supplied." }, "your_reference": { "type": "string", "nullable": true, "maxLength": 255, "description": "Optional reference supplied by you for the invoice; this is separate from invoice_number, the submission idempotency key. Blank and null are stored and returned as null." }, "debtor": { "type": "string", "format": "uuid", "description": "ID of a Mahnservice debtor belonging to the authenticated company and the token's access mode. Use the Mahnservice debtors endpoints to create or find it." }, "access_mode": { "allOf": [ { "$ref": "#/components/schemas/AccessModeEnum" } ], "readOnly": true, "description": "Legacy data-isolation mode inherited from the token, not the API host environment. Modern sandbox and production credentials both use production." }, "dunning_state": { "allOf": [ { "$ref": "#/components/schemas/MahnserviceDunningStateEnum" } ], "readOnly": true, "nullable": true, "description": "Current dunning process state. held means an API invoice awaits release; an invoice settled while held reports paid, cancelled, or written_off. Null means a bookkeeping invoice has never been enrolled." }, "archived": { "type": "boolean", "readOnly": true, "description": "Whether the invoice is archived. Archived invoices are not sendable. A held archived invoice cannot be released or corrected; repeating release after a process already exists returns its current state." }, "has_document": { "type": "boolean", "readOnly": true, "description": "Whether a usable invoice PDF is stored. A pending, rejected, or failed upload can have a document object while this flag is false." }, "document": { "allOf": [ { "$ref": "#/components/schemas/DocumentSummary" } ], "readOnly": true, "nullable": true, "description": "Current invoice-document ingestion summary, or null when no document record exists. If present, it must reach ready before the invoice can be released." }, "balance": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,12}(?:\\.\\d{0,2})?$", "readOnly": true, "description": "Remaining invoice amount in the invoice currency: amount minus reported payments, with a minimum of zero. Paid, cancelled and written-off invoices report zero. Dunning fees are not included; partial payments do not reduce the amount used in dunning notices." }, "paid_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,12}(?:\\.\\d{0,2})?$", "readOnly": true, "description": "Sum of all reported payments in the invoice currency. Payments beyond the invoice amount are accepted and counted here; balance never goes below zero." }, "overpaid": { "type": "boolean", "readOnly": true, "description": "True when paid_amount exceeds amount. Over-payment is recorded, not refused; reconcile it in your own system." }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "access_mode", "amount", "archived", "balance", "created", "debtor", "document", "due_date", "dunning_state", "has_document", "id", "invoice_number", "overpaid", "paid_amount", "updated" ] }, "InvoiceRequest": { "type": "object", "description": "A Mahnservice invoice. Created *held*: no dunning process exists until\n`POST /invoices/{uuid}/release/` creates one. The debtor is referenced\nby UUID and must belong to the same company. Company and environment come\nfrom the token, never the payload. Submitting is idempotent on the\ninvoice number.", "properties": { "invoice_number": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Your invoice number. POST with the same number within the same company and access mode returns the existing API invoice without applying changed fields. Correct an existing held invoice with PATCH." }, "amount": { "oneOf": [ { "type": "string", "format": "decimal", "pattern": "^[0-9]{1,10}(?:\\.[0-9]{1,2})?$" }, { "type": "number" } ], "description": "Decimal string (preferred) or JSON number." }, "currency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyEnum" } ], "default": "EUR", "description": "ISO 4217 currency code for the invoice amount and reported balance (EUR, USD, GBP or CHF). Input is normalized to uppercase. Defaults to EUR when omitted during creation. Dunning fees are charged in EUR." }, "due_date": { "type": "string", "format": "date", "description": "Invoice payment due date (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not before document_date). The first dunning level is scheduled using this date plus its configured delay; API invoices must still be explicitly released before dunning." }, "document_date": { "type": "string", "format": "date", "nullable": true, "description": "Issue date of the invoice (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not after due_date), or null if not supplied." }, "your_reference": { "type": "string", "nullable": true, "maxLength": 255, "description": "Optional reference supplied by you for the invoice; this is separate from invoice_number, the submission idempotency key. Blank and null are stored and returned as null." }, "debtor": { "type": "string", "format": "uuid", "description": "ID of a Mahnservice debtor belonging to the authenticated company and the token's access mode. Use the Mahnservice debtors endpoints to create or find it." } }, "required": [ "amount", "debtor", "due_date", "invoice_number" ] }, "MahnserviceDunningStateEnum": { "enum": [ "held", "pending", "active", "paused", "completed", "paid", "cancelled", "written_off", "inkasso" ], "type": "string", "description": "* `held` - Held\n* `pending` - Pending\n* `active` - Aktiv\n* `paused` - Pausiert\n* `completed` - Abgeschlossen\n* `paid` - Paid\n* `cancelled` - Storniert\n* `written_off` - Ausgebucht\n* `inkasso` - An Inkasso übergeben" }, "MahnserviceMahnungStatusEnum": { "enum": [ "pending", "sent", "delivered", "opened", "bounced", "failed", "manual" ], "type": "string", "description": "* `pending` - Pending\n* `sent` - Versendet\n* `delivered` - Zugestellt\n* `opened` - Geöffnet\n* `bounced` - Unzustellbar\n* `failed` - Fehlgeschlagen\n* `manual` - Manuell versenden" }, "PaginatedDebtorList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123, "description": "Total number of matching resources." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100", "description": "URL for the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100", "description": "URL for the previous page, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Debtor" }, "description": "Resources returned for the requested page." } } }, "PaginatedDunningFlowList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123, "description": "Total number of matching resources." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100", "description": "URL for the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100", "description": "URL for the previous page, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DunningFlow" }, "description": "Resources returned for the requested page." } } }, "PaginatedInvoiceList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123, "description": "Total number of matching resources." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100", "description": "URL for the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100", "description": "URL for the previous page, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "description": "Resources returned for the requested page." } } }, "PatchedInvoiceRequest": { "type": "object", "description": "A Mahnservice invoice. Created *held*: no dunning process exists until\n`POST /invoices/{uuid}/release/` creates one. The debtor is referenced\nby UUID and must belong to the same company. Company and environment come\nfrom the token, never the payload. Submitting is idempotent on the\ninvoice number.", "properties": { "invoice_number": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Your invoice number. POST with the same number within the same company and access mode returns the existing API invoice without applying changed fields. PATCH can rename a held invoice and moves this key; a conflicting number returns 409 duplicate_invoice_number. The previous number can then create a new invoice." }, "amount": { "oneOf": [ { "type": "string", "format": "decimal", "pattern": "^[0-9]{1,10}(?:\\.[0-9]{1,2})?$" }, { "type": "number" } ], "description": "Decimal string (preferred) or JSON number." }, "currency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyEnum" } ], "default": "EUR", "description": "ISO 4217 currency code for the invoice amount and reported balance (EUR, USD, GBP or CHF). Input is normalized to uppercase. Omit to keep the current currency; once payments have been reported the currency is fixed (409 payments_reported)." }, "due_date": { "type": "string", "format": "date", "description": "Invoice payment due date (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not before document_date). The first dunning level is scheduled using this date plus its configured delay; API invoices must still be explicitly released before dunning." }, "document_date": { "type": "string", "format": "date", "nullable": true, "description": "Issue date of the invoice, or null if unknown. On PATCH, null clears the date and omission preserves it." }, "your_reference": { "type": "string", "nullable": true, "maxLength": 255, "description": "Optional reference supplied by you for the invoice; this is separate from invoice_number, the submission idempotency key. Omission preserves the reference; null clears it." }, "debtor": { "type": "string", "format": "uuid", "description": "ID of a Mahnservice debtor belonging to the authenticated company and the token's access mode. Use the Mahnservice debtors endpoints to create or find it." } } }, "PauseReasonEnum": { "enum": [ "user", "subscription", "admin", "debtor", "integration" ], "type": "string", "description": "* `user` - Manuell pausiert\n* `subscription` - Abo gekündigt\n* `admin` - Vom Administrator pausiert\n* `debtor` - Schuldner pausiert\n* `integration` - Buchhaltungs-Verbindung getrennt" }, "Payment": { "type": "object", "description": "A payment reported against an invoice. A partial payment reduces the\nbalance while dunning continues over the full amount; once the reported\ntotal covers the amount, the invoice is marked paid and dunning stops.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "amount": { "type": "string", "format": "decimal", "pattern": "^[0-9]{1,10}(?:\\.[0-9]{1,2})?$", "description": "Amount received toward the invoice in its currency, expressed in major units and greater than zero. Partial payments reduce balance; covering the full invoice stops dunning unless it has already been handed to debt collection." }, "value_date": { "type": "string", "format": "date", "description": "Date the payment was received; must not be in the future. Together with amount and reference, it identifies an identical repeated payment report." }, "reference": { "type": "string", "nullable": true, "maxLength": 255, "description": "Optional payment reference. Omitted, blank and null references are treated alike. A repeat with the same invoice, amount, value_date and nonempty reference (compared case-insensitively) returns the existing payment (200). An identical unreferenced payment returns 409 duplicate_payment; use a distinct reference for a genuine second payment." }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "amount", "created", "id", "value_date" ] }, "PaymentRequest": { "type": "object", "description": "A payment reported against an invoice. A partial payment reduces the\nbalance while dunning continues over the full amount; once the reported\ntotal covers the amount, the invoice is marked paid and dunning stops.", "properties": { "amount": { "oneOf": [ { "type": "string", "format": "decimal", "pattern": "^[0-9]{1,10}(?:\\.[0-9]{1,2})?$" }, { "type": "number" } ], "description": "Decimal string (preferred) or JSON number." }, "value_date": { "type": "string", "format": "date", "description": "Date the payment was received; must not be in the future. Together with amount and reference, it identifies an identical repeated payment report." }, "reference": { "type": "string", "nullable": true, "maxLength": 255, "description": "Optional payment reference. Omitted, blank and null references are treated alike. A repeat with the same invoice, amount, value_date and nonempty reference (compared case-insensitively) returns the existing payment (200). An identical unreferenced payment returns 409 duplicate_payment; use a distinct reference for a genuine second payment." } }, "required": [ "amount", "value_date" ] }, "TokenInfo": { "type": "object", "description": "Identifies the company, runtime environment, and legacy data-isolation\nmode. Modern credentials use production access mode in both environments.", "properties": { "id": { "type": "string", "readOnly": true }, "token_name": { "type": "string", "readOnly": true }, "access_mode": { "type": "string", "readOnly": true, "description": "Legacy data-isolation mode, not the API environment. Modern credentials use production in both production and sandbox." }, "environment": { "allOf": [ { "$ref": "#/components/schemas/EnvironmentEnum" } ], "description": "The API environment serving this request: production or sandbox.", "readOnly": true }, "company": { "type": "string", "readOnly": true, "nullable": true, "description": "UUID of the company attached to the calling token, or null when no company is attached." }, "company_name": { "type": "string", "readOnly": true, "nullable": true, "description": "Name of the company attached to the calling token, or null when no company is attached." } }, "required": [ "access_mode", "company", "company_name", "environment", "id", "token_name" ] }, "TypeEnum": { "enum": [ "person", "company" ], "type": "string", "description": "* `person` - Privatperson\n* `company` - Unternehmen" }, "ErrorItem": { "type": "object", "properties": { "field": { "type": "string", "nullable": true, "description": "Path to the field that caused the error, using dots for objects and brackets for list indexes, for example `claims[0].amount`; null for an error without a field path." }, "code": { "type": "string", "description": "Machine-readable field error code." }, "message": { "type": "string", "description": "Human-readable explanation of the field error." } }, "required": [ "field", "code", "message" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "detail": { "type": "string", "description": "Short human-readable summary of the error." }, "code": { "type": "string", "description": "Machine-readable error category." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "description": "Field-level validation errors, when applicable." } }, "required": [ "detail", "code" ], "additionalProperties": false } }, "securitySchemes": { "tokenAuth": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.paywise.de", "description": "Production environment" } ], "externalDocs": { "url": "https://docs.paywise.de/api-docs/mahnservice-api/introduction" }, "tags": [ { "name": "Info", "description": "The authenticated credential and its context." }, { "name": "Debtors", "description": "Debtors invoices are addressed to." }, { "name": "Invoices", "description": "Held invoices, their release, payments and documents." }, { "name": "Dunning flows", "description": "Dunning flow configurations referenced by invoices." } ] }