# xmlvalid for n8n

Source: https://xmlvalid.com/docs/integrations/n8n

> Validate XML and e-invoices inside your n8n workflows, and send each document on, or back, by its result.

The [`n8n-nodes-xmlvalid`](https://www.npmjs.com/package/n8n-nodes-xmlvalid) community node checks a document against its XSD, DTD or RelaxNG schema and, for e-invoices, the Schematron business rules (EN 16931, Peppol BIS, XRechnung, Factur-X and national CIUS), with the same engine as the [validator](https://xmlvalid.com/validate). It takes a file from an earlier node, a URL or text, and returns the verdict and each finding with its line, rule id and a link that explains it.

## Install the node

1. In n8n, open **Settings → Community Nodes** and choose **Install**.
2. Enter `n8n-nodes-xmlvalid`, accept the note about community nodes and install.
3. Search for **xmlvalid** in the nodes panel of any workflow.

Installing community nodes from the settings is for the owner of a self-hosted n8n. On n8n Cloud the node appears in the nodes panel once n8n has verified it. With Docker or queue mode, see n8n's [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/).

## Add your API key

1. [Create an xmlvalid account](https://xmlvalid.com/register) and confirm your email.
2. Make a key under [Dashboard → API keys](https://xmlvalid.com/dashboard/api). It starts with `xv_` and is shown once.
3. In the xmlvalid node, open **Credential to connect with → Create new credential**, paste the key into **API Key** and save. n8n checks it right away. Leave **API URL** as it is.

## Validate a document

The quickest test needs no files: add a **Manual Trigger**, then the **xmlvalid** node with:

**Resource / Operation**

Validation / Validate.

**Document Source**

**URL**, and the address `https://xmlvalid.com/schemas/peppol-bis-3-invoice/example`: an example Peppol invoice.

**Schema**

**Auto-Detect**: an e-invoice is checked against the profile it names (its specification identifier, BT-24), so Peppol, XRechnung and Factur-X invoices can share one workflow. Pick a schema from the list to always use that one, including your [saved schemas](https://xmlvalid.com/dashboard/schemas).

Run it. The node sends the document, waits while the validation is queued and returns the result. For files from earlier nodes choose **Binary File** and the name of the binary field (`data` by default; `attachment_0` for the first email attachment). It takes XML, gzip, ZIP archives and Factur-X or ZUGFeRD PDFs, whose embedded invoice is checked. **Text** takes the XML itself, for documents your workflow builds.

## Use the result

With **Simplify** on (the default) the node returns the verdict and the findings:

```json
{
  "id": "val_01m55dyd6x75pr1e626mp09zr5",
  "status": "done",
  "valid": false,
  "outcome": "invalid",
  "schema": "peppol-bis-3-invoice",
  "errors_total": 1,
  "warnings_total": 0,
  "errors": [
    {
      "line": 139,
      "level": "error",
      "rule": "BR-CO-16",
      "message": "Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) -Paid amount (BT-113) +Rounding amount (BT-114).",
      "help_url": "https://xmlvalid.com/rules/BR-CO-16"
    }
  ],
  "warnings": [],
  "error": null
}
```

- Branch with an **If** node on `{{ $json.valid }}` is true.
- Quote the first problem in a message: `Line {{ $json.errors[0].line }}: {{ $json.errors[0].message }}`.
- List them all: ``{{ $json.errors.map(e => `Line ${e.line}: ${e.message}`).join('\n') }}``.
- `outcome` tells the cases apart: `valid`, `warnings` (valid, with warnings), `invalid`, `schema` (the schema could not be used), `input` (the document could not be read or downloaded) or `failed`.

Turn **Simplify** off for the full API response: the document's size, timings, `help_url` and `rule_url` separately, and for a ZIP or PDF the per-document `items` and the `pdf` checks. The fields are described in the [API reference](https://xmlvalid.com/docs/api#result).

## Example workflows

### Check e-invoices that arrive by email

1. **Gmail Trigger** (or **Email Trigger (IMAP)**) with **Download Attachments** on.
2. **xmlvalid**: Validate, Binary File, field `attachment_0`, Schema Auto-Detect.
3. **If** `{{ $json.valid }}`: the true branch hands the invoice to your accounting system or a shared folder; the false branch replies to the sender with the errors, or opens a ticket.

### Validate before you send

1. The node that produces your UBL or CII invoice: an HTTP Request to your ERP, a Code node or a template.
2. **xmlvalid**: Validate, Text, the schema the receiver expects (for example `peppol-bis-3-invoice` or `xrechnung-3-cii`).
3. **If** valid, send it through your Peppol access point or e-invoicing platform; otherwise post the findings to Slack or email and stop.

### Watch a feed, sitemap or export

1. **Schedule Trigger**, every hour or day.
2. **xmlvalid**: Validate, URL, a catalog schema such as `sitemap-0.9`.
3. **If** not valid: **xmlvalid** Share Report with `{{ $json.id }}` for a link anyone can open, then alert your team with it.

For a single address checked on a schedule, [URL monitors](https://xmlvalid.com/dashboard/monitors) do the same without n8n, with an email and a webhook when the document starts failing or passes again.

## All operations

**Validation → Validate**

Validate a document and wait for the result. Options: **Wait for Result** (off returns the validation queued, to fetch later), **Timeout** (minutes before it is cancelled, 15 by default) and **File Name** (shown in your history if you keep file names).

**Validation → Get**

A validation by its id, finished or not. Results are kept for 24 hours.

**Validation → Cancel**

Cancel a validation that is still queued or running.

**Validation → Share Report**

One public HTML report for one or more finished validations (ids separated by commas), open for 30 days. Pro.

**Account → Get Usage**

Your plan, the validations used this month and the limits: worth checking before a large batch.

**Account → List Schemas**

Your saved schemas and the [catalog](https://xmlvalid.com/schemas), with the name to pass as the schema.

## In an AI Agent

The node can be a tool of n8n's **AI Agent**: connect it to the agent's Tool input and the agent can validate the documents it handles, with the result to reason about. To let an AI assistant outside n8n do the same, use the [MCP server](https://xmlvalid.com/docs/api#mcp).

## Limits and errors

- Each document validated is one API validation: 100 a month on Free, 10,000 on [Pro](https://xmlvalid.com/pricing). Files up to 10 MB on Free, 1 GB on Pro.
- Requests per minute are limited too (10 on Free, 120 on Pro). For large batches, turn on **Retry On Fail** in the node's settings, or use a **Loop Over Items** node with a **Wait**.
- A refused request (an unknown schema, a file over the limit, an exhausted quota) stops the workflow with the API's message. Set **On Error** to continue to keep going and get `error` in the output instead.
- An invalid document is not an error: the node succeeds and says `"valid": false`.

Documents are validated on our servers in the EU and deleted as soon as the check finishes; see [Security](https://xmlvalid.com/security). The node's source is on [GitHub](https://github.com/xmlvalid/n8n-nodes-xmlvalid).