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.

In Addition to the above mentioned 3 API keys, 2 extra keys are also supported. These keys allow ERPs to pass license information along through our system, onto billing systems. These keys are supported in all our API versions and are optional:

  • license_key (License key of software making the call (255 characters max) From systems integrated to VLS this is the activation key)
  • license_meta (License metadata in JSON string format. license_meta parameter will be stored in a TEXT database field (65535 characters); if the JSON string exceeds that size, it will be cut and inconsistent data will be stored)
Json example of license_meta
{
	"licensing":"Some License",
	"erp_name":"My ERP",
	"erp_version":"1.0",
	"erp_user":"Some User"
}

Testing environment

In the testing server, electronic, email and print sends outside AutoInvoice are only simulated, but internal sends work as in the production environment. Also all the notification emails related to account management and error handling are sent out to the real recipients (e.g. do not use something like test@test.com since that domain really exists meaning that the e-mail address might also exist). Note! If there is a need to test the invoice sending via email route for a real recipient please contact us or support@maventa.com and we can enable it for a specific account.

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.

Invoice 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 AutoInvoice where to send the invoice from. Invoice sending doesn’t require any activation, but if you want to use any additional services like the print service, 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 attachments 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 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 sending, monitoring and error handling

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

Attachments and invoice image

Invoice image and attachment handling

Invoice receiving

Customers can use AutoInvoice 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.

Invoice receiving guide

How to build your invoice receiving flow, good to know about invoice networks in different countries and recommended routines for fetching the invoices.

Detect guide

Integrate Detect as part of the invoice receiving flow and support invoice processing automation with smart invoice and supplier checks.

Fraud reporting guide

Add the fraud reporting functionality into your system. And let users, with a few clicks, do reports of suspicious invoice senders.

Business document messages

Supported document formats

What are the supported document XML formats

Validation

How validation is handled

Finvoice specialities

Finvoice format specific handling

Changelog

Announcements about past and future changes

Companies and settings

API to use: SOAP API or REST 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 in verified state to ensure customer authentication process has been completed.

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 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 unique 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 & Customer Authentication

Open and verify company accounts, configure settings, different 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 either into their net bank and/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.

Detect Service Guide

Supplier activation

With supplier activation feature, customers can get information about suppliers who have sent invoices through scan service, but could send the invoices electronically.

Supplier activation

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

In addition to invoices AutoInvoice also enables usage of other trading documents.

Companies and governments have a growing interest towards full procurement automation. eOrdering automates the purchase-to-pay process and offers benefits to different teams involved in the process and the organization as a whole. These benefits include:

  • streamlines processes
  • improves supplier relations
  • increases visibility and control

Automation of ordering, for example usage of structured catalogues as a basis for ordering, simplifies the information exchange and offers benefits for both parties in the procurement chain, since different steps like approval, order picking and invoicing can be automated to name a few.

In order to start sending documents you have to be able to produce Peppol BIS or EHF. Sending of documents happens by sending a document file (XML) and specifying other necessary data as parameters. For receiving documents, you have to first register the company as a document receiver and then activate different document types and profile versions. Different document types supported by AutoInvoice are described below.

Recipient and the operator needs to be specified during the send. Senders and receivers in PEPPOL are identified using ISO6523 identifiers. Depending on the country, they can be organization IDs, VAT IDs, public sector IDs, for example

Norway - Organisation number (prefix 0192) OVT: 0192:1111111111 Operator: PEPPOL

Finland - OVT (prefix 0216) OVT: 0216:111111111111 Operator: PEPPOL

Read more information about service activation from here and sending and receiving of documents from here.

Through Peppol network the supported document types by AutoInvoice are:

  • Order - a stated intention to engage in a commercial transaction, used by the buyer to purchase goods and services. Contains information of quantities, prices and terms of the order that can be later matched to the invoice.
  • Order response - used to to accept or reject a received order.
  • Catalogue - provides information on services and/or products offered by a vendor or service provider.
  • Catalogue response - used to accept or reject a received catalogue
  • Dispatch note - a document accompanying a shipment of goods that lists the description, and quantity of the goods delivered

Read more about different Peppol BIS documents from here.

Check full list of supported document types in AX from here.

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.