Integration guide

Welcome to Maventa integration guide!

This guide will tell you how to connect your financial system to Maventa 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 Maventa 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 Maventa 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 Maventa 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 Maventa.

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 Maventa 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 Maventa 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 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 webhooks, resend and handle errors.

Finvoice specialities

Finvoice format specific handling.

Invoice 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

Note! Receiving can be activated while registering the company account, but company needs to be verified before they actually can receive invoices. If the receiving was activated, invoice receiving will automatically be enabled after the company gets verified.

See more information by opening the guides for Listing and downloading invoices and Fraud reporting.

List and download invoices

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

Fraud reporting

To work on preventing invoice fraud, Maventa 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 or REST API

All companies using Maventa 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 Maventa. 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 Maventa 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 Maventa 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 Maventa 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 Maventa user interface that can be embedded into the ERP. With EUI customers don’t need to visit any external webpage to access their Maventa account but instead they can access their Maventa 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 Maventa 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 Maventa 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 0037) OVT: 0037:111111111 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 Maventa 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 Maventa agree about the way the end customers (users of partner’s software) are invoiced for their transactions and use of Maventa services.

Basis for billing

Billing is transaction based. All transactions are billed based on the partner vendor_api_key that is provided on the API calls or in some cases stored in the company details. Based on the vendor_api_key setting the transactions can be billed from the key owner (partner) or from the end customer directly.

Billing is partner specific meaning that same transaction is only billed once from a partner and you can refetch invoices to same partner’s other systems without additional cost. If a customer receives invoices into different partners’ products, i.e. uses multiple ERPs from different partners to receive invoices at the same time, each partner will be billed separately for the invoice they have received into their system.

Partner billing

We recommend all our Partners to fetch transaction reports using our Billing API. Using Billing API is not tied to Maventa’s billing time and it allows billing / transaction review automatically at any time of the month.

Billing company transactions endpoint returns transaction counts that are assigned to the authenticated billing company (partner). The endpoint contains transactions for the current and previous month. (Note! Current quarter’s data is kept until the 15th of the first month of the next quarter.)

The exact amount to be invoiced for the previous month will be checked on the 1st working day of the following month 14:00 EET (A day before Maventa’s actual invoicing). For example March transactions are ready to be fetched 3.4.2023 14:00 EET, which is the 1st working day of April.

Transaction report

All Maventa invoices are attached with a transaction report that contains all the transacations that are billed in the invoice.

The transaction report contains the following information of the transactions

Header Value
BillingCompanyID unique identifier of the invoiced company in Maventa billing system
BillingCompanyName name of the invoiced company in Maventa billing system
BillingCompanyOrganizationIdentifier business ID of the invoiced company in Maventa billing system
TargetCompanyID unique identifier of the company who has performed the transaction
TargetCompanyName name of the company who has performed the transaction
TargetCompanyOrganizationIdentifier business ID of the company who has performed the transaction
MaventaProduct name of the transaction
InvoicingProductCode product information on the invoice
DimensionItemSoftware name of the software used to perform the transaction
NumberOfActions number of transaction
ActionOriginTime first day of each invoiced month
UnitNetPrice unit price of transaction
LineNetSum total line amount

See example transaction report:

Note that the structure of this report is based on a real life example, but the data in the report is made-up.