Peppol Validator API & Agent Skill

REST API endpoint

Option 1: Raw XML body

Send the XML directly as the request body with a Content-Type: application/xml header.

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

Option 2: Multipart form data

Upload the file as a file field in a multipart request.

curl -X POST https://peppolvalidator.com/api/v1/validate \
  -F "file=@invoice.xml"

ZUGFeRD / Factur-X PDF

Send the PDF as the raw body with Content-Type: application/pdf or as the multipart file field (max 5MB). An optional Content-Disposition: attachment; filename="rechnung.pdf" header names a raw body in the result. See PDF results below.

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

JavaScript / Node.js

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();
console.log(result.status); // "valid" | "invalid" | "error"

Python

import requests

with open("invoice.xml") as f:
    xml = f.read()

res = requests.post(
    "https://peppolvalidator.com/api/v1/validate",
    headers={"Content-Type": "application/xml"},
    data=xml,
)

result = res.json()
print(result["status"])  # "valid" | "invalid" | "error"

Response format

Each hint in advisories has a rule page: data quality hints ADV-*.

Example response

{
  "fileId": "a1b2c3d4-...",
  "filename": "invoice.xml",
  "status": "invalid",
  "format": "ubl",
  "specification": "Peppol BIS Billing 3.0",
  "schema": "UBL 2.1 Invoice",
  "sellerCountry": "BE",
  "invoiceNumber": "INV-2026-001",
  "errors": [
    {
      "id": "XSD",
      "severity": "error",
      "rule": "XSD",
      "location": "/Invoice/cbc:IssueDate",
      "message": "Element 'cbc:IssueDate': '2026-13-01' is not a valid value of the atomic type 'xs:date'.",
      "type": "xsd",
      "line": 8,
      "column": 5
    },
    {
      "id": "1",
      "severity": "error",
      "rule": "BR-16",
      "location": "/Invoice",
      "message": "An Invoice shall have at least one Invoice line (BG-25)."
    }
  ],
  "warnings": [
    {
      "id": "2",
      "severity": "warning",
      "rule": "PEPPOL-EN16931-R080",
      "location": "/Invoice/cac:TaxTotal",
      "message": "Tax category tax amount must equal..."
    }
  ],
  "infos": [],
  "advisories": [],
  "validatedAt": "2026-02-17T12:00:00.000Z",
  "resultsUrl": "https://peppolvalidator.com/r/a1b2c3d4-..."
}

Quickstart

HTTP status codes

Error codes

Retry guidance

Authentication

CORS

XML to PDF conversion

cURL example

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

Response

Returns application/pdf with a Content-Disposition: attachment header. On error, returns JSON with an error field and a 400 status code. Supports both raw XML body and multipart form upload (same as the validation endpoint).

Agent Skill

Download and place in your project. For Claude Code, use .claude/skills/. For other agents, use .agents/skills/.

.claude/skills/validating-peppol-invoices/SKILL.md

Or create the file manually with these contents:

---
name: validating-peppol-invoices
description: Validates Peppol UBL XML invoices and credit notes
  against the UBL 2.1 XSD, EN16931 (CEN) and Peppol BIS Billing 3.0
  schematron rules via the Peppol Validator API. Use when validating
  e-invoices, checking Peppol compliance, debugging UBL XML
  validation errors, or verifying invoices before sending via
  the Peppol network.
---

# Validating Peppol Invoices

POST XML to the Peppol Validator API and parse the JSON result.

## Endpoint

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

Send raw XML with \`Content-Type: application/xml\`:

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

Returns JSON with status ("valid" / "invalid" / "error"),
errors, warnings, and invoice metadata.

A ZUGFeRD / Factur-X PDF goes to the same endpoint with
\`Content-Type: application/pdf\` (curl \`--data-binary @invoice.pdf\`).
Its PDF issues have type "pdf" and rules PDF-01 to PDF-21.
Data quality hints (rules ADV-*, not part of the official
rules) are in a separate advisories array.

What your agent can do with it

• •Validate XML invoices during development and flag issues inline
• •Run validation as part of CI/CD before deploying invoice generation code
• •Debug Peppol validation errors by examining rule IDs and locations
• •Verify fixes by re-validating after changes

Common questions