invowerk Transform API

openapi: 3.2.0
info:
  title: invowerk Transform 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: Transform
paths:
  /v1/parse:
    post:
      tags:
      - Transform
      summary: Read an e-invoice into JSON
      description: 'Read an existing e-invoice into JSON keyed on EN 16931 Business Terms.


        The JSON in `model` is the request body of `POST /v1/generate`, so you can edit

        it and create the invoice again. Send an XML invoice (UBL or CII) or a

        ZUGFeRD / Factur-X PDF as the raw request body or as a multipart file part, at

        most 20 MB. A PDF may have at most 500 pages and 16 attachments. UBL credit

        notes are not supported. The answer also has `detection` (syntax, flavor,

        CustomizationID) and `source` (`xml` or `pdf-embedded`). A file that cannot be

        read returns 422; `detail` starts with an error code. More than 100,000 XML

        elements return 413; 429 means every slot is busy (callers without an API key

        share one), 504 that reading took longer than 20 s. Costs 2 credits.


        **Credits:** 2 per call.'
      operationId: parse_invoice
      requestBody:
        description: 'The invoice: XML (UBL or CII, e.g. XRechnung) or a ZUGFeRD / Factur-X PDF, as the raw body or as a multipart file part. At most 20 MB.'
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  type: string
                  contentMediaType: application/octet-stream
                  description: The invoice file (XML or PDF).
              type: object
              required:
              - file
          application/xml:
            schema:
              type: string
          application/pdf:
            schema:
              type: string
              contentMediaType: application/pdf
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseResponse'
      security:
      - APIKeyHeader: []
      x-connector:
        kind: action
        sample_file: /app-static/demo/beispiel-xrechnung.xml
      x-credits-cost: 2
  /v1/convert:
    post:
      tags:
      - Transform
      summary: Convert an e-invoice between UBL and CII
      description: 'Convert an e-invoice between UBL and CII.


        Send the invoice as for `POST /v1/parse`: XML or a ZUGFeRD / Factur-X PDF, raw

        body or multipart file part, at most 20 MB. `target_syntax` is required (`ubl`

        or `cii`). `target_flavor` (`en16931` or `xrechnung`) is optional; without it

        the flavor of the source is kept. invowerk checks the converted XML before

        answering and never returns an invalid document. The answer is

        `application/xml`; `?format=json` returns `{xml, syntax, flavor,

        self_validation}`. Errors: 422 when the input cannot be read or cannot be

        written in the target form (e.g. XRechnung paid by direct debit: invowerk writes

        only SEPA credit transfer), with an error code at the start of `detail`; 500

        when the converted XML fails the check (the credits are refunded); 413, 429

        and 504 as for `POST /v1/parse`. Costs 3 credits.


        **Credits:** 3 per call.'
      operationId: convert_invoice
      security:
      - APIKeyHeader: []
      parameters:
      - name: target_syntax
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Syntax'
          description: 'The XML syntax to convert to: ''cii'' or ''ubl''.'
        description: 'The XML syntax to convert to: ''cii'' or ''ubl''.'
      - name: target_flavor
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Flavor'
          - type: 'null'
          description: 'Optional rule set of the result: ''en16931'' or ''xrechnung''. Without it the flavor of the source is kept.'
          title: Target Flavor
        description: 'Optional rule set of the result: ''en16931'' or ''xrechnung''. Without it the flavor of the source is kept.'
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: '''json'' returns {xml, syntax, flavor, self_validation}; omitted returns raw application/xml.'
          title: Format
        description: '''json'' returns {xml, syntax, flavor, self_validation}; omitted returns raw application/xml.'
      responses:
        '200':
          description: The converted XML (default) or the JSON object (?format=json).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
            application/xml:
              schema:
                type: string
        '500':
          description: The converted XML failed invowerk's own check. No document is returned and the credits are refunded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      requestBody:
        required: true
        description: 'The invoice: XML (UBL or CII, e.g. XRechnung) or a ZUGFeRD / Factur-X PDF, as the raw body or as a multipart file part. At most 20 MB.'
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  contentMediaType: application/octet-stream
                  description: The invoice file (XML or PDF).
              required:
              - file
          application/xml:
            schema:
              type: string
          application/pdf:
            schema:
              type: string
              contentMediaType: application/pdf
      x-connector:
        kind: action
        sample_file: /app-static/demo/beispiel-xrechnung.xml
      x-credits-cost: 3
components:
  schemas:
    Syntax:
      type: string
      enum:
      - cii
      - ubl
      title: Syntax
      description: 'The XML syntax of the invoice: UBL or CII.'
    ConvertResponse:
      properties:
        xml:
          type: string
          title: Xml
          description: The converted e-invoice as XML.
        syntax:
          type: string
          title: Syntax
          description: 'The syntax of the XML: ''ubl'' or ''cii''.'
        flavor:
          type: string
          title: Flavor
          description: 'The rule set of the XML: ''en16931'' or ''xrechnung''.'
        self_validation:
          $ref: '#/components/schemas/ConvertSelfValidation'
          description: The result of invowerk's own check of the XML.
      type: object
      required:
      - xml
      - syntax
      - flavor
      - self_validation
      title: ConvertResponse
      description: 'The answer of POST /v1/convert?format=json: the XML and the check result.'
    ConvertSelfValidation:
      properties:
        valid:
          type: boolean
          title: Valid
          description: Always true. An invalid result returns HTTP 500 instead.
        finding_count:
          type: integer
          title: Finding Count
          description: Number of findings of the check; all of them are non-fatal.
      type: object
      required:
      - valid
      - finding_count
      title: ConvertSelfValidation
      description: 'The result of invowerk''s own check of the converted XML.


        It shows that the XML passed the check before it was returned. An invalid

        result returns HTTP 500 instead.'
    Flavor:
      type: string
      enum:
      - en16931
      - xrechnung
      title: Flavor
      description: 'The rule set the invoice follows: plain EN 16931, or XRechnung (German rules).'
    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
    ParseDetection:
      properties:
        syntax:
          type: string
          title: Syntax
          description: 'Syntax of the source document: ''ubl'' or ''cii''.'
        flavor:
          type: string
          title: Flavor
          description: 'Rule set of the source, read from its CustomizationID: ''xrechnung'', ''peppol_bis'', ''factur_x'', ''en16931'' or ''unknown''.'
        customization_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Customization Id
          description: The CustomizationID (specification identifier, BT-24) of the source, if any.
      type: object
      required:
      - syntax
      - flavor
      - customization_id
      title: ParseDetection
      description: What invowerk detected about the source document, from its bytes.
    ParseResponse:
      properties:
        model:
          additionalProperties: true
          type: object
          title: Model
          description: The invoice as JSON keyed on Business Terms. It has the schema of the POST /v1/generate request body (GenerateRequest), so you can edit it and create the invoice again.
        detection:
          $ref: '#/components/schemas/ParseDetection'
          description: 'What invowerk detected: syntax, rule set and CustomizationID.'
        source:
          type: string
          title: Source
          description: 'Where the XML came from: ''xml'' (you sent XML) or ''pdf-embedded'' (taken from a ZUGFeRD / Factur-X PDF).'
      type: object
      required:
      - model
      - detection
      - source
      title: ParseResponse
      description: 'The answer of POST /v1/parse: the invoice as JSON and what invowerk detected.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key