Maventa REST API covers the following API’s
You will find more information of the APIs below.
Before you continue, make sure you have read our Integration guide and understand the Partner Agreement
How to get started and get the necessary keys to set up the integration is explained in our Integration guide
You will also also find there feature specific guides for sending, receiving, companies and settings, services and networks and billing that list what API method to use for different tasks.
Detailed technical documentation can be found at swagger.maventa.com. Select the environment and correct API in the top-right corner of the page and you will find a full list of methods with detailed descriptions of parameters and responses.
You can also try out the API directly in your browser with the Swagger user interface. Just click the “Authorize” button first and then “Try it out” button found under each method.
Updated at 28.10.2020
This example has a collection with all the avalaible endpoints and an example environment.
In order to use the collection successfully:
baseUrl
and tokenUrl
are given in collection’s (the parent) Variables tab. In Authorization tab, the type is set to BearerToken and it uses environment variable access_token
POST /oauth2/token
endpoint to get access_token
environment variable created to your environment variablesInherits auth from the parent
Authentication to REST API is based on the Oauth2 standard. Using of all API functions requires a valid Oauth2 bearer token, retrievable with the user_api_key and company_id . Expiry is set on server side and the mechanism to handle the expiry of the token is suggested to be handled gracefully on the client side.
The endpoint for aquiring the token is POST /oauth2/token. This endpoint provides authentication to all of the Maventa REST APIs.
POST /oauth2/token
expires_in
field
Authenticating requires a user_api_key and company_id. To create an account in testing, registrations can be done in Maventa Web UI, then logging in, and navigating to settings.
Also you need a vendor_api_key. When you have registered a company account in testing, contact your integration contact point or Maventa support to convert your account into a partner account and create a vendor_api_key for you.
Call the POST /oauth2/token
method with company credentials:
Notes:
Call the POST /oauth2/token
method with operator credentials:
The client should always handle any server/connection issues gracefully. Do not lock up or throw exceptions directly at your users. There can be both scheduled and unscheduled breaks in the service which should be handled on the client side, for example with messages like “Service unavailable, please try again later”.
AutoXChange API (also known as AX API) can be used to send and receive invoices, orders and other trading documents, to register to callback notifications and to activate different networks and services such as Peppol. AutoXChange API also includes Detect, a service that performs automatic checks and analysis on invoices.
Invoices are sent by providing an XML file and specifying other necessary data for send as parameters on the api call.
direction=SENT
or GET /v1/invoices/{id}to poll status of sent documents to see those are either delivered successfully or failed in delivery. You can also use callback notifications to get notifications of invoices states.See more guidance and recommended routine for invoice sending in Integration guide
Check supported invoice formats from here and some example XML files from here.
Invoices are received by listing new incoming invoices in Maventa and then downloading the invoice and attachments into the financial system.
direction=RECEIVED
, received_at_start
, and received_at_end
to get list of invoices available for download. It is possible to use the param fields
to limit the amount of data returned on the response.See more guidance and recommended routine for invoice receiving in Integration guide
Note that this endpoint is meant for other trading documents than invoices and credit notes, such as order documents, vouchers and reminders. For exchanging invoices and credit notes see Invoice Exchange. Please also note that format conversions and full look up features are not supported for this endpoint.
Documents are sent by sending a document file, usually an XML, and specifying other necessary data as parameters on the api call.
POST /v1/documents
to send a document, getting back a document ID in returnGET /v1/documents/{id}
to poll status of sent documents to see those are either delivered successfully or failed in delivery. You can also use callback notifications to get notifications of document statesCurrently POST /v1/documents
does not provide automatic lookup features, so in order to send a document both the recipient and the operator needs to be specified during the send. This can be done by specifying the recipient and recipient operator as parameters in the POST call. Recipient information is also parsed from supported xml file formats.
Documents are received by listing new incoming documents in Maventa and then downloading the document and attachments into the financial system.
To receive documents, register first the company as document receiver
The endpoint for profile registrations is POST /v1/company/profiles
You can also use Callback notifications to get notifications when the registration status changes.
direction=RECEIVED
, received_at_start
, and received_at_end
to get list of documents available for download. It is possible to use the param fields
to limit the amount of data returned on the response.Maventa supports user-defined HTTP callbacks also known as webhooks. Using the AX API you can subscribe to certain type of events, and when that event happens we will send a HTTP POST request to the endpoint you defined.
Currently the event types are following:
We expect HTTP 200, 201 or 204 responses when the server has successfully handled the callback request. If for some reason the response is something else or the server is unavailable we will retry the request every hour for 24 hours.
Even though we try to call your webhook endpoint multiple times, nothing is 100% guaranteed, so we recommend still having a fallback routine in place. For example for invoices you can use SOAP API’s sent_invoices_status or REST API’s GET /v1/invoices to check for any unfetched or pending invoices, to be sure nothing was left behind in case handling a webhook has failed.
Below you can find examples of the payload we send to your webhook address when something happens. It is possible to add more details, so if you have any ideas what would be useful, just contact Maventa support.
{
"event":"DOCUMENTS.INVOICE.FAILED",
"company_id":"53a4e05d-42f0-4e76-acd6-968ab4558c6f",
"event_timestamp":"2019-11-23T12:03:48+02:00",
"event_data": {
"invoice_id":"da01a81d-1995-440c-971b-7e56c6c10e1d",
"invoice_number":"1001",
"destination":"PEPPOL",
"recipient_name":"Recipient",
"recipient_bid":"933646920",
"error_message": "Error that happened"
}
}
{
"event":"DOCUMENTS.INVOICE.RECEIVED",
"company_id":"53a4e05d-42f0-4e76-acd6-968ab4558c6f",
"event_timestamp":"2019-11-23T12:03:48+02:00",
"event_data": {
"invoice_id":"c154feee-399b-488e-aecd-580578b140e0",
"invoice_number":"1002",
"destination":"PEPPOL",
"recipient_name":"Recipient",
"recipient_bid":"933646920"
}
}
{
"event":"DOCUMENTS.INVOICE.DELIVERED",
"company_id":"53a4e05d-42f0-4e76-acd6-968ab4558c6f",
"event_timestamp":"2019-11-23T12:03:48+02:00",
"event_data": {
"invoice_id":"12f88354-5998-495b-8675-67bf05de60e5",
"invoice_number":"1003",
"destination":"PEPPOL",
"recipient_name":"Recipient",
"recipient_bid":"933646920"
}
}
{
"event": "NETWORKS.PEPPOL.CREATED",
"company_id": "d93a645e-ff69-42d3-88ad-5957ee173b28",
"event_timestamp": "2020-02-04T10:24:47+02:00",
"event_data": {
"network": "PEPPOL",
"profiles": [
"INVOICE_AND_CREDIT_NOTE"
],
"id": "f22c4a82-68a5-44fe-8e53-02ccc657f50d"
}
}
Subscribing to notifications happens through POST /v1/company/notifications endpoint. Once you have authenticated as a company you can call this endpoint to register a webhook for that particular company.
Key | Type | Description |
---|---|---|
destination_type | string | |
destination | string | url |
{
"destination_type": "WEBHOOK",
"destination": "https://your.example/endpoint",
"events": [
"DOCUMENTS.INVOICE.DELIVERED",
"DOCUMENTS.INVOICE.FAILED"
]
}
{
"id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
"destination_type": "WEBHOOK",
"destination": "https://your.example/endpoint",
"events": [
"DOCUMENTS.INVOICE.DELIVERED",
"DOCUMENTS.INVOICE.FAILED"
]
}
{
"destination_type": "WEBHOOK",
"destination": "https://your.example/endpoint?secret=my_secret",
"events": [
"DOCUMENTS.*.*"
]
}
{
"id": "b77cdf0f-4b3b-4d56-b2c8-a7f94d83bd77",
"destination_type": "WEBHOOK",
"destination": "https://your.example/endpoint?secret=my_secret",
"events": [
"DOCUMENTS.*.*"
]
}
{
"destination_type": "WEBHOOK",
"destination": "https://postb.in/1580823541530-123456789",
"events": [
"NETWORKS.*"
]
}
{
"id": "935026df-b548-4260-9c54-4a595a7a9c75",
"destination_type": "WEBHOOK",
"destination": "https://postb.in/1580823541530-123456789",
"events": [
"NETWORKS.*"
]
}
It might be a good idea to include some sort of authorization in your URL to ensure that the messages sent to your endpoint are really from us.
Use can use:
https://user:examplesecret@your-erp.com/webhooks
https://your-erp.com/webhooks?secret=examplesecret
Please note your webhook endpoint needs to support TLS 1.2. Older versions such as SSLv2, SSLv3, TLS 1.0 and TLS 1.1 are not supported.
The Validator API can be used for validation service, which provides XML schema and schematron validations for XML business documents. The service is mainly used for PEPPOL-related documents.
Receivables API is used for Receivables management service. The service helps to automate the debt collection process and is currently available for Finnish customers.
See more information of and integrating instructions for the service in the Integration guide
Detailed technical information in Swagger: Receivables API technical documentation
For using Receivables API the authentication scope receivables:assignments is required.
PUT /v1/services/receivables
to initiate the activation of Receivables Management service.{
"iban": "FI4900000000000000",
"bic": "DABAFIHH",
"bank": "Danske Bank",
"contact_person": "John Doe",
"contact_email": "john.doe@company.fi",
"customer_service_email": "customer_service@company.fi",
"customer_service_phone_number": "05050505",
"contact_phone_number": "04040404",
"authorization_email": "signatureperson@company.fi",
"billing_address": {
"country": "FI",
"streets": [
"Street 1"
],
"city": "Helsinki",
"zip_code": "00100"
},
"postal_address": {
"country": "FI",
"streets": [
"Street 2"
],
"city": "Helsinki",
"zip_code": "00100"
}
}
GET /v1/services/receivables
to fetch the status of the activation to see when the service is activated. Or register a webhook to get a callback notification from Maventa when the service gets activated (or rejected).
{
"iban": "FI4900000000000000",
"bic": "DABAFIHH",
"bank": "Bank 1",
"contact_person": "John Doe",
"contact_email": "john.doe@company.fi",
"customer_service_email": "customer_service@company.fi",
"customer_service_phone_number": "05050505"
"contact_phone_number": "04040404",
"authorization_email": "signatureperson@company.fi",
"billing_address": {
"country": "FI",
"streets": [
"Street 1",
"Street 2"
],
"city": "Helsinki",
"zip_code": "00100"
},
"vfsfi": {
"iban": "FI2357169020052929",
"bic": "OKOYFIHH",
"account_number": "571690-20052929",
"notes": [
{
"phrase": "Olemme siirtäneet laskujen lähettämisen sekä saataviemme eräpäivän jälkeisen seurannan ja sitä koskevat toimenpiteet Visma Financial Solutions Oy:n laskutuspalveluun. Palvelua tai tilausta koskevissa asioissa pyydämme ottamaan yhteyttä suoraan: Yritys Oy , e-mail: customer_service@company.fi. Maksamiseen liittyvissä asioissa pyydämme ottamaan yhteyttä Visma Financial Solutions Oy:n verkkopalveluun tai asiakaspalvelun numeroon 024 808 8020.",
"code": "FI"
},
{
"phrase": "Yritys Oy har externaliserat övervakningen av fordringar till Visma Financial Solutions Oy:s faktureringstjänst. I ärenden som gäller faktureringen ber vi Erta kontakt med faktureringstjänsten per telefon (024 8088020) eller e-post(fsf.asiakaspalvelu@visma.com). Vi ber Er då uppge vår uppdragsgivare samtfakturans nummer. I ärenden som gäller innehållet av tjänsten ellerbeställningen ber vi Er kontakta Yritys Oy , Email: customer_service@company.fi.",
"code": "SV"
},
{
"phrase": "We have transferred the sending of invoices and follow-up of our claims after the due date and measures related thereto to the invoicing service of Visma Financial Solutions Oy. Regarding matters concerning the service or an order, please contact Yritys Oy , e-mail: customer_service@company.fi. Regarding matters concerning invoicing, please contact the invoicing service at tel. +358 24 808 8020 or e-mail fsf.asiakaspalvelu@visma.com. In that case we request you to state the name of our client and the invoice number.",
"code": "EN"
}
]
},
"status": "ACTIVE"
}
More information about the assignments and event usage is explained in the Integration guide
GET /v1/assignments
to list and get all the assignments and their events based on given filtering parameters (e.g. debtor name, assignment creation date, closing date..).GET /v1/assignments/{assignment_id}
to fetch one assignment and it’s events.GET /v1/assignments/{assignment_id}/events
to fetch only events related to the one assignment.GET /v1/assignments/overview
to fetch an overview of assignments (how many assignments are all together open, how many are soon to due and how many are already dued. See an example implementation)POST /v1/assignments/{assignment_id}/events
to add a new event to an assignment (e.g. mark direct payment, request due date change, cancel assignment..)POST /v1/assignments/{assignment_id}/events/{event_id}/seen
to mark event as seenGET /v1/events
to list assignment eventsMaventa Direct Print (also known as Payslip) is a service that enables sending of EPL and PDF files as letters through the printing service in Finland. Service was initially build to send payslip material, but it can be used for sending any kind of letters, as long as the printing service rules are followed.
See more information of the Mass printing service (Payslip) in the Integration guide
Stage: https://payslip-stage.maventa.com
Prod: https://payslip.maventa.com
Use POST /register
to activate the service
Authentication as HTTP headers with on of the following authentication keys:
USERNAME
and USERPW
with which you registered your Direct Print API accountCOMPANY-UUID
and USER-API-KEY
of your Maventa accountUse POST /input_public
to send zip package
Use POST /file_status
to check the status of the sent package