INVOICE VALIDATION

Peppol and EN16931 invoice validation API.

Catch invoice format and business-rule errors before an invoice reaches your customer's accounting system. Send UBL XML and receive a structured JSON result with rule codes, severity and the validation stages used. Input-derived diagnostic text and XML paths are omitted to protect invoice data.

Start with 100 free validations

ILLUSTRATIVE EXAMPLE · SYNTHETIC DATA

See what a result looks like.

This fixed example explains the response format. It is not a live check of a company, invoice or domain.

SYNTHETIC DEMO · LOCAL ONLY

Try a fixed result

Predefined synthetic results are shown in your browser. No upload or live API call is used; this illustrates response shape only.

Choose a case

Read the BR-CO-10 guide → · Run a private check ↗

A completed validation can contain several findings. HTTP 200 describes a completed operation; read valid to determine the invoice result. The selector above is a fixed synthetic illustration and does not parse a document. Input-derived diagnostic text is omitted from responses.

View the example JSON response

{
  "valid": false,
  "profile": "peppol-bis-billing-3",
  "documentType": "Invoice",
  "ruleset": "peppol-3.0.21_cen-1.3.16_20260911",
  "stages": [
    "ubl-2.1-xsd",
    "en16931-1.3.16",
    "peppol-bis-billing-3.0.21"
  ],
  "findings": [
    {
      "code": "BR-CO-10",
      "severity": "error",
      "message": "Validation rule BR-CO-10 was not satisfied.",
      "xPath": null,
      "line": null
    }
  ],
  "truncated": false
}

Download synthetic JSON example · Run your own check →

What is validated?

UBL 2.1 XML schemas for Invoice and CreditNote.
European EN16931 business rules, including totals, VAT categories and mandatory fields.
Peppol BIS Billing 3 rules for supported UBL documents.
Explicit profile selection or automatic detection, with rule versions returned in the result.

A predictable integration

POST https://api.apivect.com/v1/invoices/validate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/xml
Idempotency-Key: invoice-validation-0001

Read valid, findings and stages in the response. HTTP 200 means validation completed; it does not mean the invoice is valid. A completed invalid invoice consumes one unit, while rejected unsafe input or an engine failure does not.

Retry without duplicate usage

Use a distinct idempotency key for each logical invoice submission. Replaying exactly the same request within 24 hours returns the stored result and does not consume another unit. Changed input with the same key is rejected.

Privacy and scope

XML is processed in memory and is not archived in application logs. Sanitized validation results are encrypted for 24-hour retry support. Technical validation is not a legal or tax determination. ApiVect is not a Peppol access point and does not transmit invoices. XRechnung and Factur-X/ZUGFeRD are outside this API's current scope.

Which profile should I select?

Use auto for supported documents with profile identifiers, peppol-bis-billing-3 for Peppol, or en16931-ubl for EN16931 UBL. ubl-2.1-schema checks XML structure only and does not establish business-rule conformance.

Follow the quickstart with a sample invoice, inspect the OpenAPI reference or compare product plans.

Download tested Python and Node.js clients to send your first request and handle completed invalid invoices.

Resolve common validation errors

Match a finding's stable code to the relevant business term. The examples below explain common errors without repeating your invoice data. A result can contain more than one finding; fix the underlying values and submit again with a new idempotency key.

Code	What to check
`XSD_ERROR`	UBL element names, namespaces, data types and element order. Business rules run only after schema validation succeeds.
`BR-06` / `BR-07`	The seller and buyer legal names must be present in their party legal entities.
`BR-CL-14`	Use a supported ISO country code in the country identification fields.
`BR-CO-10`	The sum of line net amounts must match the document's line-extension total.
`BR-CO-13`	Reconcile the amount before VAT with line totals, document allowances and document charges.
`BR-CO-14` / `BR-CO-15`	Reconcile the VAT-category amounts, total VAT and the invoice totals before and after VAT.
`BR-CO-16`	Reconcile the payable amount with the total including VAT, prepayments and payment rounding.
`BR-CO-17`	Check each VAT category's taxable amount, percentage and rounded tax amount.
`BR-S-02`	Standard-rated lines require the applicable seller or tax-representative identifier.

For other codes, consult the official EN16931 rule reference and Peppol rule reference. ApiVect reports the pinned ruleset in every completed validation; the upstream website may later describe a newer release.

Input limits and retries

Submit UTF-8 XML, at most 2 MiB and 5,000 lines. DTDs and external entities are rejected. HTTP 400/413/415/422 indicate input or profile problems; correct the request before retrying. HTTP 429 means a quota or admission limit was reached. A temporary HTTP 503 can indicate limited validation capacity: use bounded exponential backoff with jitter and retain the same idempotency key for the unchanged request. A schema-only result is not a Peppol validation.

Ruleset release notes

The current bundle is peppol-3.0.21_cen-1.3.16_20260911: UBL 2.1, EN16931 1.3.16 and Peppol BIS Billing 3.0.21. Rule files are pinned by SHA-256, reviewed and regression-tested before deployment. Official examples, totals and tax-category edge cases are part of the checks. This coverage is not a conformance certificate. See the component and source notices.

Need conversion or a readable copy?

Invoice Tools is a separate monthly subscription for JSON/UBL conversion and passive PDF reading copies, with validation included. Use the website or the API against one Tools allowance. Original values stay intact; supported business-invalid output is flagged instead of silently repaired. Compare Tools plans and read the workflow.