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

Reskontravahti Express for Finnish companies

Reskontravahti Express is a reminder and collection service provided by Visma Amili. It allows selected due invoices to be forwarded for reminder and collection process or directly to collection process. 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.

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

Tutorials

Invoice Response

What is an Invoice Response?

An Invoice Response is a message between Buyer and a Seller that enables efficient means for communicating about the status of a received Invoice in the Peppol network.

For example Buyer can inform the Seller if the Invoice has been rejected, under query, approved or paid.

More detailed use cases and specifications for invoice response can be found in Peppol documentation.

In this tutorial we dive deeper into how:

  • Enable receiving of the Invoice Response type of document from Peppol
  • Send Invoice Responses for received Invoices and Credit Notes from Peppol

How to take invoice responses into use in Maventa?

Before starting:

  • Have a company that is authorized to send and receive in Maventa
For a company sending invoices

In the case where a company is sending invoices they are the Seller and therefore the receiver of Invoice Responses from the Buyer. To enable the receiving of Invoice Responses the following steps needs to be taken.

Step 1 - Enable receiving of Invoice Response documents from Peppol

Use the POST /v1/company/profiles endpoint to enable Invoice Response receiving capabilities in the Peppol network. Read more about Enabling Receiving from Peppol Peppol

Request to POST /v1/company/profiles:

{
  "profiles": [
    "INVOICE_RESPONSE"
  ],
  "profile_version": "PEPPOLBIS30",
  "network": "PEPPOL"
}

Response:

{
  "id": "3abac0e6-20c1-4172-9e0b-1f882192ca6d",
  "status": "pending",
  "profile": "INVOICE_RESPONSE",
  "profiles": [
    "INVOICE_RESPONSE"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003751734872004",
  "scheme": "0216",
  "network": "PEPPOL"
}

Step 2 - Integrate to API for receiving ordering and other documents

The Invoice Response documents go in the other documents category and should be fetched using the POST /v1/documents endpoint. Read more about it in the Document Exchange) documentation.

Step 3 - Process the received Invoice Response

Details about the content of Invoice Responses can be found from the Peppol documentation.

For a company receiving invoices

In the case where a company is receiving invoices they are the Buyer and therefore the sender of Invoice Responses to the Seller. To enable the sending of Invoice Responses the following steps needs to be taken.

Step 1 - Integrate to receive invoices. Read more about receiving invoices in the Integration guide for invoice receiving.

Step 2 - Check if the Seller has capabilities to handle Invoice Response documents. This can be done doing a Peppol lookup using the GET /v1/lookup/receivers endpoint. The Sellers identifier can be found from the received invoice. For example in a PeppolBIS30 document the information is in the EndpointID element.

  <cbc:ID>567</cbc:ID>
  ...
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
      ...
    </cac:Party>
  </cac:AccountingSupplierParty>

The lookup to resolve the receiving capabilities of the Seller requires three parameters.

  • network, always set to PEPPOL, we are interested in the Peppol receiving capabilities
  • document_type, always set to INVOICE_RESPONSE, we are interested if the recipient can handle Invoice Response documents
  • eia, in the form 0216:003751734872004 and depends on the received Invoice. Represents the Seller identifier.
curl -X 'GET' \
  'https://ax-stage.maventa.com/v1/lookup/receivers?network=PEPPOL&eia=0216%3A003751734872004&document_type=INVOICE_RESPONSE' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer TOKEN'
[
  {
    "eia": "0216:003751734872004",
    "network": "PEPPOL",
    "operator": "PEPPOL",
    "document_types": [
      {
        "document_type": "INVOICE_RESPONSE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
        "process_identifier": "urn:fdc:peppol.eu:poacc:bis:invoice_response:3"
      },
      ...
    ],
    "participant": {
      "name": "Seller",
      "country": "FI"
    }
  }
]

The endpoint returns entries if the Seller enabled for processing Invoice Responses, otherwise the response will be an empty array.

Step 3 - Generate and send an Invoice Response document

Details about the business content for an Invoice Response check out the Official Peppol documentation

Example of an invoice response payload that acknowledges the receive for an Invoice with the id 567 from Seller 0216:003751734872004.

<?xml version="1.0" encoding="UTF-8"?>

<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <cbc:CustomizationID>urn:fdc:peppol.eu:poacc:trns:invoice_response:3</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:poacc:bis:invoice_response:3</cbc:ProfileID>
  <cbc:ID>1</cbc:ID>
  <cbc:IssueDate>2024-01-01</cbc:IssueDate>
  <cac:SenderParty>
    <cbc:EndpointID schemeID="0216">003751734872001</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Buyer</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:SenderParty>
  <cac:ReceiverParty>
    <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Seller</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:ReceiverParty>
  <cac:DocumentResponse>
    <cac:Response>
      <cbc:ResponseCode listID="UNCL4343OpSubset">AB</cbc:ResponseCode>
    </cac:Response>
    <cac:DocumentReference>
      <!-- Information about the orignal received invoice -->
      <cbc:ID>567</cbc:ID>
      <cbc:DocumentTypeCode listID="UNCL1001">380</cbc:DocumentTypeCode>
    </cac:DocumentReference>
  </cac:DocumentResponse>
</ApplicationResponse>

The Invoice Response payload is handed over for delivery via the POST /v1/documents endpoint.

curl -X 'POST' \
  'https://ax-stage.maventa.com/v1/documents' \
  -H 'accept: application/json' \
  -H 'content-type: multipart/form-data' \
  -F 'file=@response.xml;type=text/xml' \
  -F 'recipient_eia=0126:003751734872004' \
  -F 'recipient_operator=PEPPOL'

Response:

{
  "id": "e6c1e92b-ceba-4155-89fd-072e7ba6148f",
  "type": "INVOICE_RESPONSE"
  ...
}

Read more about documents sending and follow-up in the Document Exchange) documentation.

References

BIS Invoice Response 3.2 specification