Skip to main content

Overview

The API can extract the invoice data from a PDF file and convert it to a UBL document. Use this method when:
  • You have PDF invoices that you want to send through Peppol.
  • Your system generates PDF invoices but no structured data.
  • You migrate from PDF invoicing to e-invoicing.
If your ERP can only send invoices by email, see Send invoices by email (Mailbox). To attach a PDF to a document that you create from JSON, see Attachments and PDF.

How it works

A PDF upload does not create a document in your company. The API returns the extracted invoice data as JSON, with these fields in addition to the invoice fields: After the upload, you do these steps:
  1. Examine the extracted data. The extraction can contain errors.
  2. Create the document: from the ubl_document with POST /api/documents/ubl, or from the corrected JSON with POST /api/documents/.
  3. Send the document.
There are two upload methods: All upload requests use multipart/form-data with one form field with the name file.

Synchronous upload

POST /api/documents/pdf has two optional query parameters.
string
Tax ID of the vendor. If you do not give it, the API uses the tax ID of your company. If your company has no tax ID, the API uses its company number.
string
Tax ID of the customer. The API uses it as input for the extraction.
The samples use the house example: E-INVOICE BV (BE1018265814) as vendor and OpenPeppol VZW (BE0848934496) as customer. Replace the vendor tax ID with that of your company.
Response (201, shortened). This block is a response and not a request body. The UBL string is shortened, so do not use the block as input.
The response has no id, because the upload does not store a document. The values state and direction are the values that the document gets when you create it.
The synchronous upload does not return a partial result. If the API cannot make a document with one or more line items, the request returns 422 with a detail that starts with PDF could not be converted to a document (see Troubleshooting).

Create and send the document

Check success first. If success is true and the response has a ubl_document, save the string to a file and create the document from it. If success is false, do not use the ubl_document: POST /api/documents/ubl rejects a UBL that does not pass the rules. POST /api/documents/ubl accepts multipart/form-data with a file field, not a raw XML body.
cURL
The response is the created document in state DRAFT, with an id such as doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d. For this request in five languages and for the response, see Send UBL documents. If success is false, if the response has no ubl_document, or if the extracted data is not correct, correct the JSON and create the document with POST /api/documents/. See Create e-invoices. Then send the document. The samples read the document ID from the environment variable DOCUMENT_ID.
Response (200, shortened):
Before you send, make sure that the receiver is registered on the Peppol network. See Look up Peppol participants.

Asynchronous upload

The asynchronous upload has no tax ID parameters. The API uses the tax ID of your company as the vendor tax ID. If your company has no tax ID, the API uses its company number.
1

Start the conversion

cURL
Response (201):
The response has no status field. The schema permits pending, but the API does not return it: the status request gives completed or failed. Keep the task_id and poll the status request.
2

Poll the status

cURL
While the task is in progress, this request returns 404 with the detail PDF conversion task not found or expired. Continue to poll. When the task is complete, the response is 200:
The status is completed if the success field of the result is true. It is failed if success is false. Thus a failed task also has a result: get it in the next step to read the cause.
3

Get the result

cURL
The response (200) has the same structure as the response of the synchronous upload. For a failed task, success is false and error_message and error_type give the cause. Example values of error_type: DownloadError, OCRError, ExtractionError, ConversionError, DocumentCreationError and TimeoutError.If the task stops before the API extracts the data, the result has no extracted line items. The API then adds one placeholder line with the description Line items could not be extracted from PDF. Do not create a document from this result.Result of a task where the OCR found no text (200, shortened):
The API keeps the result for 5 minutes after the task is complete. After that time, the status request and the result request return 404. Stop the poll loop after a maximum time, because a 404 can mean “not complete” or “expired”.

Complete example

The example uploads a PDF, creates the document from the generated UBL and sends it. It needs only the environment variable E_INVOICE_API_KEY. In a production integration, examine the extracted data before the send step.

PDF requirements

  • The file must be a PDF that is not empty and not damaged. The API does not return 415 for a file that is not a PDF, although the API reference lists it. The synchronous upload returns 422 (see Troubleshooting).
  • A text-based PDF (generated by software) gives better results than a scanned document.
  • Put one invoice in each PDF.
  • Use a clear layout with separate sections for the vendor, the customer and the line items.
  • All mandatory invoice fields must be visible in the PDF.
The API does not publish a size limit for these two upload endpoints. Keep the files small, and use the asynchronous upload if your client or proxy has a short timeout.

Troubleshooting

For all status codes and error formats, see Errors and troubleshooting.

Best practices

  • Give vendor_tax_id and customer_tax_id with the synchronous upload.
  • Check success and ubl_document before you continue. If success is false or ubl_document is missing, a person must examine the data.
  • Examine the important fields (invoice_id, invoice_total, the tax IDs and the line items) before you send.
  • Use the asynchronous upload when you convert many PDF files, and limit the number of conversions that run at the same time.
  • Keep the original PDF files for your audit records.
  • Develop and test with a sandbox company. See Test mode and sandbox companies.

Next Steps

Send UBL documents

Create and send a document from UBL XML

Attachments and PDF

Add a PDF or other files to a JSON document

Send invoices by email (Mailbox)

Let your ERP email invoices to e-invoice.be

Errors and troubleshooting

Status codes, error formats and retry rules