Enter your credentials to Maventa testing environment, to authenticate and try things out with the Swagger UI. This will fetch a Bearer token using OAuth2 with the endpoint POST https://ax-stage.maventa.com/oauth2/token. The token is stored in your browser's session storage (cleared when you close the tab) and used in Swagger calls done from this documentation website. The token is valid for 1 hour.

Never use your production credentials here. This is only for testing the Maventa test environment in the Swagger UI.
All None
eui global company lookup document:receive document:send invoice:receive invoice:send company:read company:write validate receivables:assignments analysis billing:reports partner:invoice_delivery_actions partner:lookups partner:takeovers partner:lyanthe_scan_service fi_bank_message:send fi_bank_message:receive
Cancel Sign In
Get started Integration Guide Services and Networks API Specification Tutorials Changelogs
Search
Getting started Invoice sending Invoice sending Consumer Invoicing Printing Email Invoicing Invoice Receiving Invoice Receiving Scanning Country Specific Denmark Finland Germany Norway Sweden Document Exchange Document Exchange Peppol Network Invoicing formats Invoicing formats Validation Peppol BIS 3.0 Finvoice 3.0 Account Management Companies and Settings Billing

Invoice Receiving

Customers can use Maventa to receive invoices through various networks. Scanning service can be activated for PDF invoices.

Everything is delivered easily through one API. Invoices are received first to the customer’s Maventa account from where they are downloaded to the receiving financial system.

Use webhooks to build seamless receiving flow and integrate automated Detect service checks to add security and automation in the invoice processing. Fraud reporting functionality lets customers report suspicious senders and contribute to preventing invoice fraud.

Both SOAP or REST API can be used to receive invoices. Our recommendation is to use the REST. It is newer, and allows more functionality to be added on top of the regular invoice downloading - such as webhooks and Detect checks.

Overview

To receive invoices the company needs to activate the invoice receiving setting in Maventa. After this company is, depending on the country, registered to different electronic address books and they get an electronic invoice address (EIA) that can be used to send invoices to them.

From electronic networks Peppol requires its own activation. We recommend activating Peppol for all the customer so they can get the widest receiving reach possible.

Before receiving invoices

Register company account to receive

You need an company account Maventa where to receive the invoices to. Before a company account can receive invoices it needs to be verified by strong authentication.

Activate the receiving setting

Receiving is usually activated at the same time when the account is registered, but the activation can also be done at a later stage by registering invoice receiving network. The receiving setting is a master setting for e-invoices, it allows receiving from other operators, banks and internally.

When activated, the company is visible as invoice receiver in Maventa finder and will show in applicable e-invoice address books - Finnish companies will be visible in verkkolaskuosoite.fi.

Register company as Peppol receiver

When activating the electronic receiving setting, we recommend that all customers are also registered to receive electronic invoices in the international Peppol network, see more here. When company is registered their information is added to Peppol Directory.

Select receiving XML format

In the download process you can select in which XML format you want to download the invoice into your system. Maventa supports a variety of international and national formats. Make sure your system can support one of these available formats and is capable of processing the document XML. In general we recommend to use the PeppolBIS3 format.

You can also add some other services like scanning service, if a company wants to receive PDF invoices scanned. (See more here).

Routine to fetch invoices

The receiving process works simply by listing new invoices arrived to Maventa and then downloading the invoice and the attachments.

Step 1 - List new received invoices

With webhooks you can get information right away when a new invoice has arrived and can build a user friendly receiving flow. As a backup routine, we recommend to poll for invoices once a day.

Backup routine: Use GET /v1/invoices with params direction=RECEIVED, received_at_start, and received_at_end to get a list of invoices to download. Method is called per company, so it is only possible to list invoices from one company at a time.

Step 2 - Download based on listed invoice id’s

After you have saved the new incoming invoice id’s, download the invoice files and attachments into your system.

Use GET /v1/invoices/{id} to download the invoice XML file in the specified format, or to download the invoice image.

How to handle invoice image

To download invoice image you need to use param return_format:

Example usage:

Example: Original format Peppol BIS3

Invoice’s original format is Peppol BIS3 and you download it as Peppol BIS3.

You only need the XML file as it has all original attachments embedded to it. In conversion we do not forcefully embed separate attachments.

Example: Original format TEAPPSXML 3.0

Invoices’s original format is TEAPPSXML 3.0 and there is also invoice image and extra attachment.

Supported XML formats are

Invoice origin and origin_type details

In the invoice details origin shows if the received invoice is electronic invoice or scanned invoice. If the invoice origin is SCAN, extra information is provided as origin_type. It informs the type of the scanned invoice eg. if the scanned invoice is received via automatic scanning (AutoScan) or via standard scanning:

Step 3 - Fetch Detect results

Fetch the check results from Maventa.

Use GET /v1/invoices/{id}/detect_results to download the check results based on invoice id.

More information about Detect service and checks activation here

Tips and recommendations

Use webhooks with polling as backup

Use webhooks to get notification of new incoming invoices. Use the polling as a backup to method. For example once a day. If you do not implement the webhooks we do not recommend to make the polling too frequent - usually a couple of times per day is enough

Download actual invoice

After getting notifications of new invoices, have a separate process to download the actual invoice XML and attachments, and update the status with ‘download completed’ only after completed download.

This will help to ensure intermittent errors will not cause any invoices to not be downloaded.

Back to top