# Peppol Validator - Full Reference

> Free online tool for validating Peppol BIS Billing 3.0 and EN 16931 XML invoices. No signup, no API key, no rate limits.

## API Reference

### Endpoint

POST https://peppolvalidator.com/api/v1/validate

### Request options

Option 1 - Raw XML body:
  Content-Type: application/xml
  Body: the XML invoice content

Option 2 - Multipart form data:
  Content-Type: multipart/form-data
  Field "file": the XML file

### Response schema

{
  "fileId": "string (UUID)",
  "filename": "string",
  "status": "valid" | "invalid" | "error",
  "format": "ubl" | "cii",
  "specification": "string (e.g. 'Peppol BIS Billing 3.0')",
  "sellerCountry": "string (ISO 3166-1 alpha-2)",
  "invoiceNumber": "string",
  "errors": [
    {
      "id": "string",
      "severity": "error",
      "rule": "string (e.g. 'BR-16', 'PEPPOL-EN16931-R008')",
      "location": "string (XPath)",
      "message": "string"
    }
  ],
  "warnings": [
    {
      "id": "string",
      "severity": "warning",
      "rule": "string",
      "location": "string (XPath)",
      "message": "string"
    }
  ],
  "infos": [],
  "validatedAt": "string (ISO 8601)",
  "resultsUrl": "string (URL to shareable results page)"
}

### Status values

- "valid": invoice passes all rules (may still have warnings)
- "invalid": invoice has one or more errors that would cause rejection
- "error": the file could not be parsed or is not a recognized format

### Error codes

All error responses include { error: string, code: string }:
- EMPTY_BODY (400): No XML content in the request body
- MISSING_FILE (400): No "file" field in multipart form data
- FILE_TOO_LARGE (400): Uploaded file exceeds the 5MB limit
- BODY_TOO_LARGE (400): Raw request body exceeds the 5MB limit
- RULES_UNAVAILABLE (503): Schematron rules are loading; retry after 5-10 seconds
- VALIDATION_FAILED (500): Internal error during validation; retry with exponential backoff
- PDF_GENERATION_FAILED (400): XML could not be parsed or converted to PDF

### Retry guidance

- 400 errors: Do not retry. Fix the request based on the error code.
- 500 errors: Retry with exponential backoff (1s, 2s, 4s). Maximum 3 retries.
- 503 errors: Schematron rules are loading. Retry after 5-10 seconds.

### Health check

GET https://peppolvalidator.com/api/v1/health
Returns: { "status": "ok", "timestamp": "...", "service": "peppolvalidator.com", "version": "1.0.0" }

### Example curl

curl -X POST https://peppolvalidator.com/api/v1/validate \
  -H "Content-Type: application/xml" \
  -d @invoice.xml

### Example JavaScript

const xml = fs.readFileSync("invoice.xml", "utf-8");
const res = await fetch("https://peppolvalidator.com/api/v1/validate", {
  method: "POST",
  headers: { "Content-Type": "application/xml" },
  body: xml,
});
const result = await res.json();
// result.status === "valid" | "invalid" | "error"

## Validation rule categories

The validator applies three layers of schematron rules:

### Layer 1: EN 16931 (CEN) business rules
Prefix: BR-*
Examples: BR-01 (invoice must have specification identifier), BR-06 (seller name required), BR-CO-15 (VAT amount consistency)
Total: ~180 rules

### Layer 2: Peppol BIS Billing 3.0 rules
Prefix: PEPPOL-EN16931-*
Examples: PEPPOL-EN16931-R004 (electronic address scheme), PEPPOL-EN16931-R008 (no empty elements)
Total: ~50 rules

### Layer 3: Country-specific rules
Fired when seller or buyer country matches. Examples: Belgian rules, Italian rules, Norwegian rules.
Total: ~80 rules

All rules are documented at: https://peppolvalidator.com/peppol-validation-errors
Individual rule pages: https://peppolvalidator.com/peppol-validation-errors/{ruleId}

## Supported formats

### UBL 2.1 (Peppol BIS Billing 3.0)
- Invoice (namespace: urn:oasis:names:specification:ubl:schema:xsd:Invoice-2)
- CreditNote (namespace: urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2)
- Validated against: EN 16931 UBL binding + Peppol BIS 3.0 rules

### CII (Factur-X / ZUGFeRD)
- CrossIndustryInvoice (namespace: urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100)
- Validated against: EN 16931 CII binding + syntax rules (CII-SR-*)

Format is auto-detected from the XML root element and namespace.

## MCP Server

MCP endpoint: https://peppolvalidator.com/mcp
Transport: Streamable HTTP (POST with JSON-RPC)
Tools:
- validate_invoice: Validate a Peppol UBL or CII XML invoice against EN16931 and BIS Billing 3.0. Input: { xml: string }. Returns validation result as JSON text.
- xml_to_pdf: Convert a UBL or CII XML invoice to PDF. Input: { xml: string }. Returns base64-encoded PDF.
- get_verification_challenge: Get a HATCHA challenge to prove you are an AI agent. No input required. Returns { token, challenge }.
- submit_feedback: Report the outcome of using the validator. Input: { agentId, toolUsed, outcome, comment, verificationToken, verificationAnswer, accuracyIssue?, ruleIds?, invoiceFormat?, apiIssues?, sessionId?, fileId? }.

Discovery:
- https://peppolvalidator.com/.well-known/mcp - server URL and metadata
- https://peppolvalidator.com/.well-known/mcp/server-card.json - full server card with tool schemas

No authentication required.

## Agent Feedback

Agents can report validation accuracy issues and tool problems via HATCHA-verified feedback.

### HATCHA (Reverse CAPTCHA)
HATCHA proves the caller is an AI agent by issuing challenges trivial for AI but hard for humans:
- SHA-256: compute the hex digest of a random string
- Arithmetic: evaluate a large multiplication expression
- Base64: decode a base64-encoded string

### Feedback flow
1. POST /api/feedback/hatcha - get a challenge { token, challenge }
2. Solve the challenge
3. POST /api/feedback/agent - submit feedback with token and answer

### Feedback fields
Required: agentId, toolUsed (validate_invoice | xml_to_pdf), outcome (success | failure | error), comment, verificationToken, verificationAnswer
Optional: accuracyIssue (false_positive | false_negative | incorrect_severity | wrong_rule), ruleIds (e.g. ["BR-06"]), invoiceFormat (ubl | cii), apiIssues (e.g. ["timeout"]), sessionId, fileId

Rate limit: 100 submissions per hour per agent.

## AI Agent Integration

An Agent Skill file is available for AI coding agents (Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, OpenCode). The skill teaches the agent how to:
1. Call the validation API
2. Interpret the response
3. Fix common validation errors

Documentation: https://peppolvalidator.com/ai-agents

## About

Peppol Validator is operated by e-invoice.be. It is free, requires no signup, and has no upload limits. Results are shareable via unique URLs.

Website: https://peppolvalidator.com