Maventa API

Welcome to the Maventa API page! Here you can find information about Maventa API and instructions to connect your ERP system into Maventa e-invoicing with Maventa API. The page includes documentation, usage examples, and a sandbox to help you with the connection. Get familiar with Maventa API and choose the right API -user form below for the instructions to execute the connection with Maventa e-invoicing.

Before you continue, please, make sure you understand the developer terms of agreement

API Version V1.1. – Other Users

To connect Maventa with V1.1. API version, see the parsing data instructions to execute the connection.
API version v1.1.

What is Maventa API?

Maventa API is the primary means of accessing Maventa’s various e-invoicing services.
It consists of a set of callable SOAP methods defined in their respective API versions and API end-points.

How to use API?

To use Maventa API, first, open a TEST account. The test account is a sandbox in which you can develop your application by using Maventa API.

To perform an action, select calling convention and send a request to its end-point specifying a method and arguments.
After that you will receive a formatted response.

What can Maventa be used for?

Potential application ideas include:

  • Integrating your financial package (SAP, MS Dynamics / Axapta, QuickBooks, Peachtree) to the Maventa Service.
  • Custom import tools (SalesForce, QuickBooks, CSV, etc.)
  • Automatic time-based invoice creation.
  • Accounting, Revenue analysis, Budgeting, Factoring and Claiming Services.
  • External integration with online payment gateways.

API keys and endpoints

Please, conduct all testing in the dedicated testing environment before going live on the production API.

API keys

Maventa API has three different API keys which are used in almost every request.

The keys are:
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**)

*company_uuid is always required, but if the user relates only to one company, the API will collect and fill in your company_uuid for you if you do not submit it. When users are related to multiple companies, company_uuid must be supplied. We suggest you make your integration so that you always supply both user_api_key and company_uuid.

**vendor_api_key is to be used by all partner integrations (ERPs and such with multiple customers). Its purpose is to identify the partner the customer and their transactions “belong” into. This is necessary for correct billing, reporting and support handling. It is very important that Partner and ERP integrations always use their own vendor_api_key in all API calls. Actions performed without supplying vendor_api_key will not be related to any vendor/ partner. All actions submitted without specifying vendor_api_key will be billed directly to related customer, based on general price list.

The vendor_api_key is generated by the partner in the Maventa user interface under the settings page, labeled Software API keys.

Note! The option is only available on partner accounts. When registering on testing environment, you can select to open a partner account directly. For production, when you have created an integration that has been tested, open a regular account and contact our support. We will convert your production account into a partner account which will enable the Software API keys menu.

Partners can create as many vendor_api_keys as needed. Usually, if a partner is developing multiple different ERP systems and wants to get their customer transactions sorted by ERP, a partner wants to have a different vendor_api_key for each ERP. In general, this key is then ”hard-coded” into the software or at least hidden so that a user cannot change it.

If you wish to enable separate testing/production modes on your ERP-integration, please take into a consideration that the testing and production endpoints of the API use different API keys. No API keys from testing will work on production and vice versa. Errors like ”USER NOT FOUND” mean that the user_api_key is wrong for that environment. Please, make sure you are using the correct API endpoint for your API key.

Make sure API keys are written as is and ensure there are no extra blanks before or after the key to avoid errors.

Testing

On the testing server no invoices except for e-mail invoices will be sent. Please, make sure to use e-mail addresses that you own when conducting testing to avoid any confusion (e.g. do not use something like test@test.com since that domain really exists which means that the e-mail address might also exist).

Note! Our current testing environment is used also for our internal testing which means that it differs from the production time to time; There might be new features and fixes that cannot be found from the production yet, features not going to production for a long time, prototypes and temporary issues related to deployments and fixes not working properly.

The database of the testing server may be emptied without notice and the server might be unavailable at times!

Open an account on testing here: Register on Test-Maventa

The SOAP Server Endpoint URL for API version 1.1 developers is available here

Production

The SOAP Server Endpoint URL for API version 1.1 developers is available here

User authentication

Authenticity is verified by a Personal API key, which is validated on each request to the Maventa Webservice.

You can only interact with Maventa API over HTTPS.
The Maventa WSDL, which describes the Maventa API in a machine-readable way, is available at here

Most users will interact with Maventa API using a SOAP toolkit tailored for their language and development environment. Different toolkits will expose the Maventa API in different ways. Please refer to your specific toolkit documentation to understand how to use it. This section illustrates the Maventa API SOAP operations in a toolkit-independent way by exhibiting the XML requests and responses as they appear “on the wire.”

SOAP endpoint

You can send Maventa SOAP messages over SSL secured http protocol to the endpoint. Note that authenticated SOAP requests are only accepted over SSL.

Common elements

You should include the following authorization-related elements (where applicable) with any SOAP request:

user_api_key: The registered user’s API-key (always included in every request)
vendor_api_key: The software vendor’s API-key
company_uuid: The company which the user is acting on behalf (if having many companies)

Encoding

Maventa expects that all content is UTF-8 encoded! Any other format will result as garbage. Maventa does not check or correct your input. Therefore, you must make sure that all information is sent using the correct encoding.

More info about UTF-8 from is available here

Response Content Type

The response indicates the response type in the HTTP Content-Type header.
XML: Content-Type: text/xml;charset=utf-8

Date formats

All dates in Maventa API are strings in Unix epoch YYYYMMDD-format.

This format shall be used when communicating through Maventa API.

Error Return Values

Note! A word with a @-sign in front is a changing variable in the return values.
Return values inside square brackets [ ] are arrays.

All methods can fail with these status errors:

“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

Invoice state values

The following states can be returned as invoice state values.

0 = PENDING – Awaiting delivery (scheduled transmission)
1 = SENT – Invoice sent
2 = DECLINED – Rejected/declined by the recipient (Only e-mail and internal Maventa)
3 = ACCEPTED – Accepted/approved by the recipient (Only e-mail and internal Maventa)
6 = PAID – Invoice marked as paid (Internal Maventa only)
7 = VIEWED – Invoice link opened by the recipient
92 = DISPUTED – Disputed by the recipient (Only internal Maventa)
99 = ERROR – Send error occurred

Invoice layouts

You can specify the invoice layout you wish to use when sending invoices by logging into Maventa, selecting ’settings’ then selecting ’layout settings’.

Available layouts are displayed below. Fields used in the creation of invoices are positioned on the layout as they would appear when delivered to the recipient.

Täytä ja lähetä alla oleva lomake - olemme sinuun mahdollisimman pian yhteydessä.

Jos sinulla on tekninen kysymys, ole hyvä ja tutustu Maventa-asiakastukeen.


Etunimi

Sukunimi

Yritys

Puhelin

Sähköposti