invowerk Rules API

openapi: 3.2.0
info:
  title: invowerk Rules 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: Rules
paths:
  /v1/explain:
    get:
      tags:
      - Rules
      summary: Explain an error code
      description: 'Explain rule codes and invowerk''s own `IW-*` Hinweise in German or English.


        For each code the answer has the title, what the rule requires, common causes,

        how to fix the invoice, the affected Business Terms and `explain_url`, the path

        of the German page under `/codes/`. The codes appear in `findings` and `hints`

        of `POST /v1/validate`. If any code has no explanation, the answer is HTTP 404

        and names those codes. Costs 0 credits; an API key is not needed and does not

        raise the rate limit.


        **Credits:** free. This endpoint is not metered.'
      operationId: explain_codes
      security:
      - APIKeyHeader: []
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
          minItems: 1
          description: 'One or more codes; repeat the parameter: ?code=BR-DE-21&code=IW-IBAN.'
          title: Code
        description: 'One or more codes; repeat the parameter: ?code=BR-DE-21&code=IW-IBAN.'
      - name: lang
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Language of the explanation, `de` or `en`. Without it, the Accept-Language header decides, otherwise German.
          title: Lang
        description: Language of the explanation, `de` or `en`. Without it, the Accept-Language header decides, otherwise German.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplainResponse'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-credits-cost: 0
      x-connector:
        kind: action
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
    ExplainResponse:
      properties:
        lang:
          type: string
          title: Lang
          description: 'Language of all explanations: ''de'' or ''en''.'
        explanations:
          items:
            $ref: '#/components/schemas/RuleExplanation'
          type: array
          title: Explanations
          description: One explanation per requested code, in request order, duplicates removed.
      type: object
      required:
      - lang
      - explanations
      title: ExplainResponse
      description: 'The answer of GET /v1/explain: one explanation per requested code.


        Pass several codes with repeated ``?code=`` parameters. If any code is

        unknown, the call returns HTTP 404 and names it; there is no partial

        answer.'
    RuleExplanation:
      properties:
        code:
          type: string
          title: Code
          description: The rule code, e.g. 'BR-DE-21'.
        lang:
          type: string
          title: Lang
          description: 'Language of the explanation: ''de'' or ''en''.'
        severity:
          type: string
          title: Severity
          description: 'Severity of the rule: ''fatal'', ''warning'' or ''information''.'
        standard:
          type: string
          title: Standard
          description: 'Source of the rule: ''EN16931'', ''XRechnung'', ''ZUGFeRD'' or ''invowerk'' (IW-* hints).'
        bt_refs:
          items:
            type: string
          type: array
          title: Bt Refs
          description: The EN 16931 Business Terms the rule is about, e.g. 'BT-10'.
        title:
          type: string
          title: Title
          description: Short title of the rule.
        meaning:
          type: string
          title: Meaning
          description: What the rule requires.
        causes:
          items:
            type: string
          type: array
          title: Causes
          description: Common reasons why the rule fails.
        fixes:
          items:
            type: string
          type: array
          title: Fixes
          description: How to fix the invoice data.
        xpath_hints:
          items:
            type: string
          type: array
          title: Xpath Hints
          description: XPaths of the fields the rule checks.
        explain_url:
          type: string
          title: Explain Url
          description: 'Path of the explanation page: /codes/<CODE>, /en/codes/<CODE> in English.'
      type: object
      required:
      - code
      - lang
      - severity
      - standard
      - bt_refs
      - title
      - meaning
      - causes
      - fixes
      - xpath_hints
      - explain_url
      title: RuleExplanation
      description: 'The explanation of one rule code in the requested language.


        It explains the format rule and how to fix the invoice data. It is not tax

        advice. ``explain_url`` links the page for the code in the same language.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key