REST API

Maventa REST API covers the following API’s

  • AutoXChange API (sending and receiving invoices, sending and receiving other document types, callback notifications, Detect Service)
  • Validator API (validating invoices and other documents)
  • Receivables API (Receivables Management Service)
  • Payslip API (Mass Printing service)

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 start

Integration set up

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.

Technical documentation in Swagger

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.

AutoXChange Postman example

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:

  • Import the collection and example environment from button below
  • Variables 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
  • Insert correct values to EXAMPLE_ENVIRONMENT’s variables (scope, client_id, client_secret, vendor_api_key)
  • Call POST /oauth2/token endpoint to get access_token environment variable created to your environment variables
  • When calling other endpoints, set authorization type to Inherits auth from the parent

Authentication

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.

  • When starting a session, request for an authentication token via POST /oauth2/token
  • Store the token locally, and set it to expire in given time before the server side value returned in response as seconds in expires_in field
    • Use the token until the stored validity time is reached, and then request a new token
  • Build in graceful authentication error handling
    • Prepare to handle possible token expiry errors even though using the client side expiry time, by requesting a new token
    • Handle token access and token unauthorized/expired scenarios differently (if token granted per client id&secret does not grant access to given resource, asking for a new token will not help)

Authenticate as a company

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:

  • client_id = company_id
  • client_secret = user_api_key
  • vendor_api_key

Notes:

  • Currently only one level of user rights, admin, is supported. So all authenticated users will be granted with admin rights
  • For Maventa company authentication, the scope does not need to be provided

Authenticate as an operator

Call the POST /oauth2/token method with operator credentials:

  • client_id = operator_id
  • client_secret = operator_secret

Error handling

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

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.

Invoice Exchange

Invoice sending

Invoices are sent by providing an XML file and specifying other necessary data for send as parameters on the api call.

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.

Invoice receiving

Invoices are received by listing new incoming invoices in Maventa and then downloading the invoice and attachments into the financial system.

See more guidance and recommended routine for invoice receiving in Integration guide

Document Exchange

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.

Document sending

Documents are sent by sending a document file, usually an XML, and specifying other necessary data as parameters on the api call.

  • Use POST /v1/documents to send a document, getting back a document ID in return
  • Use GET /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 states

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

Document receiving

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

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

List and download documents
  • Use GET /v1/documents with params 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.
  • Use GET /v1/documents/{id} to download the document

Callback notifications

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:

  • DOCUMENTS.*.DELIVERED
    • Happens when we complete send to the given route
  • DOCUMENTS.*.DELIVERY_CONFIRMED
    • Happens when we get a positive response from the recipient operator
    • We do not have this for many routes, so not maybe yet a feasible one to listen to only currently
    • For example: Handled by Nets
  • DOCUMENTS.*.FAILED
    • Happens when we get a final error.
    • This can happen after the DELIVERED event.
  • DOCUMENTS.*.RECEIVED
    • Happens when your company receives a document
  • NETWORKS.*
    • Events on different network registrations, such as BANK, SCAN, and PEPPOL. Event types can be CREATED, ENABLED, or DISABLED. So for example an event where Bank network request is sent, is NETWORKS.BANK.CREATED, and the following event after the bank network is opened is NETWORKS.BANK.ENABLED.

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.

Example payloads

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.

Example for failed invoice 
{
  "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"
      }
}
Example for received invoice 
{
  "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"
      }
  }
Example for delivered invoice 
{
  "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"
      }
  }
Example for created network 
{
  "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"
  }
}

Registering to receive notifications

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.

Request
Key Type Description
destination_type string  
destination string url
Examples
Example registering for DELIVERED and FAILED events for invoices
Request: 
{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}
Response: 
{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}
Example registering for all events for all document types
Request: 
{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint?secret=my_secret",
  "events": [
    "DOCUMENTS.*.*"
  ]
}
Response: 
{
  "id": "b77cdf0f-4b3b-4d56-b2c8-a7f94d83bd77",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint?secret=my_secret",
  "events": [
    "DOCUMENTS.*.*"
  ]
}
Example registering for all networks and all event types
Request: 
{
  "destination_type": "WEBHOOK",
  "destination": "https://postb.in/1580823541530-123456789",
  "events": [
    "NETWORKS.*"
  ]
}
Response: 
{
  "id": "935026df-b548-4260-9c54-4a595a7a9c75",
  "destination_type": "WEBHOOK",
  "destination": "https://postb.in/1580823541530-123456789",
  "events": [
    "NETWORKS.*"
  ]
}

Security

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:

  • Basic access authentication
    Example: https://user:examplesecret@your-erp.com/webhooks
  • Secret in the URL parameters
    Example: 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.

Validator API

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

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.

To activate the service

  • Use PUT /v1/services/receivables to initiate the activation of Receivables Management service.
Example of parameters in PUT /v1/services/receivables
Request: 
{
  "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"
  }
}
Response:
  • Use 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).
Example response of the GET profile for receivables
Request:
Response: 
{
  "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"
}

Assignments and assignments’ events

More information about the assignments and event usage is explained in the Integration guide

  • use 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..).
  • use GET /v1/assignments/{assignment_id} to fetch one assignment and it’s events.
  • use GET /v1/assignments/{assignment_id}/events to fetch only events related to the one assignment.
  • use 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)
  • use 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..)
  • use POST /v1/assignments/{assignment_id}/events/{event_id}/seen to mark event as seen
  • use GET /v1/events to list assignment events

Payslip API

Maventa 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 account
  • COMPANY-UUID and USER-API-KEY of your Maventa account

Use POST /input_public to send zip package

Use POST /file_status to check the status of the sent package