> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywise.de/llms.txt > Use this file to discover all available pages before exploring further. # Attach the invoice PDF > 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). ## OpenAPI ````yaml /api-docs/mahnservice-api/openapi.json post /mahnservice/v1/invoices/{uuid}/documents/ openapi: 3.0.3 info: 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. Authentication 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. Resources: 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. Contract: 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 a per-operation window of 120 writes per minute; a `429` carries `Retry-After`. title: paywise Mahnservice API version: v1 servers: - description: Production environment url: https://api.paywise.de security: [] tags: - description: The authenticated credential and its context. name: Info - description: Debtors invoices are addressed to. name: Debtors - description: Held invoices, their release, payments and documents. name: Invoices - description: Dunning flow configurations referenced by invoices. name: Dunning flows externalDocs: url: https://docs.paywise.de/api-docs/mahnservice-api/introduction paths: /mahnservice/v1/invoices/{uuid}/documents/: post: tags: - Invoices summary: Attach the invoice PDF 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). operationId: create-invoice-document parameters: - description: UUID of the invoice in this request. in: path name: uuid required: true schema: format: uuid type: string requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/DocumentCreateRequest' description: >- A JSON body carries the document as base64 content; the file part is accepted only with multipart/form-data. not: required: - file multipart/form-data: schema: $ref: '#/components/schemas/DocumentCreateRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/DocumentRead' description: '' headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: '' headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '429': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: 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: minimum: 1 type: integer X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: 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-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string security: - tokenAuth: [] components: schemas: DocumentCreateRequest: anyOf: - not: anyOf: - required: - file - required: - url required: - base64 title: Base64 document - not: anyOf: - required: - base64 - required: - url required: - file title: Multipart file description: >- Exactly one of `file` (multipart) or `base64`. PDF only. A document is only ever the bytes the client itself transmits. `url` is rejected as an unknown field rather than silently ignored, and the error never echoes the value back -- a presigned source URL carries credentials in its query string. properties: base64: 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. maxLength: 15029589 minLength: 1 type: string file: 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. format: binary type: string filename: description: >- Optional filename override. Defaults to the uploaded file's name for multipart or document.pdf for base64. maxLength: 255 minLength: 1 type: string type: object DocumentRead: description: Read shape of an invoice document. properties: created_at: description: >- Creation time of the stable document resource; unchanged when its contents are replaced. format: date-time readOnly: true type: string download_url: description: >- Authenticated API URL for downloading the invoice PDF; null unless the document is ready. format: uri nullable: true readOnly: true type: string filename: description: Stored document filename, or null when no filename is available. nullable: true readOnly: true type: string id: description: Stable identifier of the invoice document. format: uuid readOnly: true type: string mime_type: description: >- Document media type (application/pdf for an accepted PDF), or null when unavailable. nullable: true readOnly: true type: string size: description: >- Document size in bytes. Null before ready, and may remain null if the size of a legacy document cannot be retrieved. nullable: true readOnly: true type: integer status: allOf: - $ref: '#/components/schemas/CaseDocumentStatusEnum' 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. readOnly: true updated_at: description: Time at which the document was last updated. format: date-time readOnly: true type: string required: - created_at - download_url - filename - id - mime_type - size - status - updated_at type: object Error: properties: code: description: Machine-readable error category. type: string detail: description: Short human-readable summary of the error. type: string errors: description: Field-level validation errors, when applicable. items: $ref: '#/components/schemas/ErrorItem' type: array required: - detail - code type: object CaseDocumentStatusEnum: description: |- * `pending` - pending * `ready` - ready * `rejected` - rejected * `failed` - failed enum: - pending - ready - rejected - failed type: string ErrorItem: properties: code: description: Machine-readable field error code. type: string field: 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. nullable: true type: string message: description: Human-readable explanation of the field error. type: string required: - field - code - message type: object securitySchemes: tokenAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.