POST/v1/validate

Validate an e-invoice XML against EN 16931 and format rules

Run full compliance validation on an e-invoice XML document. The pipeline performs XSD schema validation followed by Schematron business-rule checks and returns a structured report with per-rule severity, location (XPath), message, suggestion, and EN 16931 Business Term reference where available. **Auto-detection:** if `format_hint` is omitted the service inspects the XML root element and namespaces to pick the correct rule set (UBL 2.1, CII D16B, Peppol BIS 3.0, XRechnung, Factur-X/ZUGFeRD). **Size limit:** XML payloads up to 5 MB. **`is_valid`** is true only when both `schema_valid` and `business_rules_valid` are true. Required scope: `einvoice:validate`.

Authentication

Requires API key via X-API-Key header.

Request body

documentstringrequired

XML document content (string). Maximum 5 MB.

maxLen 5242880

format_hintanyoptional

Expected format code (e.g. peppol_bis_3). Auto-detected if omitted.

one of:

option 1:

string

option 2:

null

Example request

curl

curl -X POST \
  "https://einvoice.aethar.dev/api/v1/validate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":"string"}'

Responses

200Successful Response

dataValidationResultrequired

Validation result returned in the response envelope.

is_validbooleanrequired

Overall validation result

format_detectedstringrequired

Detected e-invoicing format

schema_validbooleanrequired

XML schema (XSD) validation passed

business_rules_validbooleanrequired

Schematron / business rule validation passed

error_countintegeroptional

Number of errors

default 0

warning_countintegeroptional

Number of warnings

default 0

rulesarray<ValidationRule>optional

Individual rule results

array of ValidationRule

rule_idstringrequired

Rule identifier (e.g. PEPPOL-EN16931-R001, BR-01)

severitystringrequiredenum: error | warning | info

Rule severity

messagestringrequired

Human-readable rule description

locationanyoptional

XPath or JSON path to the failing element

one of:

option 1:

string

option 2:

null

suggestionanyoptional

Actionable fix suggestion

one of:

option 1:

string

option 2:

null

business_termanyoptional

EN 16931 Business Term (e.g. BT-1)

one of:

option 1:

string

option 2:

null

processing_msanyoptional

one of:

option 1:

integer

option 2:

null

metadataMetadataSchemarequired

sourcesarray<SourceSchema>optional

array of SourceSchema

namestringrequired

Data source name

urlanyoptional

URL to the source

one of:

option 1:

string

option 2:

null

request_idstringrequired

Unique request identifier

rate_limitanyoptional

one of:

option 1:

object

option 2:

null

401Missing or invalid API key.

errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

403API key lacks the required scope for this endpoint.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

422XML is well-formed but fails schema or business rules.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

429Daily rate limit exceeded for this API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

500Unexpected server error. Includes a request_id for support.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →