Home Integration guide Invoice receiving

Invoice Receiving guide

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:

  • ORIGINAL_OR_GENERATED_IMAGE (returns original if one exists, and if not then we generate an image for you)
  • ORIGINAL_IMAGE (returns an image only if original exists)
  • GENERATED_IMAGE (returns image we generate)

Example usage:

  1. 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.
  2. Invoices’s original format is TEAPPSXML 3.0 and there is also invoice image and extra attachment.
    - You download the invoice as Finvoice 3.0 with GET /v1/invoices/{id} by giving return_format as FINVOICE30.
    - Then you can download the possible invoice image or other attachments with same endpoint but return_format being one of the described above.
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:

  • SCAN_PDF - Scanned from a PDF file
  • SCAN_PAPER - Scanned from a paper invoice
  • AUTOSCAN - Automatically scanned from a PDF file
  • SCAN - Scanned from non-invoice material

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 to get notification of new incoming invoices. Use the polling as a back up 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
    • Call methods starting with latest fetch timestamp and ending with current timestamp
    • If the API returns error or something unexpected, do not update timestamp but allow retry of listing at a later time
    • When the API returns a list of invoices, save invoice IDs locally with a status ‘pending download’ or such
    • Use the local ID list to download an invoice, marking it as successfully retrieved only after it has actually been retrieved (e.g. in case of errors, alert/retry download)
    • Timestamp on the server is GMT +2 and differences between client side and server side clocks might create intervals not covered when listing. Therefore, it is recommended that the timestamps have some buffer, for example 1 minute before and after to avoid any gaps in the time
    • Since the IDs of the invoices are listed locally, that list can be used to make sure the same invoice is not downloaded twice
  • 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.

Invoice receiving