Get started Integration Guide Services and Networks API Specification Tutorials Changelogs
Getting started Invoice sending Invoice sending Consumer Invoicing Printing Invoice Receiving Invoice Receiving Scanning Document Exchange Document Exchange Business Document Messages Companies and Settings Billing Peppol Network

Getting 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 at 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 at 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

Test session guide

Before moving to production, it is good to check that the basic operations around the integration are working. If possible, Maventa likes to organise a short test/demo session with the integrators to go over together

Company and service activation

Sending an invoice or a batch of invoices, to specific external recipients

Receiving

Extra

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 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.

Additional information about vendor_api_key

The purpose of the vendor_api_key is to identify the partner the customer and their transactions “belong” into. This is necessary for correct billing, reporting and support handling. It is very important that Partner and ERP integrations always use their own vendor_api_key in all API calls. Actions performed without supplying vendor_api_key will not be related to any vendor / partner. All actions submitted without specifying vendor_api_key will be billed directly to related customer, based on general price list.

Usually, if a partner is developing multiple different ERP systems and wants to get their customer transactions sorted by ERP, a partner wants to have a different vendor_api_key for each ERP. In general, this key is then ”hard-coded” into the software or at least hidden so that a user cannot change it.

Note also that the testing and production endpoints of the API use different API keys. API keys from testing will work on production and vice versa. Errors like USER NOT FOUND mean that the user_api_key is wrong for that environment. Please, make sure you are using the correct API endpoint for your API key.

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:

{
  "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 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.

Back to top