Documentation

API documentation

normbill is a headless e-invoicing API: you POST invoice JSON, you get back a compliant XRechnung or ZUGFeRD / Factur-X document — validated before it reaches you. When validation fails, every finding maps back to a field in your request with a plain-language message and a concrete fix.

Product pages: XRechnung API · ZUGFeRD API · XRechnung vs ZUGFeRD · XRechnung PHP. Same JSON payload, different format.

Authentication

Every request carries an API key as a bearer token. You get keys in the dashboard right after signing up — no sales call.

Authorization: Bearer sk_test_…   # or sk_live_… in production

Requests without a valid key are rejected with 401 unauthorized.

The API is plain HTTPS — no client library is required. Typed clients exist for Node.js / TypeScript and PHP, and an MCP server lets AI agents call the API directly — see SDKs & MCP server. Live status: /status. OpenAPI: /openapi.json.

Your first invoice

POST /v1/invoices/generate takes a JSON invoice and returns the generated XML plus a validation report. This payload is complete and passes validation as-is:

curl https://api.normbill.com/v1/invoices/generate \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "xrechnung-3.0",
    "invoice": {
      "number": "INV-2026-0001",
      "issue_date": "2026-06-15",
      "due_date": "2026-07-15",
      "currency": "EUR",
      "buyer_reference": "04011000-1234512345-06",
      "seller": {
        "name": "Muster Lieferant GmbH",
        "vat_id": "DE123456789",
        "address": {
          "country": "DE",
          "city": "Berlin",
          "postal_code": "10115"
        },
        "contact": {
          "name": "Billing",
          "phone": "+49 30 1234567",
          "email": "billing@lieferant.example"
        }
      },
      "buyer": {
        "name": "Beispiel Kunde AG",
        "address": {
          "country": "DE",
          "city": "Hamburg",
          "postal_code": "20095"
        },
        "contact": {
          "email": "ap@kunde.example"
        }
      },
      "payment": {
        "iban": "DE89370400440532013000"
      },
      "lines": [
        {
          "name": "Beratungsleistung",
          "qty": 10,
          "unit_price": 100,
          "vat": 19
        }
      ]
    }
  }'

A successful response (HTTP 200):

{
  "format": "xrechnung-3.0",
  "profile": "XRechnung 3.0.2 (UBL 2.1)",
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice …",
  "validation": {
    "valid": true,
    "tier": "schematron",
    "counts": { "errors": 0, "warnings": 0 },
    "issues": []
  }
}

Amounts you omit are computed for you (line totals, VAT breakdown, grand total), and sensible defaults are applied — for example currency defaults to EUR and the payment means code is derived from the IBAN. Field names are snake_case.

When validation fails: the 422 report

If the document is not valid, the API responds with HTTP 422 and does not return an invalid document. The body is an RFC 9457 problem-details object carrying a full report. Each issue tells you the rule that fired, the path in your request JSON, what is wrong, and how to fix it:

{
  "type": "https://normbill.com/docs/errors/validation-failed",
  "title": "The invoice is not valid",
  "status": 422,
  "detail": "1 error(s), 0 warning(s). Each issue includes the JSON path and a suggested fix.",
  "report": {
    "valid": false,
    "format": "xrechnung-3.0",
    "profile": "XRechnung 3.0.2 (UBL 2.1)",
    "tier": "schematron",
    "counts": {
      "errors": 1,
      "warnings": 0
    },
    "issues": [
      {
        "severity": "error",
        "rule": "BR-DE-15",
        "path": "invoice.buyer_reference",
        "message": "Buyer reference (BT-10) is missing. XRechnung requires it; public-sector buyers in Germany use their Leitweg-ID here.",
        "fix": "Set invoice.buyer_reference. Leitweg-ID format: 04011000-1234512345-06.",
        "docs_url": "https://normbill.com/docs/rules/br-de-15",
        "location": "/ubl:Invoice/cbc:BuyerReference"
      }
    ]
  }
}

• report.tier — how far validation got: structural (normbill's own pre-flight rules), schema (XSD), or schematron (the authoritative KoSIT rule set).
• issues[].path — the field in your request JSON, e.g. invoice.buyer_reference or invoice.lines[0].vat. It is null when a finding cannot be mapped back to an input field.
• issues[].docs_url — a per-rule page under /docs/rules/<rule-id>.

Quotas and rate-limit headers

Plans include a monthly document allowance (see pricing). Only successful generate and parse calls consume it — failed attempts never count, and /v1/invoices/validate has its own free fair-use allowance of five times your document quota. Every response reports where you stand:

On paid plans with metered overage active on the subscription, extra documents beyond the allowance are billed at the per-document rate shown for your tariff — capped at 2× the plan fee by default. Where metered overage is not active, calls stop at the quota with a 429 rather than being billed. The Free plan returns 429 quota-exceeded with an upgrade link.

Retries are safe: POST /v1/invoices/generate accepts an optional Idempotency-Key header (valid for 24 hours). A retry with the same key and body returns the same document and never consumes quota twice.

Test vs. live keys

• sk_test_ keys have their own allowance of 1000 requests per month and are never billed — they do not count against your plan.
• Documents generated with a test key carry a visible note marking them as test invoices, so they can't be mistaken for legal documents.
• sk_live_ keys count against the plan quota and produce production documents.

SDKs & MCP server

Typed clients for both ecosystems, with the same surface as the raw REST API:

npm i @normbill/xrechnung            # TypeScript / Node.js
composer require normbill/xrechnung    # PHP

Both cover generate, validate and parse, and type the 422 validation report so every issue maps to a field in your request. Source and docs: npm · Packagist.

MCP server: AI agents and assistants (Claude, Cursor, …) can call the API directly through @normbill/mcp — tools for generate / validate / parse plus explain_rule, a no-key lookup that returns the documentation for any KoSIT rule id. One-line setup in Claude Code:

claude mcp add normbill --env NORMBILL_API_KEY=sk_test_… -- npx -y @normbill/mcp

API reference

The whole surface is three endpoints — small on purpose. Full request/response schemas live in the OpenAPI spec; every non-2xx response is an RFC 9457 problem-details body (see the error reference).

curl https://api.normbill.com/v1/invoices/generate \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "xrechnung-3.0",
    "invoice": {
      "number": "INV-2026-0001",
      "issue_date": "2026-06-15",
      "due_date": "2026-07-15",
      "currency": "EUR",
      "buyer_reference": "04011000-1234512345-06",
      "seller": {
        "name": "Muster Lieferant GmbH",
        "vat_id": "DE123456789",
        "address": {
          "country": "DE",
          "city": "Berlin",
          "postal_code": "10115"
        },
        "contact": {
          "name": "Billing",
          "phone": "+49 30 1234567",
          "email": "billing@lieferant.example"
        }
      },
      "buyer": {
        "name": "Beispiel Kunde AG",
        "address": {
          "country": "DE",
          "city": "Hamburg",
          "postal_code": "20095"
        },
        "contact": {
          "email": "ap@kunde.example"
        }
      },
      "payment": {
        "iban": "DE89370400440532013000"
      },
      "lines": [
        {
          "name": "Beratungsleistung",
          "qty": 10,
          "unit_price": 100,
          "vat": 19
        }
      ]
    }
  }'

curl https://api.normbill.com/v1/invoices/validate \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "<?xml version=\"1.0\"?><Invoice …>…</Invoice>" }'

curl https://api.normbill.com/v1/invoices/parse \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "<?xml version=\"1.0\"?><ubl:Invoice …>…</ubl:Invoice>" }'

{
  "format": "xrechnung-3.0",
  "profile": "XRechnung 3.0.2 (UBL 2.1)",
  "invoice": {
    "number": "INV-2026-0001",
    "issue_date": "2026-06-15",
    "seller": { "name": "Muster Lieferant GmbH", "vat_id": "DE123456789", … },
    "lines": [ … ]
  }
}

Error reference

Every non-2xx response is an RFC 9457 problem-details body whose type URL links to a documented error:

Rule reference

Validation findings link to per-rule pages with the mapped JSON field and a concrete fix. The curated rules (grown from real traffic — the KoSIT validator checks many more):

Interactive API reference

The full request/response schemas are published as an OpenAPI 3.1 document generated directly from the runtime contracts — the reference cannot drift from what the API actually validates:

• Interactive reference — every schema, browsable, with request builders
• /openapi.json — the raw OpenAPI spec, ready for codegen (also served by the API at https://api.normbill.com/openapi.json)
• Postman collection — generate / validate / parse (import into Postman or Insomnia)
• Bruno OpenAPI import — point Bruno at /openapi.json (or the YAML stub) for the same contract

Questions, missing docs, or a rule that needs a better explanation? Email support@normbill.com.