Automation MCP Server Blog Pricing
Automation

Automating Incoming E-Invoices: Validate, Send Back the Report, Then Extract

E-invoicing is new for most businesses, and many suppliers still send invoices with errors. This guide builds a receiving pipeline from a few API calls. It checks every incoming file first. It sends invalid invoices back to the supplier with a PDF report that explains each error. Only valid invoices are read as JSON and passed to your accounting system.

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:

  1. Pick the check. Your code chooses the validation endpoint from the file type.
  2. Validate. The file goes to a validation report endpoint. The response is a PDF report, and the header X-Invoice-Valid holds the verdict.
  3. Send back invalid invoices. An invalid e-invoice goes back to the sender, with the PDF report attached.
  4. Extract. A valid file goes to the extraction endpoint. The invoice comes back as JSON.
  5. Handle plain PDFs. A PDF without invoice XML inside goes to the AI parser and then to a person for review.
  6. 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 fileHow to recognise itReport endpoint
Factur-X or ZUGFeRDA PDF file/v1/validate/facturx/report
XRechnungXML 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 CIIXML 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.vatIdentifier in your supplier records. An unknown supplier goes to review.
  • Was this invoice booked before? Look up the supplier and invoice.invoiceNumber in your ERP. A duplicate goes to review.

Then create the purchase invoice from these fields:

Purchase invoice fieldJSON field
Supplierinvoice.seller.vatIdentifier, invoice.seller.name
Invoice numberinvoice.invoiceNumber
Invoice date and due dateinvoice.issueDate, invoice.dueDate
Currencyinvoice.currency
Lines and VAT ratesinvoice.lines[]
Total and amount dueinvoice.totals.grandTotalAmount, invoice.totals.duePayableAmount
Supplier bank accountinvoice.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

PurposeEndpointInputOutput
Validate with PDF reportPOST /v1/validate/facturx/report, /zugferd/reportFactur-X or ZUGFeRD PDFPDF report, X-Invoice-Valid header
Validate with PDF reportPOST /v1/validate/xrechnung/report, /ubl/report, /cii/reportXML filePDF report, X-Invoice-Valid header
Validate as JSONPOST /v1/validate/facturx and the other formatsPDF or XML fileFindings per rule
Extract structured dataPOST /v1/extract/jsonHybrid PDF or XML fileInvoice JSON
Extract attachmentsPOST /v1/extract/attachmentsHybrid PDF or XML fileZIP of embedded files
Parse a plain PDFPOST /v1/parse/jsonPDFInvoice JSON
Render XMLPOST /v1/render/xml/to/pdfUBL, CII or XRechnung XMLReadable 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:

Start free today

Ready to automate your invoices?

Validate, convert and embed compliant e-invoices through one API. Start your 30-day free trial. No credit card required.

GDPR Compliant No credit card required Setup in minutes
Peppol UBL
Factur-X
EN 16931
142 / 142 passed
Compliant
PDF/A-3 embedded