Skip to main content

Overview

The API has two validation endpoints:
  • POST /api/validate/json converts your JSON to UBL and examines the result against the rules of EN 16931 and Peppol BIS Billing 3.0.
  • POST /api/validate/ubl examines a UBL XML file that you made yourself.
The two endpoints do not create a document and do not send data to the Peppol network.
Validation is not a separate mandatory call. POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.

Why validate

  • No document is created: you can repeat the call as often as necessary.
  • All rule failures in one response: each issue has a rule ID and a message.
  • The generated UBL: the result contains the XML that the API makes from your JSON, also when the document is not valid.
  • Fewer rejected create requests: you correct the payload before you call POST /api/documents/.

Validate a JSON document

Send the document JSON to POST /api/validate/json. The body is the same as the body of POST /api/documents/.
POST /api/validate/json does not compare the vendor with your company. POST /api/documents/ does: before you create the document, replace the vendor fields with those of your own company. When the document is valid, the API returns 201 Created with the result and the generated UBL:
201 Created
The ubl_document value is shortened in this example.
string
required
The identifier of this validation. It is not a document ID.
string | null
required
The name of the generated XML file (<id>.xml). For POST /api/validate/ubl, the name of the file that you uploaded. For POST /api/documents/{document_id}/validate, the value is null.
boolean
required
false when one issue or more has the flag fatal or is a failure of the XML schema (rule_id is xsd-validation).
array
required
The rule failures and warnings. Each issue has message, type (error or warning) and schematron (the rule set that found the issue). An issue can also have rule_id, flag, location and test. A failed rule has type error also when its flag is warning: use flag to know the severity. For the description of each field, see Validation result.
string | null
The generated UBL XML. The API returns this field each time that it can generate the UBL, also when is_valid is false. Only is_valid tells you if the document is valid. POST /api/documents/{document_id}/validate also returns it. POST /api/validate/ubl does not return this field, because you supply the XML.
The ubl_document field shows the XML that the API makes from your JSON. Use it to see how each JSON field maps to UBL.

A document that breaks rules

A rule failure does not change the HTTP status code. The API returns 201 Created, is_valid is false, and issues contains the failures. Thus your code must read is_valid, not only the status code. This payload has one fault: the vendor enterprise number BE0123456789 does not pass the modulo 97 check. It is a failing example on purpose.
Request body with a fault
201 Created
The response also contains the generated UBL in ubl_document. Do not send this UBL: it is not valid. Use it to find the element in the location of each issue. The location is the XPath of the element in the generated UBL: here the cbc:EndpointID of the supplier, which the API derives from vendor_tax_id. To correct the payload, use an enterprise number that passes the modulo 97 check: BE1018265814 in place of BE0123456789. The line in this payload has no amount. This is not a fault: if a line has no amount, the API calculates it as quantity × unit_price. For the cause and the correction of each frequent rule ID, see Frequent validation rules.

Totals that are not consistent

Before the API generates the UBL, it calculates the totals from the lines and compares them with subtotal, total_tax, total_discount, invoice_total and amount_due in your JSON. The API stops in these conditions:
  • subtotal, total_tax, total_discount or invoice_total is different from the calculated value by more than 1.00.
  • amount_due is more than the calculated invoice total plus rounding_amount plus 0.01. For example, if the calculated invoice total is 1210.00 and rounding_amount is absent, amount_due 1210.01 passes and 1210.02 fails.
  • You send a rounding_amount that is not zero, and amount_due is equal to the calculated invoice total. The amount_due must include the rounding amount.
The API then returns 406 Not Acceptable with one text message, and no issues list:
406 Not Acceptable
The message can also contain Total tax mismatch, Total discount mismatch, Invoice total mismatch, Amount due (...) cannot be greater than invoice total (...) or Amount due (...) must include the rounding amount (...). When more than one total is wrong, the list in the message has one entry for each total. POST /api/documents/ returns the same 406 for the same payload.
If you leave out a total field, the API calculates it. The API does not calculate rounding_amount. See Invoice totals and calculations and Rounding amount.
A request that does not agree with the schema (for example a date that is not YYYY-MM-DD, or a currency code that is not supported) returns 422 before the rules run. See Request validation error (422).

Not subject to VAT (VATEX-EU-O)

The API also uses this 406 format for one VAT rule. If vatex is VATEX-EU-O (not subject to VAT), vendor_tax_id and customer_tax_id must be empty. If one of them has a value, the API returns:
406 Not Acceptable
For the customer, the message is When vatex code is O (VATEX-EU-O), customer tax ID must be empty. Identify the two parties with their company IDs and give an address that ends with the country code:

VAT exemption reason

An exemption reason is the vatex code (BT-121, from the VATEX code list) or the vatex_note text (BT-120). The tax_code of the document controls if an exemption reason is necessary: The API does not do this check on the JSON. It generates the UBL, and the rules of EN 16931 examine each VAT breakdown. Thus the result is an issue in issues, not a 422. This fragment is valid:
This fragment is not valid, because tax_code E has no exemption reason:
When the line has the tax_rate 0.00, POST /api/validate/json returns 201 with is_valid false:
201 Created
POST /api/documents/ returns 406 for the same payload and does not create the document. The detail starts with Provided document details lead to an invalid UBL document and contains the message of the rule. See VAT exemption reason. "tax_code": "Z" with "vatex": "VATEX-EU-132" is also not valid. The issue then has the rule_id BR-Z-10. The category S operates differently:
  • A line with a tax_rate more than 0.00 always gets the category S. The API does not write vatex or vatex_note to the VAT breakdown of this category, and gives no issue. The receiver does not get the exemption reason.
  • A line with the tax_rate 0.00 gets the category Z when tax_code is S. If the document has vatex or vatex_note, rule BR-Z-10 fails.
Thus, do not send vatex or vatex_note when tax_code is S. For the category that each line gets, see VAT category and exemption reason.

Line items with no name

Each line item must have a name or a description (rule BR-25). A value that contains only spaces is empty. If a line has neither, POST /api/validate/json and POST /api/documents/ return 422 before the totals and the Peppol ID checks. This line has neither:
The loc gives the index of the line in items. Index 0 is the first line:
422 Unprocessable Entity
Each error also has an input object with the data of the line. This example does not show it. Add a name (BT-153), a description (BT-154) or the two to each line.

Peppol IDs that the API cannot derive

To generate the UBL, the API derives a Peppol ID for the vendor and for the customer from the tax ID, the company ID or customer_peppol_id. If it cannot derive a Peppol ID, it returns 422 with one text message and no issues list:
422 Unprocessable Entity
For the customer, the message is Invalid customer tax id. Frequent causes:
  • The tax ID has no country prefix, and the address has no country code at the end.
  • The API has no Peppol scheme for the country.
Give the VAT number with its country prefix, for example BE1018265814. If POST /api/documents/ cannot derive a Peppol ID, it returns 406 with the detail Could not derive Peppol sender or receiver information. The two endpoints derive the Peppol IDs with the same rules. For the types INVOICE, CREDIT_NOTE and DEBIT_NOTE, they also use the Peppol IDs of your company (peppol_ids of GET /api/me/) for the vendor:
  • When vendor_tax_id is empty, the API does not use vendor_address. It uses the Peppol ID of your company that has vendor_company_id as its identifier.
  • When vendor_tax_id is the company_tax_id or the company_number of your company, and your company has only one Peppol ID, the API uses that Peppol ID. For example, a Dutch company has only the Peppol ID 0106:12345678. Its VAT number in vendor_tax_id then gives the vendor Peppol ID 0106:12345678.
Two examples with "vendor_company_id": "1018265814" and no vendor_tax_id: To prevent this error, send vendor_tax_id with its country prefix, for example "vendor_tax_id": "BE1018265814". For the derivation rules, see Peppol ID routing.

Validate a UBL XML file

Use POST /api/validate/ubl to examine a UBL BIS Billing 3.0 XML file that you have.
This endpoint accepts multipart/form-data with one form field, file. It does not accept the XML as the raw request body. See Common mistake: raw XML body.
The API returns 201 Created with the validation result. A valid file gives:
201 Created
A file that breaks a rule gives the same status code, with is_valid set to false:
201 Created
The schematron field names the Schematron rule set that found the issue: CEN-EN16931-UBL, PEPPOL-EN16931-UBL, PEPPOL-EN16931-UBL-SB (self-billing) or XSD (the XML schema).

Look for errors in the issues

The validation endpoints use two different rules for is_valid:
  • POST /api/validate/json and POST /api/validate/ubl set is_valid to false only for an issue with flag fatal or rule_id xsd-validation.
  • POST /api/documents/{document_id}/validate sets is_valid to false for each issue whose flag is not warning. This includes an issue with no flag.
The rule sets use only the flags fatal and warning. Thus the results are different only for an issue with no flag. POST /api/validate/ubl gives such an issue when the file is not well-formed XML, or when the root element is not Invoice or CreditNote. The response is then 201 with is_valid true and one issue with type error, schematron XSD and no rule_id or flag:
201 Created
Thus, also make sure that each issue has a flag. Do not use type for this check: an issue with "flag": "warning" can also have "type": "error". The issue in the example above has no flag. Thus the file is not valid, although is_valid is true. In Node.js, the full check is result.is_valid && result.issues.every((issue) => issue.flag).

Common mistake: raw XML body

If you set Content-Type: application/xml and send the XML as the raw request body (for example with --data-binary @invoice.xml), the API returns this 422 response:
422 Unprocessable Entity
The correction: use multipart/form-data with a file form field, as the examples above show.

When to use UBL validation

Use POST /api/validate/ubl when you:
  • have UBL XML files from your ERP system and want to examine them before you send them
  • move from a different Peppol Access Point and have UBL documents that are already generated
  • get UBL files from an external source and want to examine them before you post them to POST /api/documents/ubl
If you create invoices from JSON, use POST /api/validate/json. It applies the same UBL rules and returns the generated UBL, so a second call to POST /api/validate/ubl is not necessary.
See also Send UBL documents.

Validate a stored document

POST /api/documents/{document_id}/validate validates a document that you already created. The request has no body.
cURL
  • The API validates the UBL that it stored when you created the document. If the document has no stored UBL, the API first generates the UBL from the document data.
  • The status code is 200 OK, not 201. A rule failure does not change it: read is_valid.
  • The rule for is_valid is stricter than the rule of POST /api/validate/json. See Look for errors in the issues.
  • The body has the same fields as the result of POST /api/validate/json. file_name is null, and ubl_document is always present.
200 OK
For the place of this call in the draft workflow, see Validate a stored draft.

Common validation problems

The currency field accepts these ISO 4217 codes: EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, SEK, NOK, DKK, SGD, HKD The default is EUR. The tax_rate of a line is a percentage from 0 to 100, for example 21.00, 6.00 or 0.00. You can send it as a number or as a string ("21.00"). If you do not give it, the rate is 0.00. For the rule ID reference, all HTTP status codes and the error body formats, see Errors and troubleshooting.

Development workflow

1

Build the invoice JSON

Start from the example in Validate a JSON document and replace the values with your data. For the fields, see Create e-invoices and the document schema.
2

Validate the JSON

Send the JSON to POST /api/validate/json. If the status code is 406 or 422, or if is_valid is false, correct the JSON and send it again.
3

Create the document

When is_valid is true, send the same JSON to POST /api/documents/. The API creates the document in the state DRAFT.

Complete example

These programs validate a document and create it only when the result is valid. Put your document JSON in the file invoice.json. The vendor in the file must be your own company.
validate-and-create.mjs
validate_and_create.py

Testing strategy

During development

Use POST /api/validate/json for each change of your payload:
  1. Edge cases: validate unusual documents (zero amounts, more than one VAT rate, a currency other than EUR).
  2. All document types: validate invoices, credit notes and debit notes.
  3. Short cycles: correct the JSON and validate again. No document is created.
  4. Automated tests: add validation calls to your test suite.
Develop and test with a sandbox company. A sandbox company runs in test mode: the API sends each document as UBL XML to the contact email address of the company, and nothing goes to the Peppol network. The API host and the endpoints are the same as for a production company. See Test mode and sandbox companies.

Before production

  1. Validate representative samples of all the invoice types that you send.
  2. Make sure that each receiver is registered on Peppol. See Look up Peppol participants.
  3. Validate all the tax categories and currency codes that you use.
  4. Validate complex documents (allowances, charges, many lines). See Advanced invoicing.

Best practices

Do not wait until production:
  • Validate each new invoice template.
  • Validate again after a change in your mapping or in the schema.
  • Add validation to your CI/CD pipeline.
The validation endpoints have a rate limit. See Rate limits.
Three results are possible. Handle each of them:
  • 201 and is_valid is true: continue with POST /api/documents/.
  • 201 and is_valid is false: record the rule_id and the message of each issue, and do not create the document.
  • 406 or 422: record the detail value, and do not create the document. The detail is a text for a totals error, a VATEX-EU-O error or a Peppol ID error. It is an array for a schema error or a line with no name.
If you generate invoices from a template, validate one document of each template when the template changes. The create request applies the rules again to each document, so a validation call for each invoice in production is not necessary.

Next Steps

Create e-invoices

Create and send validated invoices

Errors and troubleshooting

Find the cause of a status code or a rule ID

Invoice totals and calculations

Calculate totals that pass the checks

Look up Peppol participants

Find the Peppol ID of a receiver