Building an integration with Maventa

• Before you start
  • Choose how deep to integrate
  • Use the REST API
• The integration process
  • Your credentials
  • Working in the testing environment
  • What Maventa checks before production
  • After you go live
• Who to contact

You can build an integration with Maventa through the REST API. Maventa's integration care team supports you from your first test call until your integration is live.

Before you start

Think about what your integration needs to do. Answering these questions early makes the first conversation with Maventa more useful:

• Sending, receiving or both? Will your software send invoices, receive them, or both?
• Who are the recipients? Other companies (B2B), the public sector (B2G) or consumers (B2C)? Consumer invoicing works differently in each country.
• Which countries? What's available varies by country. See Services and reach.
• Which extra services? For example printing, scanning paper invoices, fraud checks with Detect, or accounts receivable services.

Choose how deep to integrate

You don't have to build everything at once. The integration guide describes three integration levels:

• Level 1, low effort: Invoices are sent and received through the API. Users manage company settings and follow invoices in the Maventa user interface, and errors are handled through email notifications.
• Level 2, medium effort: As level 1, but errors are also handled in the Maventa user interface instead of by email.
• Level 3, high effort: Everything happens through the API, including settings, monitoring and error handling. Users never need to leave your software.

Many integrations start at a lower level and grow over time. If you'd like to offer Maventa features inside your product without building them yourself, the embeddable user interface is another option.

Use the REST API

Maventa has two APIs: REST and SOAP. Use the REST API for new integrations. The SOAP API is a legacy API, it doesn't support all features, and new features are added to the REST API. Read more.

The integration process

1. Talk to sales. They'll go through what you want to offer your customers and connect you with the integration care team. Depending on your needs, Maventa may also arrange a kick-off meeting or training. Contact Inexchange sales.
2. Get access to the testing environment. Integration care sets up a partner account for you in the testing environment and gives you the credentials you need.
3. Build and test. Build your integration against the testing environment. Integration care can answer technical questions along the way.
4. Validate. Before production, Maventa checks that your integration works correctly.
5. Sign the agreement. All integrators sign the Maventa Integration Agreement. It covers billing, responsibilities and support, and your integration contact sends it to you.
6. Go live. You get production credentials and start using the production environment.

Your credentials

Your integration uses three credentials to connect to Maventa:

• Company UUID: identifies the company account
• User API key: identifies the user of that company
• Vendor API key: identifies your software

The vendor API key links API calls to your company as the partner. Maventa uses it for billing and reporting. One partner can have several vendor API keys, for example one per product or per country.

Testing and production have separate credentials. Keys from one environment don't work in the other. Read more.

Working in the testing environment

The testing environment lets you try most flows before going live. Keep these in mind:

• Some deliveries are real, some are simulated. Peppol test sends and sends between Maventa accounts work as in production. Email, print, consumer and external operator routes in Finland and Sweden are simulated: the invoice is marked as sent but isn't delivered.
• Notification emails are real. Use email addresses you have access to. Don't use made-up addresses or your customers' real addresses.
• Don't use real data. The testing environment is also used for Maventa's internal testing. It can be unavailable at times, and its data can be cleared without notice.

Read more about the testing environment.

What Maventa checks before production

Before your integration goes live, Maventa makes sure it works as expected. For example:

• invoices reach the right recipients with the right data
• sending over Peppol works in the countries where you use it
• consumer invoicing is set up correctly, if you use it
• received invoices are downloaded in the right format
• webhooks (automatic notifications from Maventa to your system) are received and processed
• your software doesn't check for updates more often than needed

After you go live

• Your customers confirm their accounts. Before a customer's company account can be fully used, a person with the right to represent the company confirms it. How this works depends on the country. Read more.
• Rebilling your customers. Maventa's invoice to you includes a transaction report listing each customer's transactions. Most partners use it to rebill their customers. Read more.
• Keep up with changes. Follow the developer changelog and announcements.
• Plan for service breaks. Your software should show a clear message, such as “Service unavailable, please try again later”, instead of freezing or showing raw errors to users.

Who to contact