Getting Started
Maventa SOAP API covers:
- invoice sending and receiving
- company set up and configuration
Get familiar with the API and usage examples and start building your integration. Before you continue, make sure you have read our Integration guide and understand the Partner Agreement
We recommend new integrations to use the Maventa REST API instead of the SOAP API.
While there are no concrete plans for deprecating the SOAP API, we are focusing our development efforts on the REST API and new features will primarily be added there.
Also existing integrations are advised to be moved to the REST API. It is possible to use both APIs simultaneously so you can do the move in your own schedule, method by method.
How to start
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.
Endpoints
You can send Maventa SOAP messages over SSL secured HTTP protocol to the endpoints below.
The Maventa WSDL, which describes the Maventa API in a machine-readable way, is available for
- Testing at
https://testing.maventa.com/apis/v1.1/wsdl - Production at
https://secure.maventa.com/apis/v1.1/wsdl
Authentication
Authenticity is verified by a Personal API key, which is validated on each request to the Maventa Webservice.
See API keys for more information of the keys and how to get them.
Firewall and ports
Our service operates on the following endpoints:
https://testing.maventa.com:443https://secure.maventa.com:443
All communication is on port 443 (over SSL). There is no firewall whitelisting required from our side, you can connect from anywhere as soon as you have the API keys.
Encoding
Maventa SOAP API expects that all content is UTF-8 encoded, using any other encoding will result in broken characters. Maventa does not check or correct your input. Therefore, you must make sure that all information is sent using the correct encoding.
For invoice XML please see the XML format specific guidelines for the correct encoding. In example Finvoice is encoded as ISO 8859-15.
Response Content Type
The response indicates the response type in the HTTP Content-Type header.
Content-Type: text/xml;charset=utf-8
Date formats
All dates in Maventa API are strings in YYYYMMDD-format. For example 20250131.
This format shall be used when communicating through Maventa API.
Error return values
All methods can fail with these status errors:
| Error | Description |
|---|---|
| ERROR: VENDOR API KEY DISABLED | Software vendor has disabled the use of this vendor api key |
| ERROR: USER NOT ACTIVATED | User account must be activated by visiting the activation link in the activation email |
| ERROR: USER HAS NO RIGHTS TO COMPANY | Current user has no rights to company with id given in company_uuid
|
| ERROR: USER BELONGS TO MULTIPLE COMPANIES, NO COMPANY ID GIVEN | No company_uuid given |
| ERROR: USER NOT FOUND | API key not found |
| ERROR: COMPANY NOT FOUND | Given company_uuid not found |
| ERROR: COMPANY ACCOUNT IS LOCKED | Company’s account has been locked for some reason (e.g. too many disputes) |
| ERROR: COMPANY HAS NOT COMPLETED FIRST TIME WIZARD | API won’t work until the user that registered for Maventa has completed the first time wizard |