This guide is for developers who connect an invoice inbox to an accounting system or ERP. It shows a pipeline that handles every incoming invoice in the same way. Your code checks the file first (step 2). It sends invalid e-invoices back to the supplier with a PDF report (step 3). It reads valid ones as JSON (step 4) and passes them to your system (step 6). Each step is one API call, shown here with curl. The last section links examples and SDKs for your language.
Why you check every incoming invoice first
E-invoicing is new for most suppliers. Germany requires every business to receive e-invoices since January 2025, and suppliers may send them by email. Many suppliers create their first e-invoices with new software, and many of these files break the rules. Common errors are a missing buyer reference, wrong totals, a wrong VAT category or a missing electronic address. The mandate map lists the dates for each country.
The channel depends on the country. This guide reads invoices from an email inbox, as many German businesses receive them. In Belgium, invoices arrive through a Peppol access point. In France, they arrive through a certified e-invoicing platform. The checks stay the same: run them on every file the access point or platform delivers, and send the report back through that same channel.
An error is cheapest on the day the invoice arrives. On arrival, an invalid invoice costs one automatic email. Found later, the same error costs much more. A clerk finds it while booking, or the payment run stops on it. Then someone calls the supplier, the supplier issues a credit note and a new invoice, and the books must be corrected. Checking every file on arrival stops this at the start.
Let the report do the explaining. Your team should not have to explain e-invoicing rules to suppliers. The validation report names every broken rule, the field and the fix. The supplier reads it, corrects the invoice and sends it again. Your pipeline sends the report automatically, so no person is involved at all.
Only checked data reaches your books. An invalid file never reaches extraction or booking. Everything your accounting system receives has passed the same rules.
How the pipeline works
Every received file runs through the same steps:
- Pick the check. Your code chooses the validation endpoint from the file type.
- Validate. The file goes to a validation report endpoint. The response is a PDF report, and the header
X-Invoice-Validholds the verdict. - Send back invalid invoices. An invalid e-invoice goes back to the sender, with the PDF report attached.
- Extract. A valid file goes to the extraction endpoint. The invoice comes back as JSON.
- Handle plain PDFs. A PDF without invoice XML inside goes to the AI parser and then to a person for review.
- Book. Your code passes the JSON and the original file to your accounting system.
You need an InvoiceXML API key. Create an account to get a key and start a free trial. No credit card is needed. The pricing page shows what the trial includes. The examples send the key as Authorization: Bearer YOUR_API_KEY and upload each file as multipart/form-data in the field file.
Keep each received file unchanged: it is the invoice. The pipeline only reads it and stores copies.
Step 1: Pick the check for each file
Incoming invoices arrive in several formats. Each format has its own validation endpoint. Every endpoint has a /report version that returns the PDF report.
| Received file | How to recognise it | Report endpoint |
|---|---|---|
| Factur-X or ZUGFeRD | A PDF file | /v1/validate/facturx/report |
| XRechnung | XML whose CustomizationID contains xrechnung | /v1/validate/xrechnung/report |
| Other UBL (Peppol BIS, NLCIUS, PINT and others) | XML with the root element Invoice or CreditNote | /v1/validate/ubl/report |
| Other CII | XML with the root element CrossIndustryInvoice | /v1/validate/cii/report |
In UBL, the CustomizationID is the element cbc:CustomizationID directly under the root. In CII, it is ram:ID inside ram:GuidelineSpecifiedDocumentContextParameter. Check for XRechnung first, because an XRechnung file is also UBL or CII.
Factur-X and ZUGFeRD PDFs use the same check, so /v1/validate/zugferd/report gives the same result as the Factur-X endpoint. The UBL check applies the rule set that the file declares in its CustomizationID (BT-24). The CII check applies the profile the file declares.
Step 2: Validate and read the verdict
Send the file to the chosen endpoint. The API runs the EN 16931 rules and the rules of the declared profile. The response body is always a PDF report. The header X-Invoice-Valid is true or false, so your code never has to read the PDF.
curl -X POST https://api.invoicexml.com/v1/validate/facturx/report \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]" \
-F "validationLanguage=de" \
-D headers.txt \
--output validation-report.pdf
-D headers.txt saves the response headers. The verdict is in there:
HTTP/1.1 200 OK
Content-Type: application/pdf
X-Invoice-Valid: false
The form field validationLanguage sets the language of the report: en, de or fr. Suppliers fix errors faster when they read the report in their own language. Take the language from your supplier records, or from the country of the sender's address.
A file that cannot be read at all, such as broken XML or an empty file, gets no report. The API answers with a JSON error instead. Put such a file in a review folder for a person.
Step 3: Send the report back to the supplier
When X-Invoice-Valid is false, send the invoice straight back to the sender. Attach the PDF report to a short email from your invoice inbox. The report does the explaining: it lists every broken rule, the field it concerns and a message that says how to fix it. The email itself can be the same for every supplier:
Subject: Your invoice INV-2026-0815 did not pass our e-invoice check
Hello,
We received your invoice, but it does not meet the e-invoicing rules.
The attached report lists each error, the field and how to fix it.
Please send us a corrected invoice.
Kind regards
Accounts payable
Three rules keep this step simple:
- Send the report, not your own words. The report is precise and the same for every supplier. A clerk who writes the reason by hand needs time and e-invoicing knowledge.
- Send it automatically. The reply goes out minutes after the invoice arrives. The supplier corrects it while the case is fresh, and your payment terms are not at risk.
- Keep the file and the report. They show that you received the invoice, checked it and asked for a correction.
If your code also needs the findings as data, for a dashboard or a ticket, call the same endpoint without /report. For example, /v1/validate/facturx returns { "valid": ..., "errors": [ { "rule", "message", ... } ], "warnings": [] }.
Step 4: Extract the data as JSON
When X-Invoice-Valid is true, send the file to POST /v1/extract/json. The API reads the XML inside the PDF, or the XML file itself. No AI is involved: the values are exactly the values the supplier sent. UBL, CII, XRechnung, Factur-X and ZUGFeRD all come back in the same JSON shape.
curl -X POST https://api.invoicexml.com/v1/extract/json \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]"
The JSON has the same shape as the request body of the create endpoints, plus a totals object:
{
"invoice": {
"invoiceNumber": "INV-2026-0815",
"issueDate": "2026-11-03",
"dueDate": "2026-12-03",
"currency": "EUR",
"seller": {
"name": "Northwind Supplies GmbH",
"vatIdentifier": "DE811230999",
"postalAddress": { "line1": "Hafenstraße 12", "city": "Hamburg", "postCode": "20457", "country": "DE" }
},
"buyer": { "name": "Contoso Manufacturing GmbH", "vatIdentifier": "DE123456789" },
"paymentDetails": { "paymentAccountIdentifier": "DE02120300000000202051" },
"lines": [
{ "quantity": 20, "unitCode": "H87", "item": { "name": "Copy paper A4, 500 sheets" },
"priceDetails": { "netPrice": 4.50 }, "vatInformation": { "rate": 19 } }
],
"totals": { "grandTotalAmount": 107.10, "duePayableAmount": 107.10 }
}
}
Some suppliers embed supporting files in the invoice, such as delivery notes or timesheets. POST /v1/extract/attachments returns them as one ZIP, so you can store them next to the invoice:
curl -X POST https://api.invoicexml.com/v1/extract/attachments \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]" \
--output attachments.zip
An invoice without attachments returns 404 with error code 4013. Treat that as normal.
Step 5: Handle plain PDFs
Not every supplier sends e-invoices yet. A plain PDF has no invoice XML inside, so it fails validation. But it is not a broken e-invoice, and a report would not help the supplier. So when a PDF fails, ask the JSON validation endpoint once:
curl -X POST https://api.invoicexml.com/v1/validate/facturx \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]"
If the only finding has the rule PDF-EMBED, the PDF carries no XML:
{
"valid": false,
"data": { "hasEmbeddedXml": false },
"errors": [
{
"rule": "PDF-EMBED",
"message": "The PDF contains no embedded ZUGFeRD or Factur-X XML. Upload a PDF that was created with the e-invoice XML attached."
}
],
"warnings": []
}
Any other finding means a broken e-invoice. That one goes back to the supplier as in step 3. A plain PDF goes to POST /v1/parse/json instead. The AI reads the invoice and returns the same JSON as step 4. A document that is not an invoice, such as a contract or a letter, comes back with error code 4008.
curl -X POST https://api.invoicexml.com/v1/parse/json \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]"
Put every AI result in a review folder or queue, together with the PDF.
A quick reminder: a person checks every AI result. The AI reads the PDF well, but it can make mistakes. Before you book, store or forward a parsed invoice, compare its values with the PDF: the parties and their tax IDs, the invoice number and dates, the lines, the tax amounts and totals, and the payment details.
The invoice parser guide covers the parser in depth.
Step 6: Pass the invoice to your system
A valid e-invoice is now JSON with exact values. Hand it to your accounting system or ERP, together with the original file. Two checks belong here first:
- Is the supplier known? Look up
invoice.seller.vatIdentifierin your supplier records. An unknown supplier goes to review. - Was this invoice booked before? Look up the supplier and
invoice.invoiceNumberin your ERP. A duplicate goes to review.
Then create the purchase invoice from these fields:
| Purchase invoice field | JSON field |
|---|---|
| Supplier | invoice.seller.vatIdentifier, invoice.seller.name |
| Invoice number | invoice.invoiceNumber |
| Invoice date and due date | invoice.issueDate, invoice.dueDate |
| Currency | invoice.currency |
| Lines and VAT rates | invoice.lines[] |
| Total and amount due | invoice.totals.grandTotalAmount, invoice.totals.duePayableAmount |
| Supplier bank account | invoice.paymentDetails.paymentAccountIdentifier |
Store the original file with the booking, unchanged: it is the invoice.
An XML invoice has no page for people to look at. If your clerks or your auditor need one, POST /v1/render/xml/to/pdf turns any UBL, CII or XRechnung file into a readable PDF. Keep the XML as the invoice and the PDF as a working copy.
The integrations hub has guides that build this pipeline for one system each. The DATEV import guide, for example, maps the JSON to DATEV booking records.
Code in your language
Every step above is a plain HTTPS request, so any language with an HTTP client can run the pipeline. Two resources save you the typing:
- Example repositories on GitHub. Runnable examples per format in several languages: ZUGFeRD, XRechnung, Factur-X, UBL and CII.
- Official SDKs. Typed clients for .NET, Java, PHP, Node.js and Python, with validate, report and extract methods. The SDK page lists the packages on NuGet, Maven Central, Packagist, npm and PyPI.
Endpoint reference
| Purpose | Endpoint | Input | Output |
|---|---|---|---|
| Validate with PDF report | POST /v1/validate/facturx/report, /zugferd/report | Factur-X or ZUGFeRD PDF | PDF report, X-Invoice-Valid header |
| Validate with PDF report | POST /v1/validate/xrechnung/report, /ubl/report, /cii/report | XML file | PDF report, X-Invoice-Valid header |
| Validate as JSON | POST /v1/validate/facturx and the other formats | PDF or XML file | Findings per rule |
| Extract structured data | POST /v1/extract/json | Hybrid PDF or XML file | Invoice JSON |
| Extract attachments | POST /v1/extract/attachments | Hybrid PDF or XML file | ZIP of embedded files |
| Parse a plain PDF | POST /v1/parse/json | Invoice JSON | |
| Render XML | POST /v1/render/xml/to/pdf | UBL, CII or XRechnung XML | Readable PDF |
Get started
The whole pipeline is a handful of API calls: check every file, send invalid invoices back with the report, read valid ones as JSON and book them. The API holds the format rules and applies new rule versions on their effective dates. Your code stays the same.
Related guides:
- Reading PDF invoices in code: extraction, AI parsing, review and error codes in depth.
- DATEV e-invoice import: the same pipeline, with DATEV booking records.
- ZUGFeRD integration guide: the format, the profiles and every endpoint.
- Peppol UBL integration guide: UBL and Peppol BIS invoices through the API.