invowerk Rendering API

openapi: 3.2.0
info:
  title: invowerk Rendering API
  description: 'German e-invoices: create ZUGFeRD PDFs and XRechnung, check ZUGFeRD/Factur-X, XRechnung (KoSIT) and Peppol BIS. Free tool, API, MCP.


    Base URL: `https://api.invowerk.dev`.


    ### Authentication

    Send your key in the `X-API-Key` header. Calls without a key run anonymously at

    a lower rate limit per IP address.


    ### Rate limits

    Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and

    `X-RateLimit-Reset` (seconds until the window resets). Over-budget calls return

    `429` with a `Retry-After` header. Check your live budget at `GET /v1/me`.


    ### Pagination

    List endpoints return a keyset envelope: `{"items": [...], "next_cursor": "..."}`.

    Pass `next_cursor` back as the `?cursor=` query param for the next page; it is

    `null` on the last page.


    ### Errors

    Errors are RFC 9457 `problem+json` with a

    stable machine-readable **`code`** (e.g. `rate_limited`, `credits_exhausted`,

    `validation_error`). Branch on `code`. The `title` and `detail` text may change.


    ### Quickstart

    ```sh

    curl -H "X-API-Key: $API_KEY" https://api.invowerk.dev/v1/me

    ```'
  version: '1'
servers:
- url: https://api.invowerk.dev
tags:
- name: Rendering
paths:
  /v1/render:
    post:
      tags:
      - Rendering
      summary: Render an e-invoice as HTML
      description: 'Render an XML e-invoice as a readable HTML page.


        Send an XML invoice (UBL or CII, e.g. XRechnung) as the raw request body or as

        a multipart `file` part. PDFs are not accepted. invowerk renders it with the

        KoSIT XRechnung visualization and answers with `text/html`; `?format=json`

        returns `{html, lang, flavor, syntax}` instead. `lang` sets the label language

        (`de` or `en`; otherwise `Accept-Language`, then `de`). Errors: 400 for an

        empty body, 415 for a file that is not an XML invoice, 422 for malformed XML or

        a DOCTYPE, 413 for more than 100,000 elements, 429 when every render slot is

        busy (callers without an API key share one), 504 when the render ran longer

        than 20 s. Costs 1 credit.


        **Credits:** 1 per call.'
      operationId: render_invoice
      security:
      - APIKeyHeader: []
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Label language, ''de'' or ''en''. Default: Accept-Language, then ''de''.'
          title: Lang
        description: 'Label language, ''de'' or ''en''. Default: Accept-Language, then ''de''.'
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: '''json'' returns {html, lang, flavor, syntax}; omitted returns raw text/html.'
          title: Format
        description: '''json'' returns {html, lang, flavor, syntax}; omitted returns raw text/html.'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_render_invoice'
          application/xml:
            schema:
              type: string
      responses:
        '200':
          description: The rendered HTML (default) or the JSON object (?format=json).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderResponse'
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-connector:
        kind: action
        sample_file: /app-static/demo/beispiel-xrechnung.xml
      x-credits-cost: 1
components:
  schemas:
    Problem:
      description: The RFC 9457 error body. Every error response uses it.
      properties:
        type:
          default: about:blank
          description: Problem type URI (RFC 9457).
          title: Type
          type: string
        title:
          description: Short human-readable summary of the status.
          title: Title
          type: string
        status:
          description: The HTTP status code, repeated in the body.
          title: Status
          type: integer
        detail:
          description: What went wrong with this request.
          title: Detail
          type: string
        instance:
          description: The request path that produced the error.
          title: Instance
          type: string
        code:
          description: Stable machine-readable error code. Branch on this, not on the text.
          title: Code
          type: string
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Correlation id for this request; quote it when asking for support.
          title: Request Id
        errors:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          default: null
          description: Per-field validation failures. Present on 422 only.
          title: Errors
        upgrade_url:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Where to add credits or move to a larger plan. Present on 402/403/429.
          title: Upgrade Url
      required:
      - title
      - status
      - detail
      - instance
      - code
      title: Problem
      type: object
    RenderResponse:
      properties:
        html:
          type: string
          title: Html
          description: The rendered invoice as a complete HTML document.
        lang:
          type: string
          title: Lang
          description: 'The label language used: ''de'' or ''en''.'
        flavor:
          type: string
          title: Flavor
          description: The detected rule set, e.g. 'xrechnung', 'peppol_bis' or 'unknown'.
        syntax:
          type: string
          title: Syntax
          description: The detected XML syntax, e.g. 'ubl_invoice' or 'cii'.
      type: object
      required:
      - html
      - lang
      - flavor
      - syntax
      title: RenderResponse
      description: 'The answer of POST /v1/render?format=json: the HTML and what invowerk detected.'
    Body_render_invoice:
      properties:
        file:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: File
          description: The invoice XML as a multipart file part.
      type: object
      title: Body_render_invoice
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key