Overview
The API has two validation endpoints:POST /api/validate/jsonconverts your JSON to UBL and examines the result against the rules of EN 16931 and Peppol BIS Billing 3.0.POST /api/validate/ublexamines a UBL XML file that you made yourself.
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 toPOST /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
ubl_document value is shortened in this example.
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.false when one issue or more has the flag fatal or is a failure of the XML schema (rule_id is xsd-validation).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.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.A document that breaks rules
A rule failure does not change the HTTP status code. The API returns201 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
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 withsubtotal, total_tax, total_discount, invoice_total and amount_due in your JSON. The API stops in these conditions:
subtotal,total_tax,total_discountorinvoice_totalis different from the calculated value by more than 1.00.amount_dueis more than the calculated invoice total plusrounding_amountplus 0.01. For example, if the calculated invoice total is 1210.00 androunding_amountis absent,amount_due1210.01 passes and 1210.02 fails.- You send a
rounding_amountthat is not zero, andamount_dueis equal to the calculated invoice total. Theamount_duemust include the rounding amount.
406 Not Acceptable with one text message, and no issues list:
406 Not Acceptable
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.
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 this406 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
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 thevatex 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:
tax_code E has no exemption reason:
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_ratemore than0.00always gets the categoryS. The API does not writevatexorvatex_noteto the VAT breakdown of this category, and gives no issue. The receiver does not get the exemption reason. - A line with the
tax_rate0.00gets the categoryZwhentax_codeisS. If the document hasvatexorvatex_note, ruleBR-Z-10fails.
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 aname 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:
loc gives the index of the line in items. Index 0 is the first line:
422 Unprocessable Entity
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 orcustomer_peppol_id. If it cannot derive a Peppol ID, it returns 422 with one text message and no issues list:
422 Unprocessable Entity
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.
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_idis empty, the API does not usevendor_address. It uses the Peppol ID of your company that hasvendor_company_idas its identifier. - When
vendor_tax_idis thecompany_tax_idor thecompany_numberof 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 ID0106:12345678. Its VAT number invendor_tax_idthen gives the vendor Peppol ID0106:12345678.
"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
UsePOST /api/validate/ubl to examine a UBL BIS Billing 3.0 XML file that you have.
201 Created with the validation result. A valid file gives:
201 Created
is_valid set to false:
201 Created
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 foris_valid:
POST /api/validate/jsonandPOST /api/validate/ublsetis_validtofalseonly for an issue withflagfatalorrule_idxsd-validation.POST /api/documents/{document_id}/validatesetsis_validtofalsefor each issue whoseflagis notwarning. This includes an issue with noflag.
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
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 setContent-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
multipart/form-data with a file form field, as the examples above show.
When to use UBL validation
UsePOST /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
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, not201. A rule failure does not change it: readis_valid. - The rule for
is_validis stricter than the rule ofPOST /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_nameisnull, andubl_documentis 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 fileinvoice.json. The vendor in the file must be your own company.
Node.js
Node.js
validate-and-create.mjs
Python
Python
validate_and_create.py
Testing strategy
During development
UsePOST /api/validate/json for each change of your payload:
- Edge cases: validate unusual documents (zero amounts, more than one VAT rate, a currency other than EUR).
- All document types: validate invoices, credit notes and debit notes.
- Short cycles: correct the JSON and validate again. No document is created.
- 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
- Validate representative samples of all the invoice types that you send.
- Make sure that each receiver is registered on Peppol. See Look up Peppol participants.
- Validate all the tax categories and currency codes that you use.
- Validate complex documents (allowances, charges, many lines). See Advanced invoicing.
Best practices
Validate early and frequently
Validate early and frequently
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.
Handle validation results in your code
Handle validation results in your code
Three results are possible. Handle each of them:
201andis_validistrue: continue withPOST /api/documents/.201andis_validisfalse: record therule_idand themessageof each issue, and do not create the document.406or422: record thedetailvalue, and do not create the document. Thedetailis a text for a totals error, aVATEX-EU-Oerror or a Peppol ID error. It is an array for a schema error or a line with no name.
Validate templates one time
Validate templates one time
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