Validate invoice for a specific format

curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/ae/ebinterface/validate \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "invoice": {
    "invoiceNumber": "INV-2026-0042",
    "type": "invoice",
    "issueDate": "2026-03-20",
    "seller": {
      "name": "Muster GmbH",
      "countryCode": "DE"
    },
    "buyer": {
      "name": "Muster GmbH",
      "countryCode": "DE"
    },
    "items": [
      {
        "description": "Software Development Services — March 2026",
        "quantity": 40,
        "unit": "HUR",
        "unitPrice": 120,
        "netAmount": 4800,
        "taxAmount": 912
      }
    ],
    "currency": "EUR",
    "subtotal": 4800,
    "total": 5712,
    "taxSummary": [
      {
        "netAmount": 4800,
        "taxAmount": 912
      }
    ]
  }
}'

{
  "valid": false,
  "results": [
    {
      "format": "zugferd-2.4-en16931",
      "valid": true,
      "errors": [
        {
          "ruleId": "BR-DE-6",
          "message": "message"
        }
      ],
      "skipped": "not entitled"
    }
  ],
  "status": "passed",
  "errors": [
    {
      "code": "BR-O-08",
      "message": "message"
    }
  ],
  "reason": "missing"
}

Three outcomes (status): passed and failed answer 200 with the verdict; an empty or malformed document (VAL-XML-001 / VAL-XML-002) answers 422. not_run (valid: null) has two cases: a format we have no pinned rulebook for answers 200 with status: not_run and reason: missing and is billed like a check — a retry gives the same answer; a rulebook that failed to load or run answers 503 VALIDATION_UNAVAILABLE with the tool findings (VAL-SYS-*) and bills nothing — retry later.

Generate the invoice in the given format and validate the resulting XML against its official XSD and Schematron rules. For ZUGFeRD/Factur-X every profile is validated. For ebInterface 6.1 the rules are derived from the official documentation (AUSTRIAPRO, 14 June 2023); there is no official Schematron. Billed like generation: **1 unit** on that format's `create` entitlement, which the API key must hold — without it the call is rejected with 403, exactly like `/generate`. **Three outcomes** (`status`): `passed` and `failed` answer 200 with the verdict; an empty or malformed document (`VAL-XML-001` / `VAL-XML-002`) answers 422. `not_run` (`valid: null`) has two cases: a format we have **no pinned rulebook** for answers **200** with `status: not_run` and `reason: missing` and is billed like a check — a retry gives the same answer; a rulebook that failed to load or run answers **503 `VALIDATION_UNAVAILABLE`** with the tool findings (`VAL-SYS-*`) and bills nothing — retry later.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

countryCodeenumRequired

ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.

formatenumRequired

Output/input format identifier (lowercase). Valid format values depend on the country — call GET /api/v1/invoice/{countryCode}/formats to discover the exact set for a country. Overview:

pdf — all 37 countries.
ubl — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on PL it emits the national KSeF FA(3), on PT CIUS-PT, on RO eFactura (CIUS-RO), on SK CIUS-SK.
xrechnung (DE), zugferd (DE — formatOptions.profile selects EN16931/BASIC/EXTENDED; CH — Swiss CII flavour for cross-border DE/AT customers).
ebinterface (AT).
facturx (FR/BE — formatOptions.profile selects EN16931/BASIC).
fatturapa (IT — 6-char SDI codes for PA accepted).
facturae (ES).
isdoc (CZ), nav (HU), mydata (GR), ksef (PL).
peppol-ubl — generic Peppol BIS 3.0 UBL for PL/PT/RO whose ubl slot is (or can be) occupied by the national CIUS.
hr-fisk (HR — HR-FISK 2.0 CIUS, validate only).
qr-bill (CH/LI — structured 32-line QR-Bill payload as text/plain).

Exact spelling matters — values must be lowercase. The peppol-ubl, qr-bill and hr-fisk slots are dash-separated.

Output/input format identifier (lowercase). Valid format values depend on the country — call `GET /api/v1/invoice/{countryCode}/formats` to discover the exact set for a country. Overview: - **pdf** — all 37 countries. - **ubl** — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on **PL** it emits the national KSeF FA(3), on **PT** CIUS-PT, on **RO** eFactura (CIUS-RO), on **SK** CIUS-SK. - **xrechnung** (DE), **zugferd** (DE — `formatOptions.profile` selects `EN16931`/`BASIC`/`EXTENDED`; CH — Swiss CII flavour for cross-border DE/AT customers). - **ebinterface** (AT). - **facturx** (FR/BE — `formatOptions.profile` selects `EN16931`/`BASIC`). - **fatturapa** (IT — 6-char SDI codes for PA accepted). - **facturae** (ES). - **isdoc** (CZ), **nav** (HU), **mydata** (GR), **ksef** (PL). - **peppol-ubl** — generic Peppol BIS 3.0 UBL for PL/PT/RO whose `ubl` slot is (or can be) occupied by the national CIUS. - **hr-fisk** (HR — HR-FISK 2.0 CIUS, validate only). - **qr-bill** (CH/LI — structured 32-line QR-Bill payload as text/plain). Exact spelling matters — values must be lowercase. The `peppol-ubl`, `qr-bill` and `hr-fisk` slots are dash-separated.

Request

This endpoint expects an object.

invoiceobjectRequired

Invoice data to validate

Response

Validation result - passed, failed, or not_run with reason: missing when we have no pinned rulebook for the format (valid: null).

validboolean or null

true when every checked format passed XSD + Schematron without findings, false when a check found something, null when a rulebook did not run (status: not_run).

resultslist of objects

One entry per checked spec format, each with its own verdict and findings

statusenum

passed — the rulebook ran and found nothing; failed — it found something (valid: false, see errors); not_run — it did not run (completely): valid is null and reason says why. A finding beats not_run: a real finding with another rulebook not run is failed.

Allowed values:

errorslist of objectsOptional

Flattened findings across all checked formats. Absent when there are none.

reasonenumOptional

Why the check did not run: rulebook missing (we have no pinned rulebook for this format — a retry gives the same answer), load-failed, transform-failed, or not-bound (no rulebook is bound to the written version/profile). Only with status: 'not_run'.

Allowed values:

Errors

400

Validate Format Invoices Request Bad Request Error

403

Validate Format Invoices Request Forbidden Error

422

Validate Format Invoices Request Unprocessable Entity Error

429

Validate Format Invoices Request Too Many Requests Error

503

Validate Format Invoices Request Service Unavailable Error

Output/input format identifier (lowercase). Valid format values depend on the country — call GET /api/v1/invoice/{countryCode}/formats to discover the exact set for a country. Overview:

pdf — all 37 countries.
ubl — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on PL it emits the national KSeF FA(3), on PT CIUS-PT, on RO eFactura (CIUS-RO), on SK CIUS-SK.
xrechnung (DE), zugferd (DE — formatOptions.profile selects EN16931/BASIC/EXTENDED; CH — Swiss CII flavour for cross-border DE/AT customers).
ebinterface (AT).
facturx (FR/BE — formatOptions.profile selects EN16931/BASIC).
fatturapa (IT — 6-char SDI codes for PA accepted).
facturae (ES).
isdoc (CZ), nav (HU), mydata (GR), ksef (PL).
peppol-ubl — generic Peppol BIS 3.0 UBL for PL/PT/RO whose ubl slot is (or can be) occupied by the national CIUS.
hr-fisk (HR — HR-FISK 2.0 CIUS, validate only).
qr-bill (CH/LI — structured 32-line QR-Bill payload as text/plain).

Exact spelling matters — values must be lowercase. The peppol-ubl, qr-bill and hr-fisk slots are dash-separated.