API Reference

Choose an endpoint, then switch between its request, response, and errors. Every endpoint has its own schema and copy-paste example, so you can understand one operation without reading the others first.

API version v1Auth Bearer API keyTracing X-Request-Id

Base URL

https://api.invoicespec.com

Append the complete endpoint path shown below, such as /v1/invoice/xrechnung.

Machine-readable spec

A generated OpenAPI document is published from the live controllers for client generation and Postman/Insomnia import. Use openapi-generator, NSwag, Kiota, or Postman import with the links below — the interactive explorer above remains the primary reading experience.

Download OpenAPI spec (YAML)JSON
POST/v1/invoice/xrechnungJSON → XML

Generate XRechnung

Create a validated XRechnung document in CII or UBL syntax. AUTO mode calculates derived amounts before KoSIT validation.

Authentication and request

All endpoints require Authorization: Bearer YOUR_API_KEY. Send application/json. The invoice object is shared across generation endpoints; config selects XRechnung and its syntax.

Request schema

invoicerequired
object

Complete EN 16931 invoice data: parties, payment, VAT, totals, and lines.

configrequired
object

Generation standard, syntax, version, profile, and calculation mode.

config.spec
string

Specification selected by this endpoint.

"xrechnung"
config.syntaxrequired
string

XML syntax. Use CII or UBL for XRechnung; CII for ZUGFeRD.

"cii"
config.version
string

Version to generate. Omit (or send "latest") for the newest resolvable version — recommended. Pin an exact version (e.g. "3.0.2") only during a migration window; after that version's sunsetDate it is rejected with UNSUPPORTED_SPEC. See the specs-list endpoint for the current effectiveDate/sunsetDate schedule.

"3.0.2"
config.profile
string

ZUGFeRD/Factur-X profile: MINIMUM, BASICWL, BASIC, EN16931 (default), XRECHNUNG, or EXTENDED. MINIMUM/BASICWL suppress line items from the embedded XML (the PDF still shows full data). EXTENDED stamps the URN but does not model extension-only fields. Rejected with UNSUPPORTED_SPEC if not in the spec's profiles list.

"EN16931"
config.calculationMode
string

How derived fields are populated. "AUTO" recalculates every derived field (default). "MANUAL" keeps caller-provided values as-is; a missing required derived field raises FIELD_REQUIRED (400). "PARTIAL" auto-calculates null derived fields and keeps non-null ones. Case-insensitive.

"AUTO"

Copy-paste request

curl
curl -X POST https://api.invoicespec.com/v1/invoice/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/xml" \
  -d '{"invoice":{"invoiceNumber":"INV-DEMO-001","issueDate":"2025-07-01","invoiceTypeCode":"380","currencyCode":"EUR","buyerReference":"991-12345-67","seller":{"name":"Acme GmbH","legalRegistrationIdentifier":"HRB98765","vatIdentifier":"DE123456789","electronicAddress":"DE123456789","electronicAddressSchemeId":"9930","postalAddress":{"addressLine1":"Musterstr. 1","city":"Berlin","postcode":"10115","countryCode":"DE"},"contact":{"contactPoint":"Max Mustermann","telephone":"+49 30 12345678","email":"billing@acme.de"}},"buyer":{"name":"Example Corp","electronicAddress":"FR12345678901","electronicAddressSchemeId":"9930","postalAddress":{"addressLine1":"12 Rue de Rivoli","city":"Paris","postcode":"75001","countryCode":"FR"}},"deliveryInformation":{"actualDeliveryDate":"2025-07-01"},"paymentInstructions":{"meansCode":"30","creditTransfer":{"accountIdentifier":"DE89370400440532013000"}},"documentTotals":{},"vatBreakdowns":[{"vatCategoryCode":"S","vatCategoryRate":19}],"invoiceLines":[{"lineIdentifier":"1","quantity":10,"unitCode":"C62","priceDetails":{"netPrice":150},"lineVatInformation":{"vatCategoryCode":"S","vatRate":19},"itemInformation":{"name":"Consulting Services"}}]},"config":{"spec":"xrechnung","syntax":"cii"}}'

JSON body

Browse every invoice field →
Request JSON
{
  "invoice": {
    "invoiceNumber": "INV-DEMO-001",
    "issueDate": "2025-07-01",
    "invoiceTypeCode": "380",
    "currencyCode": "EUR",
    "buyerReference": "991-12345-67",
    "seller": {
      "name": "Acme GmbH",
      "legalRegistrationIdentifier": "HRB98765",
      "vatIdentifier": "DE123456789",
      "electronicAddress": "DE123456789",
      "electronicAddressSchemeId": "9930",
      "postalAddress": {
        "addressLine1": "Musterstr. 1",
        "city": "Berlin",
        "postcode": "10115",
        "countryCode": "DE"
      },
      "contact": {
        "contactPoint": "Max Mustermann",
        "telephone": "+49 30 12345678",
        "email": "billing@acme.de"
      }
    },
    "buyer": {
      "name": "Example Corp",
      "electronicAddress": "FR12345678901",
      "electronicAddressSchemeId": "9930",
      "postalAddress": {
        "addressLine1": "12 Rue de Rivoli",
        "city": "Paris",
        "postcode": "75001",
        "countryCode": "FR"
      }
    },
    "deliveryInformation": {
      "actualDeliveryDate": "2025-07-01"
    },
    "paymentInstructions": {
      "meansCode": "30",
      "creditTransfer": {
        "accountIdentifier": "DE89370400440532013000"
      }
    },
    "documentTotals": {},
    "vatBreakdowns": [
      {
        "vatCategoryCode": "S",
        "vatCategoryRate": 19
      }
    ],
    "invoiceLines": [
      {
        "lineIdentifier": "1",
        "quantity": 10,
        "unitCode": "C62",
        "priceDetails": {
          "netPrice": 150
        },
        "lineVatInformation": {
          "vatCategoryCode": "S",
          "vatRate": 19
        },
        "itemInformation": {
          "name": "Consulting Services"
        }
      }
    ]
  },
  "config": {
    "spec": "xrechnung",
    "syntax": "cii"
  }
}