invowerk Generation API

openapi: 3.2.0
info:
  title: invowerk Generation 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: Generation
paths:
  /v1/generate:
    post:
      tags:
      - Generation
      summary: Create an e-invoice from JSON
      description: 'Create an EN 16931 e-invoice from JSON.


        The JSON body is keyed on EN 16931 Business Terms (BT-*). `syntax` selects UBL

        (default) or CII. `flavor` selects plain EN 16931 (default) or XRechnung, which

        requires `buyer_reference` (BT-10, the Leitweg-ID) and `payment_iban` (BT-84).

        A credit note (381) needs CII. The seller needs `identifier` (BT-29),

        `legal_registration_id` (BT-30) or `vat_id` (BT-31). invowerk writes your

        amounts as given, with 2 decimals. It does not compute or correct them.

        Input that breaks an EN 16931 or XRechnung rule is a 422 naming each rule,

        e.g. BT-112 = BT-109 + BT-110 (BR-CO-15). Dates are YYYY-MM-DD, amounts go

        up to 999,999,999.99. Before answering, invowerk checks

        the generated XML and never returns an invalid document. The answer is

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

        self_validation}`. Errors: 422 for invalid input, with details per field or

        the rule it breaks; 500 when the generated XML still fails the check (the

        credits are refunded); 429 when every slot is busy (callers without an API key

        share one); 504 when it took longer than 20 s. Costs 5 credits.


        **Credits:** 5 per call.'
      operationId: generate_invoice
      security:
      - APIKeyHeader: []
      parameters:
      - 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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: The generated XML (default) or the JSON object (?format=json).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
            application/xml:
              schema:
                type: string
        '500':
          description: The generated XML failed invowerk's own check. No document is returned and the credits are refunded. Input that breaks a rule is a 422, not a 500.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-credits-cost: 5
      x-connector:
        kind: action
components:
  schemas:
    Syntax:
      type: string
      enum:
      - cii
      - ubl
      title: Syntax
      description: 'The XML syntax of the invoice: UBL or CII.'
    SelfValidation:
      properties:
        valid:
          type: boolean
          title: Valid
          description: Always true. An invalid result returns HTTP 500 instead.
        lane:
          type: string
          title: Lane
          description: Which check ran; always 'local' (invowerk's own check).
        finding_count:
          type: integer
          title: Finding Count
          description: Number of findings of the check; all of them are non-fatal.
      type: object
      required:
      - valid
      - lane
      - finding_count
      title: SelfValidation
      description: 'The result of invowerk''s own check of the generated XML.


        Only in the ?format=json answer. It shows that the XML passed the check

        before it was returned.'
    Buyer:
      properties:
        name:
          type: string
          title: Name
          description: Buyer name (BT-44).
        address:
          $ref: '#/components/schemas/PostalAddress'
          description: Buyer postal address (BG-8).
        vat_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Vat Id
          description: Buyer VAT ID, e.g. 'ATU12345678' (BT-48). Needed on lines with VAT category 'AE' (BR-AE-02) or 'K' (BR-IC-02).
        electronic_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Electronic Address
          description: Buyer electronic address (BT-49).
      type: object
      required:
      - name
      - address
      title: Buyer
      description: The buyer (BG-7).
    PostalAddress:
      properties:
        line_one:
          anyOf:
          - type: string
          - type: 'null'
          title: Line One
          description: Address line 1, usually street and house number (BT-35 seller, BT-50 buyer, BT-75 deliver-to).
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: City (BT-37 seller, BT-52 buyer).
        post_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Post Code
          description: Post code (BT-38 seller, BT-53 buyer).
        country_code:
          type: string
          maxLength: 2
          minLength: 2
          title: Country Code
          description: Country code, ISO 3166-1 alpha-2, e.g. 'DE' (BT-40 seller, BT-55 buyer).
      type: object
      required:
      - country_code
      title: PostalAddress
      description: 'A postal address (BG-5 seller, BG-8 buyer, BG-15 deliver-to).


        EN 16931 requires only the country. XRechnung also requires city and post

        code for the seller. invowerk does not check that the address exists.'
    GenerateRequest:
      properties:
        syntax:
          $ref: '#/components/schemas/Syntax'
          description: 'XML syntax of the invoice: ''ubl'' or ''cii''.'
          default: ubl
        flavor:
          $ref: '#/components/schemas/Flavor'
          description: 'Rule set: ''en16931'' (plain EN 16931) or ''xrechnung'' (German rules).'
          default: en16931
        invoice_number:
          type: string
          title: Invoice Number
          description: Invoice number (BT-1).
        issue_date:
          type: string
          title: Issue Date
          description: Issue date, 'YYYY-MM-DD' (BT-2).
        currency:
          type: string
          maxLength: 3
          minLength: 3
          title: Currency
          description: Currency code, ISO 4217, e.g. 'EUR' (BT-5).
          default: EUR
        invoice_type_code:
          type: string
          title: Invoice Type Code
          description: 'Invoice type code from UNTDID 1001 (BT-3): ''380'' commercial invoice, ''326'' partial invoice, ''381'' credit note (syntax ''cii'' only), ''384'' corrected invoice, ''389'' self-billed invoice, ''875''/''876''/''877'' partial, partial final and final construction invoice.'
          default: '380'
        buyer_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Buyer Reference
          description: Buyer reference, in Germany often the Leitweg-ID (BT-10). Required for flavor 'xrechnung' (BR-DE-15), optional for plain EN 16931.
        due_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Due Date
          description: Payment due date, 'YYYY-MM-DD' (BT-9).
        payment_iban:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Iban
          description: IBAN of the payee account for a bank transfer (BT-84). Without it the invoice carries no payment instructions (BG-16). Required for flavor 'xrechnung' (BR-DE-1).
        payment_terms:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Terms
          description: Payment terms as free text (BT-20).
        notes:
          items:
            type: string
          type: array
          title: Notes
          description: Free-text notes on the invoice as a whole, one entry per note (BT-22).
        delivery_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Date
          description: Actual delivery date, 'YYYY-MM-DD' (BT-72). Defaults to the issue date unless a delivery period is given.
        delivery_period_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Period Start
          description: Start of the invoicing period, 'YYYY-MM-DD' (BT-73, BG-14), e.g. the period a service covers.
        delivery_period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Period End
          description: End of the invoicing period, 'YYYY-MM-DD' (BT-74, BG-14). Not before the start (BR-29).
        deliver_to:
          anyOf:
          - $ref: '#/components/schemas/PostalAddress'
          - type: 'null'
          description: 'Deliver-to address (BG-15): where the goods go or the service is performed. Needed for VAT category ''K'', intra-community supply (BT-80, BR-IC-12).'
        deliver_to_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Deliver To Name
          description: Name of the party the goods or services are delivered to (BT-70).
        deliver_to_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Deliver To Id
          description: Identifier of the delivery location, e.g. a GLN (BT-71).
        deliver_to_id_scheme:
          anyOf:
          - type: string
          - type: 'null'
          title: Deliver To Id Scheme
          description: Scheme of 'deliver_to_id', an ISO/IEC 6523 ICD code, e.g. '0088' for a GLN (BT-71-1). Without it the identifier is written without a scheme.
        order_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Order Reference
          description: 'Purchase order reference: the buyer''s order number (BT-13).'
        preceding_invoices:
          items:
            $ref: '#/components/schemas/PrecedingInvoice'
          type: array
          title: Preceding Invoices
          description: Earlier invoices this invoice refers to (BG-3), e.g. the invoice a corrected invoice (384) replaces. Syntax 'cii' carries at most one.
        seller:
          $ref: '#/components/schemas/Seller'
        buyer:
          $ref: '#/components/schemas/Buyer'
        lines:
          items:
            $ref: '#/components/schemas/InvoiceLine'
          type: array
          minItems: 1
          title: Lines
          description: One or more invoice lines (BG-25).
        tax_breakdown:
          items:
            $ref: '#/components/schemas/TaxBreakdown'
          type: array
          minItems: 1
          title: Tax Breakdown
          description: One or more VAT breakdowns, one per VAT category and rate (BG-23).
        totals:
          $ref: '#/components/schemas/DocumentTotals'
      additionalProperties: false
      type: object
      required:
      - invoice_number
      - issue_date
      - seller
      - buyer
      - lines
      - tax_breakdown
      - totals
      title: GenerateRequest
      description: 'The request body of POST /v1/generate: an EN 16931 invoice, keyed on

        Business Terms (BT-*).


        All amounts are your own figures. invowerk writes them into the XML and

        checks the result against EN 16931 (and XRechnung, if selected). It does not

        compute or correct them. Input that breaks an EN 16931 or XRechnung rule is

        refused (HTTP 422), each rule named. Dates are YYYY-MM-DD, amounts go up to

        999,999,999.99.'
      examples:
      - buyer:
          address:
            city: Munich
            country_code: DE
            post_code: '80331'
          electronic_address: buyer@example.com
          name: Buyer AG
        buyer_reference: 04011000-1234512345-06
        currency: EUR
        due_date: '2026-02-15'
        flavor: xrechnung
        invoice_number: INV-001
        issue_date: '2026-01-15'
        lines:
        - line_net_amount: '100.00'
          name: Widget
          net_price: '100.00'
          quantity: '1'
          tax_category: S
          tax_rate: '19.00'
        payment_iban: DE75512108001245126199
        seller:
          address:
            city: Berlin
            country_code: DE
            post_code: '10115'
          contact_email: accounts@example.com
          contact_name: Accounts
          contact_phone: +49 30 1234567
          electronic_address: seller@example.com
          name: Seller GmbH
          vat_id: DE123456789
        syntax: ubl
        tax_breakdown:
        - category: S
          rate: '19.00'
          tax_amount: '19.00'
          taxable_amount: '100.00'
        totals:
          line_total: '100.00'
          tax_exclusive: '100.00'
          tax_inclusive: '119.00'
    TaxBreakdown:
      properties:
        taxable_amount:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Taxable Amount
          description: Taxable amount of the category (BT-116).
        tax_amount:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Tax Amount
          description: VAT amount of the category (BT-117).
        category:
          type: string
          title: Category
          description: VAT category code, e.g. 'S' for standard rate (BT-118).
          default: S
        rate:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Rate
          description: VAT rate of the category in percent (BT-119).
          default: '19.00'
        exemption_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Exemption Reason
          description: VAT exemption reason as text (BT-120). The rules require it or its code for categories such as 'E', 'AE', 'K', 'G' (e.g. BR-E-10).
        exemption_reason_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Exemption Reason Code
          description: VAT exemption reason code from the VATEX code list, e.g. 'VATEX-EU-AE' (BT-121).
      type: object
      required:
      - taxable_amount
      - tax_amount
      title: TaxBreakdown
      description: 'One VAT breakdown: the totals for one VAT category and rate (BG-23).'
    Flavor:
      type: string
      enum:
      - en16931
      - xrechnung
      title: Flavor
      description: 'The rule set the invoice follows: plain EN 16931, or XRechnung (German rules).'
    InvoiceLine:
      properties:
        name:
          type: string
          title: Name
          description: Item name (BT-153).
        net_price:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Net Price
          description: Net price per unit (BT-146).
        quantity:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Quantity
          description: Invoiced quantity (BT-129).
        unit_code:
          type: string
          title: Unit Code
          description: Unit code from UN/ECE Recommendation 20; 'C62' means 'one' (BT-130).
          default: C62
        line_net_amount:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Line Net Amount
          description: Line net amount, quantity × net price, as you state it (BT-131).
        tax_category:
          type: string
          title: Tax Category
          description: VAT category code of the line, e.g. 'S' for standard rate (BT-151).
          default: S
        tax_rate:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Tax Rate
          description: VAT rate of the line in percent, e.g. 19.00 (BT-152). Not written for category 'O', not subject to VAT (BR-O-05).
          default: '19.00'
      type: object
      required:
      - name
      - net_price
      - quantity
      - line_net_amount
      title: InvoiceLine
      description: One invoice line (BG-25).
    Seller:
      properties:
        name:
          type: string
          title: Name
          description: Seller name, the registered name (BT-27).
        address:
          $ref: '#/components/schemas/PostalAddress'
          description: Seller postal address (BG-5).
        vat_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Vat Id
          description: Seller VAT ID, e.g. 'DE123456789' (BT-31). Needed when a line has VAT category 'S' (BR-S-02).
        tax_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Tax Number
          description: Seller tax registration identifier, e.g. a German Steuernummer '123/456/78901' (BT-32). Written with scheme 'FC'.
        identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Identifier
          description: Seller identifier, e.g. a GLN or an ID the buyer knows the seller by (BT-29). An invoice needs BT-29, BT-30 or BT-31 (BR-CO-26).
        identifier_scheme:
          anyOf:
          - type: string
          - type: 'null'
          title: Identifier Scheme
          description: Scheme of the seller identifier, an ISO/IEC 6523 ICD code, e.g. '0088' for a GLN (BT-29-1). Leave empty for an identifier without a scheme.
        legal_registration_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Legal Registration Id
          description: Seller legal registration identifier, e.g. a Handelsregisternummer 'HRB 12345' (BT-30). An invoice needs BT-29, BT-30 or BT-31 (BR-CO-26).
        legal_registration_scheme:
          anyOf:
          - type: string
          - type: 'null'
          title: Legal Registration Scheme
          description: Scheme of the legal registration identifier, an ISO/IEC 6523 ICD code (BT-30-1). Leave empty for an identifier without a scheme.
        contact_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Name
          description: Seller contact name; required for XRechnung (BT-41).
        contact_phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Phone
          description: Seller contact phone; required for XRechnung (BT-42).
        contact_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Email
          description: Seller contact email; required for XRechnung (BT-43).
        electronic_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Electronic Address
          description: Seller electronic address, e.g. an email address (BT-34).
      type: object
      required:
      - name
      - address
      title: Seller
      description: The seller (BG-4).
    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
    DocumentTotals:
      properties:
        line_total:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Line Total
          description: Sum of the line net amounts (BT-106).
        tax_exclusive:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Tax Exclusive
          description: Invoice total without VAT (BT-109). invowerk writes no document-level allowances or charges, so to generate, it must equal the line total (BR-CO-13).
        tax_inclusive:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Tax Inclusive
          description: 'Invoice total with VAT (BT-112): the total without VAT plus the sum of the VAT breakdown amounts (BR-CO-15).'
        prepaid:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Prepaid
          description: Amount already paid, e.g. the sum of earlier partial invoices on a final invoice (BT-113).
        payable:
          anyOf:
          - type: number
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Payable
          description: Amount due for payment (BT-115). Defaults to the total with VAT minus the paid amount (BT-112 − BT-113).
      type: object
      required:
      - line_total
      - tax_exclusive
      - tax_inclusive
      title: DocumentTotals
      description: The document totals (BG-22).
    GenerateResponse:
      properties:
        xml:
          type: string
          title: Xml
          description: The generated 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/SelfValidation'
          description: The result of invowerk's own check of the XML.
      type: object
      required:
      - xml
      - syntax
      - flavor
      - self_validation
      title: GenerateResponse
      description: 'The answer of POST /v1/generate?format=json: the XML and the check result.'
    PrecedingInvoice:
      properties:
        number:
          type: string
          title: Number
          description: Number of the earlier invoice (BT-25).
        issue_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Issue Date
          description: Issue date of the earlier invoice, 'YYYY-MM-DD' (BT-26).
      type: object
      required:
      - number
      title: PrecedingInvoice
      description: 'A reference to an earlier invoice (BG-3), e.g. the invoice a corrected invoice

        (384) replaces, or a partial invoice a final invoice (877) settles.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key