# EU E-Invoice API: API guide

Base URL: `https://einvoice-api-main-f5141d8.zuplo.app`. Authentication: `Authorization: Bearer <API key>` (developer portal: https://einvoice-api-main-f5141d8.zuplo.site).
OpenAPI 3.1 description: https://einvoice-api.eu/openapi.json. Interactive reference: https://einvoice-api-main-f5141d8.zuplo.site/api.

## Endpoints

| Endpoint | Counts as | What it does |
|---|---|---|
| `POST /v1/validate` | 1 document | Validates the invoice with the official rules of its format. |
| `POST /v1/parse` | 1 document | Validates and returns normalized EN 16931 JSON (`invoice`) and recomputed totals (`calculation`). |
| `POST /v1/generate?format=…` | 2 documents | Generates a document from normalized JSON; validated before it is returned. |
| `POST /v1/preview/validate` | 1 document | Validates against upcoming rule sets before they become mandatory (paid plans). |
| `GET /v1/formats` | free | Rule sets, versions and the documents each one validates. |
| `GET /v1/health` | free, no key | Liveness. |

Only answers with status 200 or 422 are counted; calls rejected before processing (missing key, file too large,
plan limit) are not.

## Input

`/v1/validate`, `/v1/parse` and `/v1/preview/validate` take the document as the raw request body (any of
`application/pdf`, `application/xml`, `text/xml`, `application/octet-stream`) or as `multipart/form-data` with a part
named `file`. The format is detected from the content, not from the media type. Maximum size: 10 MB, and the plan's
file size limit below.

Optional query parameter `ruleset=<id>@<version>` pins a rule-set version (repeat it or separate with commas).

## Formats detected by validate and parse

XRechnung 3.0 (UBL, CII; also inside ZUGFeRD profile XRECHNUNG), plain EN 16931 (UBL, CII), ZUGFeRD 2.x / Factur-X
(MINIMUM to EXTENDED, PDF/A-3 checked with veraPDF), the French rules BR-FR for sellers in France and EXTENDED-CTC-FR,
Peppol BIS Billing 3.0, CIUS-RO (Romania), HR-CIUS (Croatia), Peppol BIS with Slovak advisory checks, FatturaPA 1.2.3
(Italy; XML Schema and the offline SDI controls) and KSeF FA(3) (Poland; XML Schema).

## Rule sets in force

| Rule set | Version | Release |
|---|---|---|
| `xrechnung` | 3.0.2 | 2026-08-31 |
| `zugferd` | 2.5.2 | mustang-2.26.0 |
| `peppol-bis` | 3.0-2026.5 | 2026.5 |
| `ksef` | FA3-1-0E | 2025-06-25 |
| `france-rfe` | 1.4.0.04 | 2026-09-04 |
| `cius-ro` | 1.0.9 | 2024-06-05 |
| `hr-cius` | 1.0.4 | 2026-03-13 |
| `sk-advisory` | 1.0 | 2026-10-25 |
| `fatturapa` | 1.2.3 | 2025-04-01 |

`GET /v1/formats` returns the same list at run time; every result names the rule sets that were applied.

## Generate formats

The input is the JSON that `/v1/parse` returns (schema `NormalizedInvoice` in the OpenAPI description). BT-24 is set
from `format`: remove `context.specificationIdentifier` when converting a parsed invoice into another format.

| `format` | Output | Typical country |
|---|---|---|
| `xrechnung-cii` | XRechnung 3.0, CII XML | Germany |
| `xrechnung-ubl` | XRechnung 3.0, UBL XML | Germany |
| `zugferd-en16931` | ZUGFeRD / Factur-X PDF/A-3, profile EN 16931 | Germany, France |
| `facturx-basic` | Factur-X PDF/A-3, profile BASIC | France, Germany |
| `en16931-cii` | plain EN 16931, CII XML (BT-23 from the input, e.g. France) | EU |
| `en16931-ubl` | plain EN 16931, UBL XML | EU |
| `peppol-bis` | Peppol BIS Billing 3.0, UBL XML | Belgium, Slovakia, every Peppol country |
| `cius-ro-ubl` | CIUS-RO, UBL XML (RO e-Factura) | Romania |
| `hr-cius-ubl` | HR-CIUS eRačun, UBL XML | Croatia |
| `ksef-fa3` | KSeF FA(3) XML | Poland |
| `fatturapa-fpr12` | FatturaPA 1.2.3, businesses (unsigned) | Italy |
| `fatturapa-fpa12` | FatturaPA 1.2.3, public sector (unsigned; sign before sending) | Italy |

PDF formats render a neutral layout, or send multipart with `invoice` (JSON) and your own PDF/A in the part `pdf`.
The response is the document itself, with the headers `X-Validation-Warnings` (number of non-blocking findings) and
`X-Rulesets`.

## Findings

| Field | Meaning |
|---|---|
| `severity` | `fatal` or `error` (the document is invalid), `warning`, `info` |
| `ruleId` | Rule id of the rule set (e.g. `BR-DE-15`, `BR-CO-15`, `PEPPOL-EN16931-R001`) or of this API (e.g. `PDFA-…`, `CALC-…`, `PROFILE-NOT-FR`) |
| `message` | Official rule text (German for BR-DE, French for BR-FR), or this API's explanation. Owners and licences of the rule sets: https://einvoice-api.eu/licences/ |
| `xpath` | Location in the invoice XML |
| `source` | Layer: `schematron:<pack>`, `xsd:<pack>`, `pdfa:veraPDF`, `xmp`, `profile`, `calc`, … |
| `docUrl` | Public page of the rule: https://einvoice-api.eu/rules/<rule-id>.html. Present for Schematron rules of the rule sets in force. |

## Errors

Errors are RFC 9457 `application/problem+json` objects with `type`, `title`, `status`, `detail` (what to fix) and
`requestId`. An invoice that can be read but is invalid is not an error (200, `"valid": false`).

| Status | When |
|---|---|
| 400 | Malformed request: empty body, missing part, unknown or preview rule set (`unknown-ruleset`, `preview-ruleset`), input not usable for the format (`invalid-for-format`, with `errors`) |
| 401, 403 | Missing or wrong API key, or the plan does not include the endpoint (`/v1/preview/validate` on Free) |
| 413 | File above the plan's limit |
| 415 | Media type not accepted by the endpoint |
| 422 | Not an e-invoice (`validate`, `parse`); generated document invalid (`generated-invoice-invalid`, with `findings`); unusable PDF |
| 429 | Requests per minute of the plan exceeded |
| 503 | All workers busy: retry after `Retry-After` seconds |
| 504 | Processing took longer than 15 seconds |

## Plans

| Plan | Price per month | Documents per month | Extra documents | Requests per minute | Max. file |
|---|---|---|---|---|---|
| Free | EUR 0 | 100 | none (stops at the quota) | 10 | 2 MB |
| Starter | EUR 29 | 2,500 | EUR 0.015 each | 30 | 5 MB |
| Pro | EUR 99 | 15,000 | EUR 0.009 each | 60 | 10 MB |
| Scale | EUR 349 | 100,000 | EUR 0.0045 each | 120 | 10 MB |

A validate, parse or preview call counts as 1 document, a generate call as 2. Paid plans bill extra documents
automatically; the Free plan stops at its quota.

## Privacy

Documents are processed in memory on servers in Germany. Invoice content is never stored or logged.