POST /validate – Validate an e-invoice

You are here: / / POST /validate – Validate an e-invoice

REST-API · POST /validate · paid route

Validate an e-invoice: result, findings and report in one call.

This route validates an e-invoice against EN 16931 and the national rule sets. The service picks the right rule set itself, from the syntax and the specification identifier in the invoice.

You get the result, the scenario found, the findings with an explanation in your language and the full validation report in the format of the KoSIT validator. The validation is done by VAMPIRE, our validation engine.

API overview
Try it in the browser

Request

How to call the route

Address: POST https://invoicepress.de/wp-json/einvoice-api/v1/validate

Key: Send your API key in the header Authorization: Bearer <key>. Without this header, the free quota of two calls per route and day applies. If a key is sent that is not valid, the route answers with status 401.

Body: The body of the request is the invoice itself: as XML (XRechnung, Peppol BIS, CII or UBL) with Content-Type: application/xml, or as a ZUGFeRD or Factur-X PDF with Content-Type: application/pdf. From a PDF the service first takes the embedded invoice.

Parameters

ruleReport=1 (optional) – Adds the report per rule: every rule of the rule sets used with its result (satisfied, violated, not applicable, not checked), the rule sets with their edition, the time of the check and the SHA-256 checksum of the checked file. The answer grows from about 1 KB to about 280 KB on average. The call still costs one validation.

lang (optional) – de, en or fr: the language of the explanations. Without it, the header Accept-Language applies, otherwise English.

The invoice is processed in memory only and is not stored. The usage log keeps a fingerprint of the request, never its content.


Answer

What comes back

accepted – The result: true means accepted. An accepted invoice can still carry findings with the severity “warning” or “information”. So always read the result from this field, never from an empty list of findings.

scenario – The rule set chosen automatically, e.g. “XRechnung 3.0 CII”.

input – xml or pdf, depending on what you sent.

findings – The findings. Each names the rule, its severity, the text, the place in the invoice as XPath, the fields concerned (BT and BG) and an explanation in your language.

report – The full validation report in the format of the KoSIT validator, as XML text.

engine and rulesets – Name and version of the validation engine, and the rule sets with their edition, e.g. “XRechnung-UBL@3.0.2”.

When something goes wrong

Status 400 – The request was empty.

Status 401 – A key was sent, but it is unknown or blocked.

Status 415 – The content is neither XML nor PDF.

Status 422 – The XML could not be read, or the PDF carries no invoice.

Status 429 – The quota is used up. The header Retry-After tells you when it works again.


Example

A call with curl

curl -X POST "https://invoicepress.de/wp-json/einvoice-api/v1/validate?lang=en" \
     -H "Authorization: Bearer <key>" \
     -H "Content-Type: application/xml" \
     --data-binary @invoice.xml

Cost

Quota and plan

This route is a paid route. With a key, every successful call counts as one validation against the monthly quota of your plan; answers with an error status are not counted. To try it, you can call the route twice a day without a key. This limit applies per network address and per route: two calls to this route leave the other routes untouched. Every answer without a key tells you in the headers X-RateLimit-Remaining and X-RateLimit-Reset how many calls are left today and when the counter resets.

Plans and key