Integration guide

Welcome to AutoInvoice integration guide!

This guide will tell you how to connect your financial system to AutoInvoice e-invoicing and document exchange service. See how to move from testing to production, what API methods to use for different functionality, as well as get useful tips and information about how the integration works.

Let’s go!

Get started

The integration process includes setting up the integration, testing it and finally moving to production.

Before entering the production environment all integrators are required to fill in and sign AutoInvoice Integration Agreement that outlines important arrangements such as billing and support. The agreement is given to you by your integration contact point.

To get the necessary API keys to testing and production follow the steps described below.

If you haven’t quite yet decided what type of integration to make, see our Overview section. In there you can find guidance how to define the integration scope and level based on the needed functionality and automation.

Integration setup

Step 1 - Create Account to get access to API keys

To start using AutoInvoice APIs, open a test account for your company from here.

When you have registered the company account in testing, contact Integration Care (integrations@maventa.com) or your integration contact point to convert your account into a partner account. At the same time they will create a vendor_api_key for you. This key is linked to your partner account will be used to identify your software interaction with the API.

Step 2 - Start building

After having the necessary API keys you can start building the integration. Follow feature specific guides for detailed instructions on sending, receiving, account & settings configuration and service activation.

Make sure you also understand how the testing environment works.

Step 3 - Move to production

When integration is created and tested in the testing environment, next step is to move to production. To get the necessary keys follow the same process as in testing.

First create a regular account for your company in production from here. After that contact Integration Care (integrations@maventa.com) or your integration contact point to change the account to partner and create the vendor_api_key.

When can the integration be taken to production

  • Integration is working in the testing environment
  • Integration agreement has been signed
  • Billing set up is ready

API keys

To use the API you need three different API keys, which are used in almost every request towards AutoInvoice API:

  • user_api_key (identifies a single user, required in all interaction with API)
  • company_uuid (identifies a single company, required in all interaction with API)
  • vendor_api_key (identifies a partner, required in all partner interaction with API)

User_api_key and the company_uuid are returned when you create new users and companies. The vendor_api_key is given to you by your integration contact point from AutoInvoice.

In SOAP API, authentication is performed by providing all keys on each request.

In REST API, authentication is performed by using oauth2 standard tokens. See more at REST API Authentication.

When using the API keys, make sure they are written as is and ensure there are no extra blanks before or after the key to avoid errors.

Testing environment

In testing server, electronic and print sends outside AutoInvoice are simulated, but internal and e-mail sends work as in production environment. Since emails are actually sent out, make sure to use e-mail addresses that you own when conducting testing to avoid any confusion (e.g. do not use something like test@test.com since that domain really exists meaning that the e-mail address might also exist)

It is also good to note, that the testing environment is also used for internal testing, which means that it can differ from the production environment from time to time. The database of the testing server might be unavailable at times, and the server may be emptied without notice. Also for data privacy do not use real/production data in the testing environment.

Sending

APIs to use: SOAP API or REST API

Invoices are sent by providing an XML file and specifying other necessary data as parameters on the api call. After the send you will get an ID that can be used to monitor invoice delivery.

You can use the same functionality to send invoices based on your preference either using SOAP or REST API.

To send an invoice make sure you have:

  • Sender company account: company account in Maventa where to send the invoice from. Sending doesn’t require separate activation, but if you want to use the print service or other additional services for sending, these need to be activated beforehand
  • Invoice xml: invoice XML file from your system in one of the supported e-invoice formats. You can also add supported attachments types or own invoice image to be sent with the invoice.
  • Receiver information: electronic invoicing address, email or postal address that can be used to reach the invoice receiver

See more information by opening the guides for

Invoice routing

How invoice gets delivered, how to give the delivery address and look up invoice recipients.

Invoice XML & content

What are the supported XML formats and attachment types, how invoice images and validation are handled

Invoice sending, monitoring and error handling

How to send an invoice. What are the possible invoice statuses, how to use callback notifications, resend and handle errors.

Finvoice specific logic

Finvoice format specific handling.

Receiving

APIs to use: SOAP API or REST API

Invoices are received first to the customer’s company account in Maventa where they are downloaded to the receiving financial system. In order to start receiving, the company needs to first activate the receiving setting.

You can select to receive the invoices based on preference either through SOAP or REST API. The functionality is the same in both.

To receive an invoice make sure you have

  • Receiver company account company account in Maventa where to receive the invoice to
  • Receiving setting activated Receiving is usually activated when the account is registered, but the activation can also be done at a later stage (see companies & settings) Note that receiving from some networks such as Peppol or scan network needs their own registration and activation.
  • Capability to process the document in the requested xml format In the download process you can select in which XML format you want to download the invoice into your system. Make sure your system can support at least one of these available formats

See more information by opening the guides for

List and download invoices

Recommended routine for invoice receiving - How to get information of new incoming invoices in AutoInvoice and download them into your system.

Fraud reporting

To work on preventing invoice fraud, AutoInvoice supports functionality to report us receiving of suspected fraudulent invoices. See here how to add the reporting functionality into your system to give the users an easy way to do reports. To get notifications on reported companies and other useful information for invoice handling see also more on integration to Detect service.

Companies and settings

API to use: SOAP API

All companies using AutoInvoice have an own account that is registered with unique business ID and company details. After registration company settings can be configured, including activation of different services and networks. Before account is ready to be used fully, it needs to be verified by partner or the end user company.

Company accounts will always be linked to at least one user. Users are created based on an email address. The user can be a real “human” user or a technical/API user only. This gives possibility to create the user set up in a very flexible way, taking into account the integration needs.

In company and user management note that

  • each company in the system is unique by businessID
  • each user in the system is unique by email address
  • companies have their own unique identifier; company_uuid
  • users have their own API key; user_api_key
  • each company needs to have at least one user, this can be a “real human user” or system “api user”
  • accessing the AutoInvoice web user interface requires for authentication access to the user email. If you need the company user to access the web UI, make sure that the user email exists and is accessable for the user.

Company account management

Open and verify company accounts, configure settings, account types.

User management

Create users, manage user settings and roles

Services and networks

Take into use different services and networks enabled by AutoInvoice. Select the services that you want to include in your integration and check here the service specific guides for implementation instructions.

Consumer invoicing

Send invoices to consumers into their net bank or mobile application. Use email or printing service as a fallback options for sending.

Peppol network

Send and receive electronic invoices and other trading documents in an international Peppol network.

Printing

Use print service to print the invoice and deliver it by post to recipients who cannot receive electronic invoices. Define the settings based on your customer needs.

Mass printing service (Payslip)

Use AutoInvoice Direct Print API to send EPL and PDF files as letters through print service. The service is currently available in Finland only.

Receivables Management Service for Finnish companies

Activate AutoInvoice Receivables Management Service to accelerate cash flow and free resources from manual work. The service handles reminders, payment monitoring, payment allocation, and debt collection after the invoice has been sent. Note! Only available for Finnish companies.

Scanning

Use scanning service to receive PDF and print invoices in electronic format. Open scan accounts where suppliers can send print and PDF invoices. The invoices are scanned and then delivered to the companies as electronic invoices.

Detect

Use AutoInvoice Detect service to add more automation and safety into received invoice handling. Service runs different automated checks on company’s suppliers and purchase invoices based on which company can get useful notifications to support their invoice processing.

As a source the checks are using a variety of external registers, such as central business registers or warning lists, as well as data based on the broad invoice traffic in the Nordics.

Maventa Connector

Maventa Connector is a simple Maventa client program for Windows. If your ERP does not have a direct Maventa integration but can create invoices as XML files, you can use Maventa Connector to send those invoices. More information available in Finnish at www.maventa.fi and our support portal.

Email invoicing

Invoices can also be sent as an email invoices to the recipients. Email route is used as a secondary delivery route if invoice could not be sent as an e-invoice and if recipient e-mail address is available. Email invoice sending can also be forced or then disabled completely.

Embeddable User Interface

The Embeddable User Interface (EUI) is AutoInvoice user interface that can be embedded into the ERP. With EUI customers don’t need to visit any external webpage to access their AutoInvoice account but instead they can access their AutoInvoice related settings, activate additional services and view their invoice listings directly from inside the ERP system. EUI is highly customizable which means that every ERP using it can create their own look of it by hiding parts of it their customers don’t need.

OP Laskulaina - Invoice Credit Service

OP Laskulaina invoice credit service enables companies to use their sales invoices (EUR) as collateral for a loan. When the service is in use each sent invoice will increase the amount of a loan the company can withdraw if they wish so, and only the amount they need at the time.

The service offers help in situations where the company has sales receivables and would benefit from immediate funds without having to wait for due dates that are far in the future. It is an excellent tool for managing cash flow and working capital, such as timely payment of wages, taxes and other obligatory payments. This service has been developed together with the OP Bank (Osuuspankki).

Document exchange

API to use: REST API

AutoInvoice enables sending and receiving electronic order documents through PEPPOL network. The document types supported include orders, order responses, catalogues, catalogue responses and dispatch notes.

Billing

Partner and AutoInvoice agree about the way the end customers (users of partner’s software) are invoiced for their transactions and use of AutoInvoice services.