REST API

Maventa REST API covers the following API’s

  • AutoXChange API (sending and receiving invoices, sending and receiving other document types, webhooks, 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 15.02.2024

This example has a collection with all the available 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 the colletion’s Authorization tab, the Type is set to BearerToken and as Token it uses the environment variable access_token which is created when you call the token endpoint.
  • Before creating a token insert mandatory 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. In Tests tab there is a step that sets the access_token from response to a environment variabel.
    • For this endpoint remember set Type to No Auth in the Authorization tab
  • With other endpoints, set 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
    • When storing the token note that it is just a signed JSON so the length is not fixed. Be prepare that the number of characters in token may change
  • 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 UUID (log in to your Maventa account to get it)
  • client_secret = API key (log in to your Maventa account to get it)
  • 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 create companies, send and receive invoices, orders and other trading documents, register webhooks and activate different networks and services such as Peppol or Scan. It also includes Detect, a service that performs automatic checks and analysis on invoices.

Company creation and customer authentication

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 verified to ensure Know Your Customer process has been completed.

You can register webhooks to monitor when company authrization status changes, and when services and networks gets activated.

Service activation and profile registering

Register company as invoice or document receiver and activate services. The endpoint for profile registrations is POST /v1​/company​/profiles

You can also use webhooks to get notifications when the registration status changes.

Networks to register

  • VISMA - Internal invoice receiving. This network needs to be enabled to be able to receive invoices also via other networks like Peppol and scan.
  • PEPPOL - Receiving in the Peppol network. You can register different document types (profiles).
    • ORDER
      • With orders you can also specify the profile version (profile_version) PEPPOLBIS30 or EHF30.
    • ORDER_RESPONSE
    • CATALOGUE
    • CATALOGUE_RESPONSE
    • DESPATCH_ADVICE
    • INVOICE_AND_CREDIT_NOTE
    • REMINDER
    • INVOICE_RESPONSE
    • MESSAGE_LEVEL_RESPONSE
    • INVOICE (DEPRECATED - use INVOICE_AND_CREDIT_NOTE)
    • CREDIT_NOTE (DEPRECATED - use INVOICE_AND_CREDIT_NOTE)
  • BANK - Sending and receiving in the Finnish bank network. Only for Finnish companies. Request to activate is sent automatically when company completes the customer authentication process. Activation takes typically from 1-3 days.
  • SCAN - Receiving from scan service activated via AutoInvoice. Read more about scan service from here.
  • SCAN_DOCUMENTS (or VISMASCANNER) - Receiving other documents than invoices via scan applications (Visma Scanner mobile application, DocScan web application)
    • VOUCHER
  • RECEIVABLES - DEPRECATED - Use PUT /v1/services/receivables for receivables management service activation. Read more about the service from here.
  • INEXCHANGE - Profile for operator InExchange - usage agreed separately.
  • NEMHANDEL - Profile for Nemhandel registrations - usage agreed separately.
  • AISPROOM - Profile for operator Sproom - internal use only.

Profiles not visible in this list are deprecated or in experimental stage. Please contact your integration contact point if you have further questions.

Examples

Below you can find examples of how to register networks and profiles

Examples for enabling invoice receiving
Request:
// Request 1
{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "endpoint_id": "003712345678", 
  // Company's Electronic Invoicing Address (EIA). Not mandatory, you can let API to resolve it.
  "scheme": "V154", 
  // Not mandatory, you can let API to resolve it.
  "network": "VISMA"
}

// Request 2
{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "VISMA"
}
Response:
// Response for both requests
{
  "id": "23c3226e-eaba-423e-8f4d-b1ce85429ab5",
  "status": "pending",
  "profile": "INVOICE_AND_CREDIT_NOTE",
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": null,
  "endpoint_id": "003712345678",
  "scheme": "V154",
  "network": "VISMA"
}
Examples for registering profiles to Peppol network
Request:
// Request 1
{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003712345678", 
  // Company's Electronic Invoicing Address (EIA). Not mandatory, you can let API to resolve it.
  "scheme": "0037", 
  // Scheme ID associated with compnay's EIA. Not mandatory, you can let API to resolve it.
  "network": "PEPPOL"
}

// Request 2
{
"profiles": [
  "ODER"
],
"profile_version": "PEPPOLBIS30",
"network": "PEPPOL"
}
Response:
// #1
{
  "id": "ce2e8bda-355a-4e58-b2be-830c434b8ab9",
  "status": "pending",
  "profile": "INVOICE_AND_CREDIT_NOTE",
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003712345678",
  "scheme": "0037",
  "network": "PEPPOL"
}

// #2
{
  "id": "ce2e8bda-353a-4e58-b4be-832c434b8ab9",
  "status": "pending",
  "profile": "ORDER",
  "profiles": [
    "ORDER"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003712345678",
  "scheme": "0037",
  "network": "PEPPOL"
}

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.

NOTE! Sending or receiving of invoices is not allowed if company_state is unverified (-1) and API will return error message “Unauthorized”. Invoices can be sent after the authorization is done.

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

To receive invoices, register the company first as invoice receiver, like this.

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

  • Use GET /v1/invoices with params 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. You can also use webhooks to get notifications of received invoices.
  • Use GET /v1/invoices/{id} to download the invoice XML file in the specified format, or to download the invoice image.

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

Scan Account

Fraud reporting on received invoices

To work on preventing invoice fraud, Maventa supports functionality to report us receiving of suspected fraudulent invoices.

Integrators can add the reporting functionality into their system to give the users an easy way to do reports in the context of the invoice handling.

See more guidance and example flow for fraud reporting 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 webhooks 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

To receive documents, register first the company as document receiver, like this.

Documents are received by listing new incoming documents in Maventa and then downloading the document and attachments into the financial system.

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

Webhooks

Maventa supports registering 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.
  • COMPANIES.AUTHORIZATION.*
    • When a company’s authorization status changes to either VERIFIED, UNVERIFIED or UNKNOWN.

We expect HTTP 200, 201 or 204 responses when the server has successfully handled the event. If for some reason the response is something else or the server is unavailable we will retry the request every hour for 24 hours.

The requests are expected to finish in under 5 seconds, requests that timeout are considered as failures and will be retried. No long running processing should ever be done in the webhook request.

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"
  }
}
Example for companies authorization
{
  "event": "COMPANIES.AUTHORIZATION.VERIFIED",
  "company_id": "74700284-d794-4fdd-a2ae-d72c3589f7a2",
  "event_timestamp": "2021-10-29T11:33:24+03:00",
  "event_data": {
    "state": "VERIFIED"
  }
}

Registering to receive events via webhooks

Subscribing to events happens through the POST /v1/company/notifications endpoint.

For a single company

Once you have authenticated as a company you can call this endpoint to register a webhook for that particular company.

For all partner’s companies

We have also a possibility to register webhooks for partners (aka vendor webhooks).

When a registration is done for a partner it covers all the companies that have been linked to the partner company’s vendor api key. The registration for a partner is a one time operation, after the registration is active the endpoint registered will receive events for all companies associated with the partner. This is the recommended way for partners to register their webhooks. Linking and unlinking the vendor api key is a requirement for this feature to fully function. More about partner accounts here.

If you want to register webhooks for a partner, authenticate with the partner company credentials and specify destination_type as VENDOR_WEBHOOK when subscribing to the events.

Request
Key Type Description
destination_type string Type of the hook WEBHOOK or VENDOR_WEBHOOK
destination string Endpoint url
For partner’s companies based on vendor key

There is a third posibility to register vendor webhooks based on vendor key.

This registration allows you to filter notifications based on vendor keys. This is helpful if you own multiple vendor api keys, and want notifications separately.

Registering based on vendor keys requires you to pass vendor_key in the payload.

Request
Key Type Description
destination_type string VENDOR_WEBHOOK
destination string Endpoint url
vendor_key string your_vendor_key
Examples
Example registering for a partner company
Request:
{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}
Response:
{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}
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 that the webhook endpoint needs to support TLS 1.2. Older versions such as SSLv2, SSLv3, TLS 1.0 and TLS 1.1 are not supported.

OP Laskulaina - Invoice credit service

Scope for the /oauth2/token: company

See more guidance for OP Laskulaina - Invoice credit service in Integration guide

Detect service

Scope for the /oauth2/token: analysis

See more guidance for Detect service in Integration guide

Definitions used by the API

You will find more information about the data type definitions used by this API from /v1/definitions namespace.

Some of these methods are publicly available, others will require an authenticated API user.

Validator API

The Validator API can be used for validation service, which provides XML schema and schematron validations for XML business 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

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

Service levels

  • use GET /v1/service_levels to list the service levels for all of your customers. This method will only return customers that have a special service level set (premium, vip or service_bypass), the default service level is named “default” and that applies to every customer that does not have a service level. There is no way to list customers with the default service level.
  • use GET /v1/service_levels/{customer_bid} to get service level for specific customer (with customer bid)
  • use PATCH /v1/service_levels/{customer_bid} to set service level for customer (with customer bid)

Messaging functionality

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