SOAP API

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

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.

Endpoints

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

The Maventa WSDL, which describes the Maventa API in a machine-readable way, is available for

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

  • https://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

When interacting with Maventa, 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.

For invoice XML please see the XML format specific guidelines for the correct encoding. In example Finvoice is encoded as ISO 8859-15.

More info about UTF-8 from is available at utf-8.com

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

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

API methods

Updated lists of most relevant methods that are useful for new integrations.
Detailed information of each method.

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

Account configuration

Register, activate and fetch information about companies, view and set settings for a company.
Link and unlink companies to vendors. Integration guide for companies and settings

Create, list, show, update and delete users.

Create, list, show,update and delete company postal addresses.

Order, show and disable a scan account. Integration guide for scanning

Invoice Receiving

Get necessary details to receive all the invoices successfully. Integration guide for invoice receiving

Invoice Sending

Find out if a company can receive electronic invoices through Maventa or through external operators.
Send invoices successfully and get statuses. Integration guide for invoice sending

B2C

Norway

Finland

Useful stuff

Methods to help you out when starting to build integration.

Details

Here are details of all the recommended SOAP API methods.

b2c_issuer_agreement_order_with_ocr

For opening Norwegian B2C agreement together with agreement capture (requires OCR agreement).

Input is name and email address of a person with rights to accept such an agreement on behalf of the company, OCR account number, OCR kid length, OCR reference position. That email address will receive the agreement by email as PDF and a link to accept the agreement with (Note! Does not require login). Read more about consumer invoicing in Norway

/v1.1/api/b2c_issuer_agreement_order_with_ocr

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
signer_name string  
signer_email string  
ocr_account_number string Bank account number for receiving payments (11 digits)
ocr_kid_length string Number of digits in the KID number, including control number
ocr_reference_position string Position of the electronic invoice reference inside the KID number. The position of the electronic invoice reference is normally the customer number on the invoice. For example, if your KID length is 17 digits, and your customer number is the first five digits in the KID, the position would be 1-5.
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:b2c_issuer_agreement_order_with_ocr soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <signer_name xsi:type="xsd:string">?</signer_name>
         <signer_email xsi:type="xsd:string">?</signer_email>
         <ocr_account_number xsi:type="xsd:string">?</ocr_account_number>
         <ocr_kid_length xsi:type="xsd:string">?</ocr_kid_length>
         <ocr_reference_position xsi:type="xsd:string">?</ocr_reference_position>
      </sec:b2c_issuer_agreement_order_with_ocr>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: Email sent to @signer_email
ERROR: NO RIGHTS (Only admin user can order the agreement)
ERROR: signer_name or signer_email missing or invalid
ERROR: ocr_account_number is invalid
ERROR: ocr_kid_length is invalid
ERROR: ocr_reference_position syntax is invalid
ERROR: Bid check towards Nets failed
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""

puts server.b2c_issuer_agreement_order_with_ocr(api_keys, "John Doe", "john@company.doe", "32234756777", "10000", "1-3")

b2c_issuer_agreement_order

For opening Norwegian B2C agreement for a company. Input is name and email address of a person with rights to accept such an agreement on behalf of the company.

That email address will receive the agreement by email as PDF and a link to accept the agreement with (Note! Does not require login).

Read more about consumer invoicing in Norway

/v1.1/api/b2c_issuer_agreement_order

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
signer_name string  
signer_email string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:b2c_issuer_agreement_order soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <signer_name xsi:type="xsd:string">?</signer_name>
         <signer_email xsi:type="xsd:string">?</signer_email>
      </sec:b2c_issuer_agreement_order>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: Email sent to @signer_email
ERROR: NO RIGHTS (Only admin user can order the agreement)
ERROR: signer_name or signer_email missing or invalid
ERROR: ocr_account_number is invalid
ERROR: ocr_kid_length is invalid
ERROR: ocr_reference_position syntax is invalid
ERROR: Bid check towards Nets failed
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""
api_keys[:vendor_api_key] = ""

puts server.b2c_issuer_agreement_order(api_keys, "John Doe", "john@company.doe")

company_invoice_receiving

Enable/disable receiving of invoices. Read more about invoice receiving

/v1.1/api/company_invoice_receiving

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
receive boolean  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:company_invoice_receiving soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <receive xsi:type="xsd:boolean">?</receive>
      </sec:company_invoice_receiving>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:company_invoice_receivingResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:company_invoice_receivingResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK
ERROR: USER NOT FOUND
ERROR: INVOICE RECEIVING CANNOT BE DISABLED WHEN SCAN ACCOUNT IS OPEN
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

puts server.company_invoice_receiving(api_keys, true)

enable_operator

Enables operator connections that require it done separately. Currently needed for PEPPOL receiving.

/v1.1/api/enable_operator

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

operator_struct OperatorStruct

Key Type Description
operator_id string Operator name/code. For peppol network use PEPPOL
enabled boolean Enable or disable. When set to false, will remove both invoice and credit note receiving
sender_id string Sender ID if needed (not needed for PEPPOL)
recipient_id string Recipient ID if needed (not needed for PEPPOL)
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:enable_operator soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <operator_struct xsi:type="sec:OperatorStruct">
            <!--You may enter the following 4 items in any order-->
            <recipient_id xsi:type="xsd:string">?</recipient_id>
            <sender_id xsi:type="xsd:string">?</sender_id>
            <enabled xsi:type="xsd:boolean">?</enabled>
            <operator_id xsi:type="xsd:string">?</operator_id>
         </operator_struct>
      </sec:enable_operator>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
status string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:enable_operatorResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:enable_operatorResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK
ERROR: USER NOT FOUND
ERROR: [OPERATOR] CANNOT BE ENABLED WHILE RECEIVING INVOICES IS DISABLED
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

operator = Hash.new
operator[:operator_id] = "PEPPOL"
operator[:enabled] = true

puts server.enable_operator(api_keys, operator)

company_list

Used for listing all the companies user has access to.

/v1.1/api/company_list

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:company_list soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:company_list>
   </soapenv:Body>
</soapenv:Envelope>

Output

return CompanyParamsOutArray (Array of CompanyParamsOut)

Key Type Description
email string  
status string  
user_api_key string  
name string  
maventa_uuid string  
maventa_id string  
bid string  
id string  
country string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:company_listResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return n2:arrayType="n1:CompanyParamsOut[19]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
            <item>
               <maventa_id xsi:type="xsd:string">FI-000012345678-23134-8</maventa_id>
               <country xsi:type="xsd:string">FI</country>
               <name xsi:type="xsd:string">Test Company</name>
               <id xsi:type="xsd:string">c8fb304f-bd25-49d6-8678-776951f14e7b</id>
               <bid xsi:type="xsd:string">FI12345678</bid>
               <status xsi:type="xsd:string">OK</status>
               <email xsi:type="xsd:string">test.comp@company.com</email>
            </item>
         </return>
      </n1:company_listResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: USER NOT FOUND
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

results = server.company_list(api_keys)

if results[0].status == "OK"
  results.each do |result|
    puts result.id, result.name, result.bid, result.email, result.country
  end
end

company_lookup_with_operator

Used for finding recipient’s invoicing information. Differs from company_lookup only by returning also operator_code inside ‘edis’ value.

Read more about recipient look-up

/v1.1/api/company_lookup_with_operator

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

company_lookup_params CompanyLookupParams

Key Type Description
search_string string Search string can be company name, BID (organisation number), VAT code or e-invoice address (EDI, OVT, EAN, GLN…)
country_code string Limit hits to specific country. If left blank, returns hits from all countries
limit int Maximum number of results to return, default 20 and maximum 200
disable_vies boolean Disable external directory lookup fallback when no results from Maventa Network. If set to false or left blank, Maventa will do queries on external services if no match is found in Maventa Finder, this might slow down query.
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:company_lookup_with_operator soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <company_lookup_params xsi:type="sec:CompanyLookupParams">
            <!--You may enter the following 4 items in any order-->
            <search_string xsi:type="xsd:string">?</search_string>
            <limit xsi:type="xsd:int">?</limit>
            <country_code xsi:type="xsd:string">?</country_code>
            <disable_vies xsi:type="xsd:boolean">?</disable_vies>
         </company_lookup_params>
      </sec:company_lookup_with_operator>
   </soapenv:Body>
</soapenv:Envelope>

Output

api-company_lookup_with_operatorResponse CompanyLookupOutExtendedArray

Key Type Description
status string  
edis ElectronicInvoiceAddressArray ElectronicInvoiceAddress content is two strings, ‘eia’ with the electronic invoice address and ‘operator_code’
name string  
state string  
post_code string  
post_office string  
maventa_id string  
bid string  
address1 string  
country string  
address2 string  
receive_invoices boolean Can only be true for Maventa network users (e.g. maventa_id field is not blank), for all others this is always false and does not necessarily mean they cannot receive e-invoices
receive_orders boolean Only applies for Maventa network users
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:company_lookup_with_operatorResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return n2:arrayType="n1:CompanyLookupOutExtended[3]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
            <item>
               <state xsi:type="xsd:string"/>
               <address2 xsi:type="xsd:string">Company address 1_2</address2>
               <receive_invoices xsi:type="xsd:boolean">true</receive_invoices>
               <country xsi:type="xsd:string">FI</country>
               <edis n2:arrayType="n1:ElectronicInvoiceAddress[1]" xsi:type="n2:Array">
                  <item>
                     <operator_code xsi:type="xsd:string">003721291126</operator_code>
                     <eia xsi:type="xsd:string">003733686731</eia>
                  </item>
               </edis>
               <address1 xsi:type="xsd:string">Company address 1</address1>
               <name xsi:type="xsd:string">Test Company 1_1</name>
               <bid xsi:type="xsd:string">3368673-1</bid>
               <post_office xsi:type="xsd:string">Helsinki</post_office>
               <receive_orders xsi:type="xsd:boolean">false</receive_orders>
               <maventa_id xsi:type="xsd:string">FI-000000001337-76666-4</maventa_id>
               <status xsi:type="xsd:string">OK</status>
               <post_code xsi:type="xsd:string">00100</post_code>
            </item>
            <item>
               <state xsi:type="xsd:string"/>
               <address2 xsi:type="xsd:string">Company address 2_2</address2>
               <receive_invoices xsi:type="xsd:boolean">false</receive_invoices>
               <country xsi:type="xsd:string">FI</country>
               <edis n2:arrayType="n1:ElectronicInvoiceAddress[1]" xsi:type="n2:Array">
                  <item>
                     <operator_code xsi:type="xsd:string">003721291126</operator_code>
                     <eia xsi:type="xsd:string">003787486612</eia>
                  </item>
               </edis>
               <address1 xsi:type="xsd:string">Company address 2_1</address1>
               <name xsi:type="xsd:string">Test Company 2</name>
               <bid xsi:type="xsd:string">8748661-2</bid>
               <post_office xsi:type="xsd:string">Helsinki</post_office>
               <receive_orders xsi:type="xsd:boolean">false</receive_orders>
               <maventa_id xsi:type="xsd:string">FI-0008748661-2-34137-8</maventa_id>
               <status xsi:type="xsd:string">OK</status>
               <post_code xsi:type="xsd:string">00100</post_code>
            </item>
         </return>
      </n1:company_lookup_with_operatorResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: NO RESULTS
ERROR: TOO MANY RESULTS If result set contains more than 200 hits
ERROR: SEARCH STRING BLANK OR TOO SHORT (MIN 3 CHARS)
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

search_struct = Hash.new
search_struct[:search_string] = "FI1234567"
search_struct[:disable_vies] = true
search_struct[:limit] = 20

results = server.company_lookup_with_operator(api_keys, search_struct)

if results[0].status == "OK"
  results.each do |result|
    puts result.name, result.bid, result.address1, result.post_code,
    result.post_office, result.country
    result.edis.each do |edi_code|
      puts "#{edi_code.eia}@#{edi_code.operator_code}"
    end
  end
end

company_show

Used for showing current company information.

Read more about companies and settings

/v1.1/api/company_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:company_show soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:company_show>
   </soapenv:Body>
</soapenv:Envelope>

Output

return CompanyParamsOut

Key Type Description
email string  
status string  
name string  
maventa_id string  
bid string  
id string  
country string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:company_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:CompanyParamsOut">
            <maventa_id xsi:type="xsd:string">FI-000012345678-23134-8</maventa_id>
            <country xsi:type="xsd:string">FI</country>
            <name xsi:type="xsd:string">Test Company</name>
            <id xsi:type="xsd:string">c8fb304f-bd25-49d6-8678-776951f14e7b</id>
            <bid xsi:type="xsd:string">FI12345678</bid>
            <status xsi:type="xsd:string">OK</status>
            <email xsi:type="xsd:string">test.comp@company.com</email>
         </return>
      </n1:company_showResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: USER NOT FOUND
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.company_show(api_keys)

if result.status == "OK"
  puts result.id, result.name, result.bid, result.email, result.country
end

configure_company

Used for updating company settings.

Read more about companies and settings

/v1.1/api/configure_company

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

settings SettingValueArray

Key Type Description
website string Website of company, displayed on invoice (depending on sending format)
print_and_send_request int Print&Send enabled request (1=yes,0=no)
print_and_send_letter_class integer Print&Send mail class (1 = Priority, 0 = Economy). Only available for FI and NL companies!
print_and_send_own_pdf boolean Use own PDF images in Print&Send.
print_and_send_color boolean Print with colors in Print&Send
print_attachments_disabled boolean Disable printing of attachments (true = disabled, false = enabled) Note! This setting applies only for NO and NL companies!
email_remind_freq int Frequency of email reminder’s for open invoices in days (e.g. 2)
email string Company email
invoice_email string Company invoice email (inbound invoice notifications)
errors_to_user int Send invoice relay errors to users or just error email? (1=yes,0=no)
error_emails string List of comma separated error emails to notify of invoice relay errors
reports int E-mail reports activated (0 = no, 1 = weekly, 2 = monthly, 3 = daily)
reports_emails string List of comma separated email addresses to send reports to
name string Name of company
bid string Business ID, VAT, organization number etc.
country string Country of company
stop_duplicates boolean Prevent (re)sending invoices with the same number
notify_incoming boolean Enable/disable email notification of incoming invoice. Will be sent to invoice email if defined, else company email
disable_email boolean Enable/disable sending of invoices by email notification. If this is set to true, invoices will only go out as e-invoices or by print. If the only available route for an invoice is email, the invoice will go to error state
notifications_disabled int Enable/disable all e-mail notifications to the company email address, (1=disable, 0=enable)
internal_receive_via_peppol boolean Enable/disable internal receive via Peppol. When enabled, all invoices received from companies inside the home network will be converted to EHF/ PEPPOL BIS, routed through the PEPPOL network and validated towards PEPPOL validation rules. If the invoice fails PEPPOL validation, sender will receive an error message and the invoice will not be delivered.
send_email_attachments int With this option we add the invoice image (as PDF) and other attachments on your invoices which get sent by email (total size max 5 megabytes, if larger, recipient is asked to download the attachments from our service using a link provided). Note! You will not get an acknowledgement of receival when sending attachments like for normal email invoices. Also note that when sending attachments the recipient’s email box might get full and then emails are not delivered.
send_invoice_email int With this option you can decide how the email invoice is sent out. 0 = Do not send invoice via email. 1 = send all invoice e-mails with attachments (max size 5MB). 2 = Send all invoice e-mail with invoice objections. 3 = Send all invoice e-mails with a link to download PDF. Note! This setting will override send_email_attachments and disable_email settings
receive_finvoice2 int Enable/disable receiving finvoice 2.x. With this option you can make both the API and UI return Finvoice documents with version 2.0 and higher. When off, it will return version 1.3 or earlier.
invoice_receiving int Enable/disable invoice receiving, (1=enabled, 0=disabled).
invoicing_eia string invoicing EIA (Billing information: The delivery method priority is following 1 = einvoice, 2 = email, 3 = print, if all below values are given. If company prefers invoicing via normal post, invoicing_eia, invoicing_operator and invoicing_email should be left blank).
invoicing_operator string invoicing operator.
invoicing_email string invoicing email address.
invoicing_street_address1 string invoicing postal address.
invoicing_street_address2 string invoicing additional postal address.
invoicing_post_code string invoicing post code.
invoicing_post_office string invoicing post office.
billing_company_id string Company to be set as a billing company.
message_from_sender string Only for Norway. Write a message to the invoice receivers that is visible in the recipients e-mail. Note! If your ERP supports their own message to receiver, the message in the ERP will overwrite this message.
b2c_fallback string Only for B2C NO, can be print or email
b2c_reminder boolean Enable/disable B2C NO reminders
contact_person string Contact person, email and phone are shown in the email message when invoice is sent by email
contact_email string Contact person, email and phone are shown in the email message when invoice is sent by email
contact_phone string Contact person, email and phone are shown in the email message when invoice is sent by email
scan_notification_interval string Supplier Activation e-mail interval (Use one of the following to activate the service: ”monthly”, ”weekly”, ”daily”, or to disable the service use something else for example ”disabled”)
scan_notification_email string E-mail address for Supplier Activation e-mail delivery
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:configure_company soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_meta xsi:type="xsd:string">?</license_meta>
            <license_key xsi:type="xsd:string">?</license_key>
         </api_keys>
         <settings xsi:type="sec:SettingValueArray" soapenc:arrayType="sec:SettingValue[1]">
            <item>
              <key xsi:type="xsd:string">website</key>
              <value xsi:type="xsd:string">www.comp.com</value>
            </item>
         </settings>
      </sec:configure_company>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:configure_companyResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:configure_companyResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK Settings saved successfully
ERROR: NO RIGHTS TO CHANGE SETTINGS Only admin user can change settings
ERROR: COULD NOT SAVE SETTINGS Could not save settings for unknown reason
ERROR: BILLING EMAIL ADDRESS INVALID Email address is not valid
ERROR: BILLING INFORMATION INCOMPLETE Invoicing postal address is incomplete; address, postcode or postoffice is missing
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

settings = [
    {:key => "notify_incoming", :value => "true"},
    {:key => "stop_duplicates", :value => "true"},
    {:key => "name", :value => "MyNewName"},
    {:key => "email", :value => "newemail@company.no"},
    {:key => "invoice_email", :value => "newinvoiceemail@company.no"},
    {:key => "email_remind_freq", :value => "5"},
    {:key => "errors_to_user", :value => "1"},
    {:key => "reports", :value => "2"},
    {:key => "error_emails", :value => "firsterroremail@company.no,seconderroremail@company.no"},
    {:key => "reports_emails", :value => "firstreportemail@company.no,secondreportemail@company.no"},
    {:key => "website", :value => "www.maventa.no"},
    {:key => "print_and_send_request", :value => "1"},
    {:key => "print_and_send_letter_class", :value => "2"},
    {:key => "print_and_send_own_pdf", :value => "true"},
  {:key => "disable_email", :value => "false"}
]
puts server.configure_company(api_keys, settings)

consumer_agreement_status

Checking status of an existing consumer agreement.

Read more about consumer invoicing in Norway

/v1.1/api/consumer_agreement_status

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
reference_nr string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:consumer_agreement_status soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <reference_nr xsi:type="xsd:string">?</reference_nr>
      </sec:consumer_agreement_status>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:consumer_agreement_statusResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: NEW</return>
      </n1:consumer_agreement_statusResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: @status One of REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR. Status of ACTIVE means the consumer is ready to receive invoices
ERROR: CONSUMER NOT FOUND
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""

puts server.consumer_agreement_status(api_keys, "20141113014")

consumer_agreements_query

Checking status of existing agremeents.

Read more about consumer invoicing in Norway

/v1.1/api/consumer_agreements_query

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

query ConsumerAgreementQuery

Key Type Description
name string  
phone string  
email string  
state string One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR
reference_nr string  
customer_nr string  
timestamp string Format YYYYMMDDHHMMSS (For example 20180401152042)
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:consumer_agreements_query soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <query xsi:type="sec:ConsumerAgreementQuery">
            <!--You may enter the following 7 items in any order-->
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <state xsi:type="xsd:string">?</state>
            <customer_nr xsi:type="xsd:string">?</customer_nr>
            <name xsi:type="xsd:string">?</name>
            <timestamp xsi:type="xsd:string">?</timestamp>
            <reference_nr xsi:type="xsd:string">?</reference_nr>
         </query>
      </sec:consumer_agreements_query>
   </soapenv:Body>
</soapenv:Envelope>

Output

return ConsumerAgreementQueryResponse

Key Type Description
status string  
agreements ConsumerInfoOutArray Array of ConsumerInfoOut

agreements ConsumerInfoOutArray

Key Type Description
state string One of REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR
name string  
phone string  
email string  
reference_nr string  
customer_nr string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:consumer_agreements_queryResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:ConsumerAgreementQueryResponse">
            <agreements n2:arrayType="n1:ConsumerInfoOut[1]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <state xsi:type="xsd:string">NEW</state>
                  <customer_nr xsi:type="xsd:string">00123456</customer_nr>
                  <name xsi:type="xsd:string">Tester Testersson</name>
                  <phone xsi:nil="true"/>
                  <reference_nr xsi:type="xsd:string">00123456</reference_nr>
                  <email xsi:nil="true"/>
               </item>
            </agreements>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:consumer_agreements_queryResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: Timestamp format error
ERROR: No agreements found
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""

query = Hash.new
query[:name] = "Test Consumer 1"

result = server.consumer_agreements_query(api_keys, query)
if result.status == "OK"
 result.agreements.each do |agreement|
  puts agreement.reference_nr
  puts agreement.customer_nr
 end
else
 puts result.status
end

disable_b2c_issuer_agreement

For closing Norwegian B2C agreement for a company.
The agreement can be disabled only if it is CONFIRMED. User cannot disable a PENDING agreement.

Read more about consumer invoicing in Norway

/v1.1/api/disable_b2c_issuer_agreement

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

Sorry, there is no example available for this method.

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK
ERROR: NO RIGHTS Only admin user can disable the agreement
ERROR: Company agreement not found
ERROR: Cannot disable agreement. Issuer state is #{status}
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/attachment'
require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""
api_keys[:vendor_api_key] = ""

puts server.disable_b2c_issuer_agreement(api_keys)

For preparing consumer agreement without actually sending invoices. Can be used to mass-prepare consumer registry for a coming invoice batch.

Consumer will get either SMS or email depending on what information is given (SMS preferred if both) with a link to Nets’ service where they can login using BankID and accept the agreement.

Read more about consumer invoicing in Norway

/v1.1/api/get_consumer_link

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

consumer_info ConsumerInfoIn

Key Type Description
name string  
phone string International format, e.g. +4712341234
email string  
country string  
reference_nr string Efakturaref, can be left blank, in that case one will be generated based on the customer_nr
customer_nr string Mandatory and unique for company
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:get_consumer_link soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <consumer xsi:type="sec:ConsumerInfoIn">
            <!--You may enter the following 6 items in any order-->
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <country xsi:type="xsd:string">?</country>
            <customer_nr xsi:type="xsd:string">?</customer_nr>
            <name xsi:type="xsd:string">?</name>
            <reference_nr xsi:type="xsd:string">?</reference_nr>
         </consumer>
      </sec:get_consumer_link>
   </soapenv:Body>
</soapenv:Envelope>

Output

return ConsumerLinkResponse

Key Type Description
status string  
message string  
reference_nr string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK Means that agreement is already in place.
For OK status there can be an additional message attribute with values:
- Link already exists for given reference
- Consumer has accept all flag, agreement created
PENDING Means that agreement is waiting for acceptance from consumer.
For PENDING status there can be an additional message attribute with these values:
- Sent agreement to consumer for acceptance
ERROR: B2C agreement is not opened
ERROR: customer_nr missing
ERROR: Invalid reference_nr, only numbers allowed
ERROR: Invalid reference_nr, check digit mismatch
ERROR: Invalid phone number
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""

consumer_info = Hash.new
consumer_info[:name]         = "Test Consumer 1"
consumer_info[:phone]        = "+4755512345"
consumer_info[:email]        = "test.consumer@mail.tst"
consumer_info[:country]      = "NO"
consumer_info[:reference_nr] = ""
consumer_info[:customer_nr]  = "20141113014"

result = server.get_consumer_link(api_keys, consumer_info)
puts "#{result.status}: #{result.message}"

hello_world

Can be used for testing the connection to the API.

/v1.1/api/hello_world

Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:hello_world soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:hello_worldResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">Hello from Maventa API v1.1</return>
      </n1:hello_worldResponse>
   </env:Body>
</env:Envelope>

Examples
Example Ruby implementation

require 'soap/wsdlDriver'
server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

puts server.hello_world

invoice_download

Used for downloading company’s received invoices.

Read more about invoice receiving

/v1.1/api/invoice_download

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string invoice id
xmlformat array Specify 1-n formats for download. If the original file being downloaded is any of the specified formats, the original file is returned. Otherwise the first format of the array is returned.
Supported formats:
finvoice
finvoice20
finvoice30
oio
teapps
teapps30
ubl
liinos
svefaktura
sedi
ehf
ehf20
vismaxml
vismaxml60
e2b
woodx
axflow
facturae
bgc
peppolbis20
peppolbis30
siubl
siubl12
siubl20
vismaubl
vismaubl30
include_metadata boolean Return invoice related information in the metadata. See the fields included in the metadata from the example response below
options InvoiceDownloadOptionsArray Array Of InvoiceOptions

options InvoiceDownloadOptionsArray

Key Type Description
generate_image_if_missing boolean If there is no original invoice image specified, setting this to true creates a custom Maventa invoice image pdf based on the invoice xml data. False by default.
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_download soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <user_api_key xsi:type="xsd:string">filtered</user_api_key>
            <vendor_api_key xsi:type="xsd:string">filtered</vendor_api_key>
            <company_uuid xsi:type="xsd:string">filtered</company_uuid>
         </api_keys>
         <invoice_id xsi:type="xsd:string">12345678-90ab-cdef-1234-567890abcdef</invoice_id>
         <xmlformat xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[]">
            <xsd:string>teapps</xsd:string>
            <xsd:string>finvoice</xsd:string>
            </xmlformat>
         <include_metadata xsi:type="xsd:boolean">true</include_metadata>
         <options xsi:type="sec:InvoiceDownloadOptionArray" soapenc:arrayType="sec:InvoiceDownloadOption[]">
            <item>
               <value xsi:type="xsd:string">false</value>
               <key xsi:type="xsd:string">generate_image_if_missing</key>
            </item>
         </options>
      </sec:invoice_download>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
status string  
attachments FileAttachmentArray Array of attachments. Contains always the invoice xml. For xml formats not supporting embedded attachments, image and attachments are returned as separate objects. For xml formats supporting embedded attachments, the original attachments are returned only embedded to the xml file. With the exception that if the generate_image_if_missing is set as true, then the image we have created will be returned as a separate attachment, and not embedded into the xml file.
metadata InvoiceDownloadMetadata Information about the invoice, that may be used for invoice handling related controls. Returned only if requested.

attachments FileAttachmentArray

Key Type Description
attachment_type string For invoice xml value is the xml format requested e.g. ‘PEPPOLBIS30’. For invoice image, ‘INVOICE_IMAGE’. For other attachments ‘ATTACHMENT’
filename string Original or Maventa generated filename
file base64 File contents in base64 format

metadata InvoiceDownloadMetadata

Key Type Description
origin string Source of the invoice, either EINVOICE or SCAN
original_format string Original XML format
company_name string Sender company name
company_bid string Sender company business identifier
invoice_nr string  
reference_nr string  
sum string Invoice total without VAT
sum_tax string Invoice total including VAT (payable amount)
currency string  
date string  
date_due string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:invoice_downloadResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:InvoiceDownloadParams">
            <metadata xsi:type="n1:InvoiceDownloadMetadata">
               <invoice_nr xsi:type="xsd:string">Invoice 608583</invoice_nr>
               <company_bid xsi:type="xsd:string">1234567-9</company_bid>
               <date xsi:type="xsd:string">20201009</date>
               <original_format xsi:type="xsd:string">FINVOICE30</original_format>
               <currency xsi:type="xsd:string">EUR</currency>
               <sum_tax xsi:type="xsd:string">24.0</sum_tax>
               <company_name xsi:type="xsd:string">Supplier xyz</company_name>
               <date_due xsi:type="xsd:string">20201108</date_due>
               <sum xsi:type="xsd:string">24.0</sum>
               <origin xsi:type="xsd:string">EINVOICE</origin>
               <reference_nr xsi:nil="true"/>
            </metadata>
            <attachments n2:arrayType="n1:FileAttachment[2]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <filename xsi:type="xsd:string">invoice_image.pdf</filename>
                  <attachment_type xsi:type="xsd:string">INVOICE_IMAGE</attachment_type>
                  <file xsi:type="n2:base64">JVBERi0xLjMKJf</file>
               </item>
            </attachments>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:invoice_downloadResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: INVOICE NOT FOUND OR NO RIGHTS Requested invoice doesn't exist for the company
ERROR: USER NOT FOUND
ERROR: FORMAT NOT SUPPORTED Invoice format specified is not supported
ERROR: VENDOR KEY MISSING Invalid or no vendor key provided
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company
InvoiceDownloadOption = Struct.new(:key,:value)
options = [InvoiceDownloadOption.new("generate_image_if_missing","true")]
puts "Downloading invoice #{options[:invoice_id]}, started at: #{Time.new.strftime("%H:%M:%S")}"
result = server.invoice_download(api_keys, "12345678-90ab-cdef-1234-567890abcdef", true ["teapps","finvoice"], options)
puts result.inspect

invoice_list_between_dates

Used for getting list of outbound invoices. With timestamps its possible to recheck an intervall if there’s reason to believe something was missed or need to redownload invoices.

Read more about sending invoices

/v1.1/api/invoice_list_between_dates

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
timestamp_start string start time for search, format “YYYYMMDDHHMMSS”
timestamp_end string end time for search, format “YYYYMMDDHHMMSS”
all int nil => open invoices, 1 => archived invoices, 2 => all invoices, 3 => invoices in error state
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_list_between_dates soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <timestamp_start xsi:type="xsd:string">?</timestamp_start>
         <timestamp_end xsi:type="xsd:string">?</timestamp_end>
         <all xsi:type="xsd:int">?</all>
      </sec:invoice_list_between_dates>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceParamsOutCArray

Key Type Description
status string Status
id string Invoice db-id
state int Invoice state
currency string Currency abbrevation
invoice_nr string Invoice number
order_nr string Order number
sum string Total sum without tax
sum_tax string Total sum with tax
delivery_date string Delivery date, YYYYMMDD
delivery_type string Delivery type (e.g. mail)
reference_nr string Invoice reference number
date string Invoicing date, YYYYMMDD
date_due string Invoice due date, YYYYMMDD
company_interest string Company’s interest rate (e.g. 11.5)
company_reminder string Company’s reminder fee in invoices currency (e.g. 5.50)
company_paper_fee string Company’s paper fee, added if customer requests paper invoice (e.g. 3.25)
customer_reference string Reference for customer (“Viitteenne”)
company_reference string Reference for company (“Viitteemme”)
company_comment string Comment for email invoice
customer_comment string Customer comment (from decline invoice)
notes string Additional information for invoice
lang string Language code for invoice (e.g. ‘FI’)
customer_nr string Customer number
customer_name string Name
customer_email string Email
customer_bid string Business ID, VAT, etc
customer_contact_p string Contact person’s name
customer_address1 string First line of street address
customer_address2 string Second line of street address
customer_post_code string Postal code
customer_post_office string Postal office
customer_state string State
customer_country string Country (e.g. ‘FI’)
customer_ovt string EDI-code (OVT)
work_order_nr string Work order nr
payment_terms string Payment terms
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:invoice_list_between_datesResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n2:Array" n2:arrayType="n1:InvoiceParamsOutC[216]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
            <item>
               <invoice_delivery_address xsi:nil="true"/>
               <data xsi:type="xsd:string">{"customer_order_number":"0110"}</data>
               <customer_contact_p xsi:nil="true"/>
               <notes xsi:type="xsd:string">Some notes</notes>
               <order_nr xsi:type="xsd:string">1001</order_nr>
               <state xsi:type="xsd:int">99</state>
               <company_paper_fee xsi:nil="true"/>
               <sum xsi:type="xsd:string">100</sum>
               <customer_comment xsi:nil="true"/>
               <customer_ovt xsi:nil="true"/>
               <attachments xsi:nil="true"/>
               <reference_nr xsi:type="xsd:string">1337</reference_nr>
               <payment_terms xsi:type="xsd:string">14 days</payment_terms>
               <customer_post_code xsi:nil="true"/>
               <date xsi:type="xsd:string">20190909</date>
               <customer_bid xsi:nil="true"/>
               <company_comment xsi:type="xsd:string">This is a comment to email</company_comment>
               <invoice_nr xsi:type="xsd:string">1001</invoice_nr>
               <company_reminder xsi:nil="true"/>
               <customer_country xsi:type="xsd:string"/>
               <delivery_type xsi:type="xsd:string">mail</delivery_type>
               <customer_address2 xsi:type="xsd:string"/>
               <work_order_nr xsi:type="xsd:string">10010110</work_order_nr>
               <actions xsi:nil="true"/>
               <customer_email xsi:nil="true"/>
               <id xsi:type="xsd:string">fd717e90-fba2-47b8-85bb-bd05f0b42e91</id>
               <company_reference xsi:type="xsd:string">Viitteemme</company_reference>
               <customer_nr xsi:type="xsd:string"/>
               <currency xsi:nil="true"/>
               <company_interest xsi:nil="true"/>
               <customer_state xsi:nil="true"/>
               <items xsi:nil="true"/>
               <invoice_seller_information xsi:nil="true"/>
               <customer_address1 xsi:type="xsd:string"/>
               <delivery_date xsi:type="xsd:string">20190909</delivery_date>
               <status xsi:type="xsd:string">OK</status>
               <accounts xsi:nil="true"/>
               <customer_reference xsi:type="xsd:string">Viitteenne</customer_reference>
               <customer_name xsi:type="xsd:string">Test Customer</customer_name>
               <sum_tax xsi:type="xsd:string">122</sum_tax>
               <date_due xsi:type="xsd:string">20190930</date_due>
               <lang xsi:type="xsd:string">FI</lang>
               <customer_post_office xsi:nil="true"/>
            </item>
         </return>
      </n1:invoice_list_between_datesResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: TIMESTAMP START FORMAT ERROR
ERROR: TIMESTAMP END FORMAT ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

invoices = server.invoice_list_between_dates(api_keys, "20120501000000", "20120510000000", nil)

if invoices[0].status == "OK"

  invoices.each do |invoice|
    puts invoice.id, invoice.sum, invoice.sum_tax, invoice.invoice_nr,
    invoice.customer_nr, invoice.customer_name, invoice.customer_email,
    invoice.customer_bid, invoice.customer_address1, invoice.customer_address2,
    invoice.customer_post_code, invoice.customer_post_office,
    invoice.customer_state, invoice.customer_country,
    invoice.customer_contact_p, invoice.customer_ovt, invoice.lang
  end

end

invoice_list_ids

Used for getting a list of invoice id’s. Otherwise the same as invoice_list_between_dates and invoice_list_inbound_between_dates but a lot faster as it only returns the invoice id’s.

/v1.1/api/invoice_list_ids

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key (mandatory)
Key Type Description
direction string IN or OUT
timestamp_start string Start time for search, format “YYYYMMDDHHMMSS”
timestamp_end string End time for search, format “YYYYMMDDHHMMSS”
options string Not yet implemented any
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_list_ids soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <direction xsi:type="xsd:string">?</direction>
         <timestamp_start xsi:type="xsd:string">?</timestamp_start>
         <timestamp_end xsi:type="xsd:string">?</timestamp_end>
         <options xsi:type="xsd:string">?</options>
      </sec:invoice_list_ids>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceListIdsStruct

Key Type Description
status string Status of the API call
invoice_ids Array Invoice DB-id
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:invoice_list_idsResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:InvoiceListIdsStruct">
            <invoice_ids n2:arrayType="xsd:string[19]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>bddf2e77-607b-492b-b9cd-e11731d8a8fd</item>
               <item>4c74f8a2-06a5-4f64-8087-8e98e1f16cab</item>
            </invoice_ids>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:invoice_list_idsResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: VENDOR API KEY MISSING
ERROR: VENDOR API KEY INVALID OR DISABLED
ERROR: TIMESTAMP START FORMAT ERROR
ERROR: TIMESTAMP END FORMAT ERROR
ERROR: TIMEFRAME TOO LONG Max one month between start and end
ERROR: INVALID DIRECTION
ERROR: USER NOT FOUND
ERROR: Unexpected error

invoice_list_inbound_between_dates

Used for getting list of inbound invoices. With timestamps its possible to recheck an intervall if there’s reason to believe something was missed or need to redownload invoices. Recommended that ‘id’ of downloaded invoices is saved locally to be able to check for duplicates.

Read more about invoice receiving

/v1.1/api/invoice_list_inbound_between_dates

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
timestamp_start string start time for search, format “YYYYMMDDHHMMSS”
timestamp_end string end time for search, format “YYYYMMDDHHMMSS”
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_list_inbound_between_dates soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <timestamp_start xsi:type="xsd:string">?</timestamp_start>
         <timestamp_end xsi:type="xsd:string">?</timestamp_end>
      </sec:invoice_list_inbound_between_dates>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InboundInvoiceParamsOutCArray

Key Type Description
status string Status
id string Invoice db-id
state int Invoice state
currency string Currency abbrevation
invoice_nr string Invoice number
order_nr string Order number
sum string Total sum without tax
sum_tax string Total sum with tax
delivery_date string Delivery date, YYYYMMDD
delivery_type string Delivery type (e.g. mail)
reference_nr string Invoice reference number
date string Invoicing date, YYYYMMDD
date_due string Invoice due date, YYYYMMDD
customer_reference string Reference for customer (“Viitteenne”)
company_reference string Reference for company (“Viitteemme”)
company_comment string Comment for email invoice
notes string Additional information for invoice
lang string Language code for invoice (e.g. ‘FI’)
customer_nr string Customer number
customer_name string Recipient name
customer_email string Recipient email
customer_bid string Recipient BID/VAT/org number
customer_contact_p string Recipient contact person’s name
customer_address1 string Recipient street address
customer_address2 string Recipient additional address
customer_post_code string Recipient postal code
customer_post_office string Recipient postal office
customer_state string Recipient address state
customer_country string Recipient country code
customer_ovt string Recipient e-invoice address (EDI/OVT/GLN/EAN…)
company_name string Sender name
company_bid string Sender BID/VAT/org number
company_address1 string Sender street address
company_address2 string Sender additional address
company_post_code string Sender post code
company_post_office string Sender post office
company_city string Sender registered city
company_state string Sender address state
company_country string Sender country code
company_phone string Sender phone number
company_gsm string Sender GSM number
company_fax string Sender fax number
company_email string Sender email
company_website string Sender website
company_interest string Invoice late interest rate
company_reminder string Invoice reminder fee
company_paper_fee string Invoice paper fee
user_name string Sender contact person
user_email string Sender contact email
user_phone string Sender contact phone
work_order_nr string Work order nr
payment_terms string Payment terms
invoice_delivery_address InvoiceDeliveryAddressOut Invoice delivery address
invoice_seller_information InvoiceSellerInformationOut Invoice seller information

invoice_delivery_address InvoiceDeliveryAddressOut

Key Type Description
post_code string  
address2 string  
country string  
post_office string  
name string  
state string  
id string  
address1 string  

invoice_seller_information InvoiceSellerInformationOut

Key Type Description
phone string  
name string  
email string  
id string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK
ERROR: TIMESTAMP START FORMAT ERROR
ERROR: TIMESTAMP END FORMAT ERROR
ERROR: NO INVOICES
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

invoices = server.invoice_list_inbound_between_dates(api_keys, "20090916000000", "20120916000000")

if invoices[0].status == "OK"

  invoices.each do |invoice|
    puts "ID: #{invoice.id}, Nr: #{invoice.invoice_nr}, Date: #{invoice.date}"
  end

end

invoice_put_invoice_with_metadata

Used for creating new invoices from existing XML invoice files or ZIP files with XML files and attachments. Additional information can be given in metadata.

If the same information is given in invoice XML, metadata will override it.

Note! Version in the JSON struct should always be 1.1

Read more about sending invoices

/v1.1/api/invoice_put_invoice_with_metadata

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

file_in FileAttachment

Key Type Description
attachment_type string Not needed on input
filename string Allowed characters [A-z0-9_.-] (no spaces or other special characters allowed)
file base64 File content itself (XML or ZIP)
Key Type Description
xmlformat string Currently supports “vismaxml”, “svefaktura”, “sedi”, “e2b”, “ehf”, “peppolbis20”, “siubl11”, “siubl20”, “vismaubl”, “vismaubl30” “finvoice”, “finvoice30”, “teapps30”

metadata string

JSON struct, supports following parameters:

  • version - Always “1.1”
  • routing
    • receiver_eia - Receivers electronic address (e.g. EIA, OVT, GLN)
    • receiver_operator_id - Receivers operator code
    • receiver_email - Address the invoice is sent to if delivered by email
    • route_order array - Only in Norway, used with recipient_type “consumer” to define preferred order of routes.
      Possible routes are:
      • “netbank”
      • “netbank_cvl”
      • “netbank_cvl_hold”
      • “vipps”
      • “dpi”
      • “email”
      • “print”
  • disabled_routes_out - Routes that will not be tried, “true” means the route is disabled
    • paper
    • email
    • relay
  • extra
    • sender_comment - Text that will be added in the email message if invoice is delivered by email
  • recipient_type - Only in Norway, set to “consumer” to use route_order
  • licensing
    • license_key - Key that identifies license. Used in partner’s invoicing system to allocate transaction (max length 255 bytes)
    • license_meta - Additional information related to license e.g. software version, user

Example:

{
   "version":"1.1",
   "routing":{
      "receiver_eia":"00371111111",
      "receiver_operator_id":"003721291126"
   },
   "disabled_routes_out":{
     "paper":"false",
     "email":"false",
     "relay":"false"
   }
}
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_put_invoice_with_metadata soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_meta xsi:type="xsd:string">?</license_meta>
            <license_key xsi:type="xsd:string">?</license_key>
         </api_keys>
         <file_in xsi:type="sec:FileAttachment">
            <!--You may enter the following 3 items in any order-->
            <file xsi:type="soapenc:base64" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv...</file>
            <attachment_type xsi:type="xsd:string"></attachment_type>
            <filename xsi:type="xsd:string">test_invoice.xml</filename>
         </file_in>
         <xmlformat xsi:type="xsd:string">finvoice30</xmlformat>
         <metadata xsi:type="xsd:string">{"version":"1.1","routing":{"receiver_eia":"","receiver_operator_id":""},"disabled_routes_out":{"paper":"false","email":"false","relay":"false"}}</metadata>
      </sec:invoice_put_invoice_with_metadata>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceStatus

Key Type Description
status string Status string, includes OK or ERROR
invoice_id string 36 character UUID of new invoice if successfully created
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:invoice_put_invoice_with_metadataResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:InvoiceStatus">
            <file_statuses xsi:nil="true"/>
            <status xsi:type="xsd:string">OK: INVOICE CREATED SUCCESSFULLY</status>
            <invoice_id xsi:type="xsd:string">72035f60-12b3-70eb-b4c1-ae3ddc8bcf9b</invoice_id>
         </return>
      </n1:invoice_put_invoice_with_metadataResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK: INVOICE CREATED SUCCESSFULLY
ERROR: UNSUPPORTED XML FORMAT
ERROR: FILE OR FILENAME BLANK
ERROR: FILENAME CONTAINS INVALID CHARACTERS
ERROR: FILENAME INSIDE ZIP CONTAINS INVALID CHARACTERS OR IS INVALID TYPE
ERROR: INVALID ZIP FILE
ERROR: COULD NOT SAVE FILES TO DISK
ERROR: FILENAME CONTAINS INVALID CHARACTERS OR IS INVALID TYPE
ERROR: FILE IS EMPTY
ERROR: NO XML FILE OR MORE THAN ONE FOUND
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

file_out = Hash.new
file_out[:file] = SOAP::Attachment.new(File.new("invoice.xml")).to_s
file_out[:filename] = "invoice.xml"

metadata = "{\"version\": \"1.1\", \"routing\" :{\"receiver_eia\": \"003122312555\", \"receiver_operator_id\": \"003721291126\"}}"

result = server.invoice_put_invoice_with_metadata(api_keys, file_out, "vismaxml", metadata)
puts "#{result.status} #{result.invoice_id}"

invoice_show

Used for getting information about a specific outbound invoice.

Read more about sending invoices

/v1.1/api/invoice_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string invoice id
include_files boolean download invoice image and attachments
xmlformat string nil, finvoice, finvoice20, finvoice30, oio, teapps, teapps30, ubl, liinos, svefaktura, sedi, ehf, ehf20, vismaxml, vismaxml60, e2b, woodx, axflow, facturae, bgc, peppolbis20, peppolbis30, siubl, siubl12, siubl20, vismaubl or vismaubl30
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_show soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
         <include_files xsi:type="xsd:boolean">?</include_files>
         <xmlformat xsi:type="xsd:string">?</xmlformat>
      </sec:invoice_show>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceParamsOutD

Key Type Description
status string Status
id string Invoice db-id
state int Invoice state
currency string Currency abbrevation
invoice_nr string Invoice number
order_nr string Order number
sum string Total sum without tax
sum_tax string Total sum with tax
delivery_date string Delivery date, YYYYMMDD
delivery_type string Delivery type for invoiced product (e.g. truck, mail…)
reference_nr string Invoice payment reference number
date string Invoicing date, YYYYMMDD
date_due string Invoice due date, YYYYMMDD
company_interest string Company”s interest rate (e.g. 11.5)
company_reminder string Company”s reminder fee in invoices currency (e.g. 5.50)
company_paper_fee string Company”s paper fee, added if customer requests paper invoice (e.g. 3.25)
customer_reference string Reference for customer (“Viitteenne”)
company_reference string Reference for company (“Viitteemme”)
company_comment string Comment for email invoice
customer_comment string Recipient comment (from decline invoice)
notes string Additional freetext information for invoice
lang string Language code for invoice (e.g. “FI”)
customer_nr string Customer number
customer_name string Name of recipient
customer_email string Email of recipient. If left blank, no email notification can/will be sent
customer_bid string Business ID, VAT, organization number etc
customer_contact_p string Contact person”s name
customer_address1 string First line of street address
customer_address2 string Second line of street address
customer_post_code string Postal code
customer_post_office string Postal office
customer_state string State
customer_country string Country (e.g. “FI”)
customer_ovt string EDI-code (OVT), e-invoice address
work_order_nr string Work order nr
payment_terms string Payment terms
items ItemsOutArray Array of ItemsOut
attachments FileAttachmentArray Array of FileAttachment
accounts InvoiceAccountParamsOutArray Array of InvoiceAccountParamsOut
actions InvoiceActionParamsOutArray Array of InvoiceActionParamsOut

items ItemsOutArray

Key Type Description
subject string Subject string
amount double Amount/quantity of items
price string Unit price
tax double VAT tax for item, expressed as a percentage, e.g. 22.0 is 22%
sum string Sum without VAT tax for item row, dot as decimal separator (e.g. “123.45”)
sum_tax string Sum including VAT tax for item row, dot as decimal separator (e.g. “123.45”)
item_code string Item code
definition string Additional definition for item (freetext)
position int Position in item list
unit_type string Unit of item (e.g. “km” or “h”)
discount double Discount percentage (e.g. 12.5)

attachments FileAttachmentArray

Key Type Description
attachment_type string  
filename string  
file base64  

accounts InvoiceAccountParamsOutArray

Key Type Description
status string  
account string  
iban string  
bank string  
swift string  

actions InvoiceActionParamsOutArray

Key Type Description
timestamp string  
action string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:invoice_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:InvoiceParamsOutD">
            <data xsi:type="xsd:string">{"customer_order_number":"1337"}</data>
            <customer_contact_p xsi:type="xsd:string">John Doe</customer_contact_p>
            <notes xsi:type="xsd:string">INVOICE TO JOHN</notes>
            <work_order_nr xsi:type="xsd:string"/>
            <order_nr xsi:type="xsd:string">123456</order_nr>
            <state xsi:type="xsd:int">3</state>
            <sum xsi:type="xsd:string">1000</sum>
            <customer_comment xsi:nil="true"/>
            <company_paper_fee xsi:type="xsd:string">10.0</company_paper_fee>
            <customer_ovt xsi:type="xsd:string">003733686731</customer_ovt>
            <reference_nr xsi:type="xsd:string">1 57432 49126</reference_nr>
            <attachments xsi:type="n2:Array" n2:arrayType="n1:FileAttachment[1]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <attachment_type xsi:type="xsd:string">INVOICE_IMAGE</attachment_type>
                  <filename xsi:type="xsd:string">invoice_1574324912.pdf</filename>
                  <file xsi:type="n2:base64">JVBERi0xLjMKJf////8KMSAwIG9iago8PCAvVGl0bGUgPGZlZmYwMDU2MDA2
                  OTAwNzMwMDc1MDA2MTAwNmMwMDY5MDA3YTAwNjEwMDc0MDA2OTAwNmYwMDZl
                  MDAyMDAwNmQwMDYxMDA2NDAwNjUwMDIwMDA2MjAwNzkwMDIwMDA0ZDAwNjEw
                  MDc2MDA2NTAwNmUwMDc0MDA2MT4KL0F1dGhvciA8ZmVmZjAwNTAwMDQ0MDA0
                  NjAwNDEwMDUwMDA0OT4KL1N1YmplY3QgPGZlZmYwMDUwMDA0NDAwNDYwMDIw
                  MDA0OTAwNmUwMDc2MDA2ZjAwNjkwMDYzMDA2NT4KL0NyZWF0b3IgPGZlZmYw
                  MDUwMDA3MjAwNjEwMDc3MDA2ZTAwNzQwMDYxMDA3MzAwNzQwMDY5MDA2MzAw
                  MjAwMDc2MDAzMzAwMmUwMDM4MDAyZTAwMzEwMDMyPgovUHJvZHVjZXIgPGZl
                  ZmYwMDUwMDA3MjAwNjEwMDc3MDA2ZTAwMjAwMDc2MDAzMTAwMmUwMDMwMDAy
                  ZTAwMzA+Ci9DcmVhdGlvbkRhdGUgKEQ6MjAxOTEwMTAwNjM4NDArMDMnMDAn
                  KQo+PgplbmRvYmoKMiAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZwovUGFnZXMg
                  MyAwIFIKPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzCi9Db3Vu
                  dCAxCi9LaWRzIFs1IDAgUl0KPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0
                  aCAxNDcxNAo+PgpzdHJlYW0KcQoKQlQKNTYuNjkyOTEzMzg1ODI2NzggODAw
                  </file>
               </item>
            </attachments>
            <error_message xsi:type="xsd:string"/>
            <customer_post_code xsi:type="xsd:string">00100</customer_post_code>
            <date xsi:type="xsd:string">20191121</date>
            <customer_bid xsi:type="xsd:string">FI33686731</customer_bid>
            <company_comment xsi:type="xsd:string"/>
            <invoice_nr xsi:type="xsd:string">1574324912</invoice_nr>
            <invoice_seller_information xsi:nil="true"/>
            <company_reminder xsi:type="xsd:string">14.0</company_reminder>
            <customer_country xsi:type="xsd:string">FI</customer_country>
            <delivery_type xsi:nil="true"/>
            <customer_address2 xsi:nil="true"/>
            <lang xsi:type="xsd:string">FI</lang>
            <customer_email xsi:type="xsd:string">john.doe@johnsdoes.com</customer_email>
            <id xsi:type="xsd:string">439bf2cb-60ac-43b8-895f-8a4386c591aa</id>
            <company_reference xsi:type="xsd:string">REFERENCE</company_reference>
            <actions n3:arrayType="n1:InvoiceActionParamsOut[7]" xsi:type="n3:Array" xmlns:n3="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <timestamp xsi:type="xsd:string">Thu Nov 21 10:28:32 +0200 2019</timestamp>
                  <action xsi:type="xsd:string">CREATED</action>
               </item>
               <item>
                  <timestamp xsi:type="xsd:string">Thu Nov 21 10:29:34 +0200 2019</timestamp>
                  <action xsi:type="xsd:string">INTERNAL</action>
               </item>
               <item>
                  <timestamp xsi:type="xsd:string">Mon Nov 25 15:54:58 +0200 2019</timestamp>
                  <action xsi:type="xsd:string">SENT (EMAIL)</action>
               </item>
            </actions>
            <customer_nr xsi:type="xsd:string">1001</customer_nr>
            <invoice_delivery_address xsi:nil="true"/>
            <customer_state xsi:nil="true"/>
            <currency xsi:type="xsd:string">EUR</currency>
            <company_interest xsi:type="xsd:string"/>
            <items xsi:type="n4:Array" n4:arrayType="n1:ItemsOut[1]" xmlns:n4="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <sum xsi:type="xsd:string">1000</sum>
                  <unit_type xsi:type="xsd:string"/>
                  <position xsi:type="xsd:int">1</position>
                  <discount xsi:type="xsd:double"/>
                  <subject xsi:type="xsd:string">Test item 1</subject>
                  <price xsi:type="xsd:string">1000</price>
                  <definition xsi:type="xsd:string">1: testing</definition>
                  <item_code xsi:type="xsd:string"/>
                  <sum_tax xsi:type="xsd:string">1240</sum_tax>
                  <tax xsi:type="xsd:double">24</tax>
                  <amount xsi:type="xsd:double">1</amount>
               </item>
            </items>
            <customer_address1 xsi:type="xsd:string">address1</customer_address1>
            <delivery_date xsi:type="xsd:string">20191121</delivery_date>
            <payment_terms xsi:type="xsd:string"/>
            <status xsi:type="xsd:string">OK</status>
            <customer_reference xsi:type="xsd:string">1239#5679|CUST4321</customer_reference>
            <customer_name xsi:type="xsd:string">John Company</customer_name>
            <accounts n5:arrayType="n1:InvoiceAccountParamsOut[1]" xsi:type="n5:Array" xmlns:n5="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <swift xsi:type="xsd:string">TSTBNKFI</swift>
                  <iban xsi:type="xsd:string">FI1231231231232456</iban>
                  <bank xsi:type="xsd:string">Test Bank</bank>
                  <account xsi:type="xsd:string">123566-12256</account>
               </item>
            </accounts>
            <sum_tax xsi:type="xsd:string">1240</sum_tax>
            <date_due xsi:type="xsd:string">20191205</date_due>
            <customer_post_office xsi:type="xsd:string">Helsinki</customer_post_office>
         </return>
      </n1:invoice_showResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: INVOICE NOT FOUND OR NO RIGHTS
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.invoice_show(api_keys, "1c555458-fa83-402b-a1f6-4d22071020a8", true, "teapps")
if result.status == "OK"
  puts "Invoice number: " + result.invoice_nr

  if result.attachments
    result.attachments.each do |fa|
      File.open(fa.filename, 'wb') do |f|
        f<<(fa.file)
      end
    end
  end
end

invoice_state_list

Used for getting list of states for given set of invoices and can be used to update state of multiple invoices at once.

/v1.1/api/invoice_state_list

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
invoices StringArray Array of string, containing invoice id’s
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_state_list soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <invoices xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[]"/>
      </sec:invoice_state_list>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceStateArray (array of InvoiceState)

Key Type Description
status string  
state int  
invoice_id string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK
ERROR: NO INVOICES FOUND
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

invoices = Array.new
invoices.push("00521759-4570-467c-98dd-c496b22de0ba")
invoices.push("049b161d-4d15-45a9-95f6-f669d26acf51")
invoices.push("128dc817-90ae-4fa5-a0af-8e24e7650a72")
invoices.push("1c555458-fa83-402b-a1f6-4d22071020a8")
invoices.push("505459bf-8507-42ee-b0da-470f2407c96f")
invoices.push("5ad8cec7-ef53-4161-b9e1-da1921b29f43")

result = server.invoice_state_list(api_keys, invoices)
if result[0].status == "OK"
  result.each do |i|
    puts "#{i.invoice_id}: #{i.state}"
  end
end

invoice_reroute

Used for re-routing a existing specific outbound invoice.

Read more about sending invoices

/v1.1/api/invoice_reroute

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string invoice id
route string einvoice, email or print

params InvoiceRerouteParams

Key Type Description
recipient_eia string Recipient’s electronic invoicing address
recipient_operator string Recipient’s operator code
email string Recipient email address
customer_name string If routing to print, fill in the address details
customer_address1 string  
customer_address2 string  
customer_post_code string  
customer_post_office string  
customer_state string  
customer_country string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:sec="https://secure.maventa.com/">
  <soapenv:Header/>
  <soapenv:Body>
    <sec:invoice_reroute soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <api_keys xsi:type="sec:ApiKeys">
        <!--You may enter the following 5 items in any order-->
        <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
        <company_uuid xsi:type="xsd:string">?</company_uuid>
        <user_api_key xsi:type="xsd:string">?</user_api_key>
        <!--Optional:-->
        <license_key xsi:type="xsd:string">?</license_key>
        <license_meta xsi:type="xsd:string">?</license_meta>
      </api_keys>
      <route xsi:type="xsd:string">?</route>
      <id xsi:type="xsd:string">?</id>
      <params xsi:type="sec:InvoiceRerouteParams">
        <!--You may enter the following 10 items in any order-->
        <recipient_eia xsi:type="xsd:string">?</recipient_eia>
        <recipient_operator xsi:type="xsd:string">?</recipient_operator>
        <email xsi:type="xsd:string">?</email>
        <customer_name xsi:type="xsd:string">?</customer_name>
        <customer_address1 xsi:type="xsd:string">?</customer_address1>
        <customer_address2 xsi:type="xsd:string">?</customer_address2>
        <customer_post_code xsi:type="xsd:string">?</customer_post_code>
        <customer_post_office xsi:type="xsd:string">?</customer_post_office>
        <customer_state xsi:type="xsd:string">?</customer_state>
        <customer_country xsi:type="xsd:string">?</customer_country>
      </params>
    </sec:invoice_reroute>
  </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceParamsOutD

Key Type Description
return string Status, did the re-routing work
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <n1:invoice_rerouteResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
      xmlns:n1="https://secure.maventa.com/">
      <return xsi:type="xsd:string">OK: Invoice routed successfully</return>
    </n1:invoice_rerouteResponse>
  </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: Invoice routed successfully
ERROR: Invalid parameters
ERROR: Invalid route
ERROR: Invoice reroute failed: #{message}
ERROR: Invoice not found or no rights
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

#Set invoice ID and route 
invoice_id = ""
route = ""

#Set up route params
params = Hash.new
params[:recipient_eia] = ""
params[:recipient_operator] = ""
params[:email] = ""
params[:customer_name] = ""
params[:customer_address1] = ""
params[:customer_address2] = ""
params[:customer_post_code] = ""
params[:customer_post_office] = ""
params[:customer_state ] = ""
params[:customer_country] = ""

#Re-route the invoice
result = server.invoice_reroute(api_keys, route, invoice_id, params)

puts result

link_vendor_api_key

Link company account to a vendor_api_key like company was registered using API with that vendor_api_key.

Read more about vendor api keys

/v1.1/api/link_vendor_api_key

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:link_vendor_api_key soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:link_vendor_api_key>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string “OK” or “ERROR: …”
Example API response
<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:link_vendor_api_keyResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:link_vendor_api_keyResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK
ERROR: NO VENDOR API KEY GIVEN
ERROR: COULD NOT SAVE CHANGES
Examples
Example Ruby implementation
require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

puts server.link_vendor_api_key(api_keys)

list_operators

Lists currently supported roaming operators and their operator codes.

Read more about invoice sending

/v1.1/api/list_operators

Input

list_operators

Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:list_operators soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
   </soapenv:Body>
</soapenv:Envelope>

Output

return OperatorInfoArray

Key Type Description
operator_id string Operator code
name string Operator name
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:list_operatorsResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return n2:arrayType="n1:OperatorInfo[24]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
            <item>
               <operator_id href="#id69965496697180"/>
               <name xsi:type="xsd:string">MAVENTA</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">BAWCFI22</operator_id>
               <name xsi:type="xsd:string">BASWARE</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003701011385</operator_id>
               <name xsi:type="xsd:string">TIETO</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003708599126</operator_id>
               <name xsi:type="xsd:string">LIAISON</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003714756079</operator_id>
               <name xsi:type="xsd:string">SONERA</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003714377140</operator_id>
               <name xsi:type="xsd:string">Ropo Capital</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003703575029</operator_id>
               <name xsi:type="xsd:string">CGI</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">PAGERO</operator_id>
               <name xsi:type="xsd:string">PAGERO</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">LOGIQ</operator_id>
               <name xsi:type="xsd:string">LOGIQ</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">PEPPOL</operator_id>
               <name xsi:type="xsd:string">PEPPOL</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">SE556700997101</operator_id>
               <name xsi:type="xsd:string">INEXCHANGE</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">EXPSYS</operator_id>
               <name xsi:type="xsd:string">EXPERTSYSTEMS</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">VISMAEDI</operator_id>
               <name xsi:type="xsd:string">VISMA EDI</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">LOGICASWEDEN</operator_id>
               <name xsi:type="xsd:string">LOGICASWEDEN</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003723327487</operator_id>
               <name xsi:type="xsd:string">APIX</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">B2CNO</operator_id>
               <name xsi:type="xsd:string">B2CNO</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">NEMHANDEL</operator_id>
               <name xsi:type="xsd:string">NEMHANDEL</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">B2C_VIPPS</operator_id>
               <name xsi:type="xsd:string">VIPPS FAKTURA</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003726044706</operator_id>
               <name xsi:type="xsd:string">NETBOX</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">B2CNO_AGIRO_VIEW</operator_id>
               <name xsi:type="xsd:string">B2CNO_AGIRO_VIEW</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">E204503</operator_id>
               <name xsi:type="xsd:string">OpusCapita</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">003701150617</operator_id>
               <name xsi:type="xsd:string">STRALFORS</name>
            </item>
            <item>
               <operator_id xsi:type="xsd:string">B2CNO_AGIRO</operator_id>
               <name xsi:type="xsd:string">B2CNO_AGIRO</name>
            </item>
            <item>
               <operator_id href="#id69965496697180"/>
               <name xsi:type="xsd:string">AUTOINVOICE</name>
            </item>
         </return>
      </n1:list_operatorsResponse>
      <operator_id id="id69965496697180" xsi:type="xsd:string" env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">003721291126</operator_id>
   </env:Body>
</env:Envelope>

Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.list_operators
result.each do |op|
  puts "#{op.name}: #{op.operator_id}"
end

list_vendor_inbound_invoices

Allows vendor to list inbound invoices of companies linked to their vendor_api_key.

Read more about invoice receiving

/v1.1/api/list_vendor_inbound_invoices

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:list_vendor_inbound_invoices soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <timestamp_start xsi:type="xsd:string">?</timestamp_start>
         <timestamp_end xsi:type="xsd:string">?</timestamp_end>
      </sec:list_vendor_inbound_invoices>
   </soapenv:Body>
</soapenv:Envelope>

Output

items InboundInvoiceList

Key Type Description
status string Status
items InboundInvoiceListItemArray Array of InboundInvoiceListItem

items InboundInvoiceListItemArray

Key Type Description
invoice_id string Unique ID of invoice, to be used in method inbound_invoice_show
recipient_id string company_uuid of recipient company
timestamp string Timestamp when invoice was received on account, is what is checked against with the list methods timestamps
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:list_vendor_inbound_invoicesResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:InboundInvoiceList">
            <items xsi:type="n2:Array" n2:arrayType="n1:InboundInvoiceListItem[34]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <recipient_id xsi:type="xsd:string">eaeb6064-d0b1-5109-81cf-4bddf61b9e42</recipient_id>
                  <timestamp xsi:type="xsd:string">20191106120725</timestamp>
                  <invoice_id xsi:type="xsd:string">e4038c72-1ecd-43ce-8c2e-8e6fe41d4adc</invoice_id>
               </item>
               <item>
                  <recipient_id xsi:type="xsd:string">eaeb5065-d2b3-4408-80cf-4bddf51b9e42</recipient_id>
                  <timestamp xsi:type="xsd:string">20191106121142</timestamp>
                  <invoice_id xsi:type="xsd:string">91cdaee2-ca3e-4705-87e2-f2cfe76bf3c6</invoice_id>
               </item>
            </items>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:list_vendor_inbound_invoicesResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: TIMESTAMP START FORMAT ERROR
ERROR: TIMESTAMP END FORMAT ERROR
ERROR: NO RIGHTS TO VENDOR API KEY
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.list_vendor_inbound_invoices(api_keys, "20120501152042", "20120502152042")
if result.status == "OK"
  result.items.each do |item|
    puts "Incoming invoice #{item.invoice_id} for recipient #{item.recipient_id} with timestamp #{item.timestamp}"
  end
else
  puts result.status
end

register_with_password

Method register_with_password can be used to register new companies through the API with predefined password (if given).

This method is only for partners and requires a partner software API key. Partner must make sure the user can read and understand the Maventa license agreements.

Method returns a RegistrationParamsOutD struct which includes the new user’s API key, the company’s UUID and e-invoice address for receiving. This information can then be automatically updated to the software’s settings so the users do not need to input API key information by themselves.

Note! If given user (e-mail) exists, API key will not be returned for security reasons. The user will then get access to the newly created company with the same user account. In this case the password will not be updated. Note! Password minimum length 8 characters.

Read more about companies and settings

/v1.1/api/register_with_password

Input

registration_params RegistrationParamsIn

Key Type Description
vendor_api_key string Identifies partner/ERP, mandatory
license_agreement boolean Registering company must accept Maventa user agreement, mandatory
company_name string Company name, mandatory
company_bid string Company VAT/Business ID/Organization number (VAT preferred), mandatory
company_email string Contact email address for company, mandatory
no_vat boolean If company_bid is not a VAT-number, this is set to true to skip VAT-check
receive_invoices boolean Select if company wants to receive e-invoices on their account
user_first_name string First name, mandatory
user_last_name string Last name, mandatory
user_email string Email is used as login to portal and needs to be unique, mandatory
user_phone string Depending on invoice format, phone number might be visible on invoices
email_activation boolean Possibility to skip email activation by link (partner has verified email)
address1 string Street address, mandatory
address2 string Additional address
post_code string Postal number/code, mandatory
post_office string Post office, mandatory
city string Registered city, mandatory
state string State of address
country string Country code for company, mandatory. Allowed countries FI, SE, NO, DK, NL, EE
bank_accounts BankAccountParamsInArray Array of BankAccountParamsIn

bank_accounts BankAccountParamsInArray

Bank accounts are not required for registration and needed only if invoicing format does not include bank account details

Key Type Description
account string  
default boolean  
iban string  
swift string  
bank string  
Key Type Description
user_password string if not given, random password will be generated
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:register_with_password soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <registration_params xsi:type="sec:RegistrationParamsInD">
            <!--You may enter the following 20 items in any order-->
            <post_office xsi:type="xsd:string">?</post_office>
            <email_activation xsi:type="xsd:boolean">?</email_activation>
            <user_first_name xsi:type="xsd:string">?</user_first_name>
            <company_name xsi:type="xsd:string">?</company_name>
            <company_email xsi:type="xsd:string">?</company_email>
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_bid xsi:type="xsd:string">?</company_bid>
            <user_last_name xsi:type="xsd:string">?</user_last_name>
            <address1 xsi:type="xsd:string">?</address1>
            <state xsi:type="xsd:string">?</state>
            <country xsi:type="xsd:string">?</country>
            <address2 xsi:type="xsd:string">?</address2>
            <receive_invoices xsi:type="xsd:boolean">?</receive_invoices>
            <city xsi:type="xsd:string">?</city>
            <user_email xsi:type="xsd:string">?</user_email>
            <license_agreement xsi:type="xsd:boolean">?</license_agreement>
            <no_vat xsi:type="xsd:boolean">?</no_vat>
            <user_phone xsi:type="xsd:string">?</user_phone>
            <post_code xsi:type="xsd:string">?</post_code>
            <bank_accounts xsi:type="sec:BankAccountParamsInArray" soapenc:arrayType="sec:BankAccountParamsIn[]"/>
         </registration_params>
         <user_password xsi:type="xsd:string">?</user_password>
      </sec:register_with_password>
   </soapenv:Body>
</soapenv:Envelope>

Output

return RegistrationParamsOutD

Key Type Description
status string  
company_uuid string  
user_api_key string  
company_maventa_id string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK
ERROR: LICENSE AGREEMENT NEEDS TO BE ACCEPTED
ERROR: COUNTRY CODE INVALID
ERROR: REGISTRATION FAILED, BID ALREADY TAKEN
ERROR: VAT CHECK FAILED
ERROR: POSTAL ADDRESS MISSING REQUIRED INFORMATION
ERROR: USER PASSWORD INVALID
ERROR: USER DETAILS MISSING REQUIRED INFORMATION
ERROR: REGISTRATION FAILED
Examples
Example Ruby implementation

require 'soap/wsdlDriver'
server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

registration_params = Hash.new

#vendor api key needs to be set and valid for register request to work
registration_params[:vendor_api_key] = "bccd8e6e-fc64-427a-b1b2-3c3ab578e370"

#license agreement needs to be agreed, vendor makes sure user can read the
#agreement
registration_params[:license_agreement] = true

#company name and bid/vat
registration_params[:company_name] = "api test"
registration_params[:company_bid] = "fi12345671"

#company has vat code or no
registration_params[:no_vat] = true

#Receiving invoices on/off
registration_params[:receive_invoices] = true

#Require activation of email address
registration_params[:email_activation] = false

#user information, activation email with password is sent to this email address
registration_params[:user_first_name] = "api"
registration_params[:user_last_name] = "test"
registration_params[:user_email] = "apitest@maventa.com"
registration_params[:user_phone] = "040 123 4566"

#company address information
registration_params[:address1] = "test street 1"
registration_params[:address2] = "section c"
registration_params[:post_code] = "00100"
registration_params[:post_office] = "helsinki"
registration_params[:city] = "helsinki"
registration_params[:state] = nil
registration_params[:country] = "fi"

#bank account information, not mandatory since account information can be given
#in the invoice_create request when using the new api
bank_account_params = array.new

ba1 = hash.new
ba1[:bank] = "testbank 1"
ba1[:iban] = "f1111 1221121"
ba1[:swift] = "tstbnkfi"
ba1[:account] = "12222-42211"
ba1[:default] = true

ba2 = hash.new
ba2[:bank] = "testbank 2"
ba2[:iban] = "f222 2221222"
ba2[:swift] = "tstbnkfi"
ba2[:account] = "222122-42221"

bank_account_params.push(ba1)
bank_account_params.push(ba2)

registration_params[:bank_accounts] = bank_account_params

result = server.register_with_password(registration_params, user_password)

if result.status == "OK"
  puts "user api key: #{result.user_api_key}"
  puts "company uuid: #{result.company_uuid}"
  puts "company e-invoice address: #{result.e_invoice_address}"
end

authorize_companies

Creating a new company account requires strong authentication, depending on agreement it can happen on the ERP side or in AutoInvoice via Visma Sign. After registering new company account and in order to be able to send or receive invoices, this method is needed to verify the created company. Calling the authorize_companies includes the company authorisation and TOS signing as well as for Finnish companies the bank network opening. Read more about company authorization from integration guide

/v1.1/api/authorize_companies

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
auth_email string Email to send the Visma sign request to. The person signing will be strongly authenticated.
company_emails StringArray Array of company UUIDs to authorize. Admin user needs to have rights to all of the companies given
locale string Locale to use on the sign invitation email, visma sign portal, and agreement pdf. Currently supports FI, NO, SE, EN
options string Used only if ERP has self-signed the company. Contact Maventa team if ERP want’s to sign on their side, otherwise can be given empty value
Output
Key Type Description
return string  
Return values
Key Type Message
return string OK: Visma Sign document sent
ERROR: VENDOR API KEY CANNOT BE BLANK
EERROR: VENDOR API KEY INVALID OR DISABLED
ERROR: EMAIL ADDRESS INVALID
ERROR: LOCALE NOT SUPPORTED
ERROR: AMOUNT OF COMPANIES TO SIGN NEEDS TO BE BETWEEN 1 to 50
ERROR: COMPANY AUTHORIZATION STATUS MISMATCH
ERROR: UNKNOWN ERROR

company_auth_status

To check the company authorization status. In order to start sending and receiving invoices the company status needs to be verified. Read more about company authorization from integration guide

/v1.1/api/company_auth_status

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Output

return AuthParamsOut

Key Type Description
auth_state string Visma Sign request state SENT/SIGNED/CANCELLED/PENDING/ERROR
auth_email string Email address used to sent the Visma Sign request to
company_state string Trusted state of the company unverified/verified
Return values
Key Type Message
return string OK: Visma Sign document sent
OK: Company authorized
OK: No authorization requests
ERROR: USER NOT FOUND
ERROR: VENDOR API KEY CANNOT BE BLANK
ERROR: VENDOR API KEY INVALID OR DISABLED
ERROR: Visma Sign status check failed
ERROR: UNKNOWN ERROR

Removes uploaded logo from server.

Read more about logo usage from the printing guide

/v1.1/api/remove_logo

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:remove_logo soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:remove_logo>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:remove_logoResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:remove_logoResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: COULD NOT SAVE SETTINGS Logo could not be removed
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

puts server.remove_logo(api_keys)

scan_account_disable

Close scan account.

Read more about scanning

/v1.1/api/scan_account_disable

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

Sorry, there is no example available for this method.

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK Scan account closed
ERROR: Scan account not found
ERROR: Multiple scan accounts found, please contact support
ERROR: Unexpected error, contact customer support
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.scan_account_disable(api_keys)
puts result

scan_account_order

Open a new scan account for your company or for updating already existing one when called again. If first time ordering is successful, returns the scan address where suppliers send their invoices (paper or email). Note! It is very important to give suppliers the full returned scanning address. Also note that you cannot open a scan account if your account has receiving e-invoices turned off.

When called again for already existing scan account, will return OK: RETURN ADDRESS UPDATED

Note! User accepts the pricing including scan minimum fee when opening the account.

Read more about scanning

/v1.1/api/scan_account_order

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

return_address ScanAddress

Your company’s postal address. Given to scan provider so they can return mail which is not proper invoices that have been sent to scanning address (like contracts etc.)

Key Type Description
name string  
address1 string either address1 or address2 mandatory
address2 string  
post_code string mandatory
post_office string mandatory
state string  
country string mandatory
email string for sending notifications in error situations, mandatory
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:scan_account_order soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <return_address xsi:type="sec:ScanAddress">
            <!--You may enter the following 8 items in any order-->
            <post_office xsi:type="xsd:string">?</post_office>
            <email xsi:type="xsd:string">?</email>
            <address1 xsi:type="xsd:string">?</address1>
            <state xsi:type="xsd:string">?</state>
            <country xsi:type="xsd:string">?</country>
            <address2 xsi:type="xsd:string">?</address2>
            <name xsi:type="xsd:string">?</name>
            <post_code xsi:type="xsd:string">?</post_code>
         </return_address>
      </sec:scan_account_order>
   </soapenv:Body>
</soapenv:Envelope>

Output

return ScanAccountParamsOut

Key Type Description
status string Status
address ScanAddress Company’s scanning address (i.e the address suppliers should use when sending invoices)

address ScanAddress

Key Type Description
name string  
address1 string For sending non-invoice material that has been sent to your scanning address and cannot be sent to your return email address (e.g. packages)
address2 string  
post_code string  
post_office string  
state string  
country string  
email string For sending non-invoice material that has been sent to your scanning address
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK Scan account opened, return value includes address information of the new scan account
OK: RETURN ADDRESS UPDATED
ERROR: REGISTRATION FAILED Unexpected error, contact support
ERROR: SCAN ACCOUNT EXISTS Company already has a scan account, you can have only one
ERROR: SCAN ACCOUNT CURRENTLY AVAILABLE FOR FINNISH, NORWEGIAN, SWEDISH, DANISH AND DUTCH COMPANIES ONLY
ERROR: RETURN ADDRESS EMPTY OR INVALID
ERROR: RECEIVING INVOICES NOT ENABLED ON ACCOUNT
ERROR: INVALID SCAN RETURN EMAIL DOMAIN
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

return_address = Hash.new
return_address[:name] = "Test"
return_address[:address1] = "TestStreet 1"
return_address[:address2] = "B2"
return_address[:post_code] = "010101"
return_address[:post_office] = "TEST"
return_address[:country] = "FI"
return_address[:email] = "myreturn@company.loc"

result = server.scan_account_order(api_keys, return_address)
puts result.status

scan_account_show

Show company’s scanning address (i.e the address suppliers should use when sending invoices).

Note! It is very important to give suppliers the full returned scanning address.

Read more about scanning

/v1.1/api/scan_account_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:scan_account_show soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:scan_account_show>
   </soapenv:Body>
</soapenv:Envelope>

Output

return ScanAddress

Key Type Description
status string Status
name string  
address1 string  
address2 string  
post_code string  
post_office string  
state string  
country string  
email string For sending PDFs per email for interpretation
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:scan_account_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:ScanAccountParamsOut">
            <address xsi:type="n1:ScanAddress">
               <state xsi:nil="true"/>
               <post_office xsi:type="xsd:string">CITY</post_office>
               <country xsi:nil="true"/>
               <post_code xsi:type="xsd:string">00100</post_code>
               <name xsi:type="xsd:string">Test Company</name>
               <address2 xsi:type="xsd:string">Box 1</address2>
               <address1 xsi:type="xsd:string">Boxes</address1>
               <email xsi:type="xsd:string">33686731@autoinvoice.com</email>
            </address>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:scan_account_showResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: SCAN ACCOUNT DISABLED
ERROR: SCAN ACCOUNT NOT FOUND
ERROR: USER NOT FOUND
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.scan_account_show(api_keys)
if result.status == "OK"
  puts result.address.name
  puts result.address.email
  puts result.address.address1
  puts result.address.address2
  puts result.address.post_code
  puts result.address.post_office
  puts result.address.country
else
  puts result.status
end

sent_invoices_status

Used querying the status and possible error message of the sent invoices.

Read more about sending invoices

/v1.1/api/sent_invoices_status

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
invoices StringArray array of string
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:sent_invoices_status soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <invoice_ids xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[]"/>
      </sec:sent_invoices_status>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceStateArray

Key Type Description
invoice_id string  
state string  
sent_by string  
error_message string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:sent_invoices_statusResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:SentInvoicesStatusResponse">
            <invoices xsi:type="n2:Array" n2:arrayType="n1:SentInvoiceStatusStruct[5]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <state xsi:type="xsd:string">SENT</state>
                  <sent_by xsi:type="xsd:string">Sent inside home network</sent_by>
                  <error_message xsi:nil="true"/>
                  <invoice_id xsi:type="xsd:string">afaaa8ef-61ca-6b19-a84d-b9d360fb004c</invoice_id>
               </item>
               <item>
                  <state xsi:type="xsd:string">SENT</state>
                  <sent_by xsi:type="xsd:string">Sent e-invoice</sent_by>
                  <error_message xsi:nil="true"/>
                  <invoice_id xsi:type="xsd:string">590fd499-f679-1345-847d-ab83264c8179</invoice_id>
               </item>
               <item>
                  <state xsi:type="xsd:string">SENT</state>
                  <sent_by xsi:type="xsd:string">Sent by email</sent_by>
                  <error_message xsi:nil="true"/>
                  <invoice_id xsi:type="xsd:string">9b49b446-c478-4902-ad19-3cca4cfac639</invoice_id>
               </item>
               <item>
                  <state xsi:type="xsd:string">SENT</state>
                  <sent_by xsi:type="xsd:string">Sent by print WORLD</sent_by>
                  <error_message xsi:nil="true"/>
                  <invoice_id xsi:type="xsd:string">59f7b65b-b1b4-6d50-b6ec-952716f79631</invoice_id>
               </item>
               <item>
                  <state xsi:type="xsd:string">ERROR</state>
                  <sent_by xsi:nil="true"/>
                  <error_message xsi:type="xsd:string">SEND ERROR (REASON: )</error_message>
                  <invoice_id xsi:type="xsd:string">1214acf1-0743-478d-bda7-44461cb7d238</invoice_id>
               </item>
            </invoices>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:sent_invoices_statusResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: NO INVOICE IDS GIVEN
Possible state values are
Key Type Message Description
state string SENT
ACCEPTED
PAID
VIEWED
PENDING
DECLINED
DISPUTED
ERROR
Possible sent_by values are
Key Type Message Description
sent_by string Sent inside home network
Sent e-invoice
Sent to bank network
Sent by email
Sent by print
Sent by print PRIORITY
Sent by print EU
Sent by print WORLD
Sent by N/A
Examples
Example Ruby implementation

require 'soap/wsdlDriver'
require 'soap/rpc/driver'
require 'soap/attachment'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

response = server.sent_invoices_status(api_keys, ["2a444e5r-4d8c-4858-9179-296b30c0dc39","4444f870d-fb34-43e4-b3c6-c83a96f12bc5"])

if response.status == "OK"
 response.invoices.each do |invoice|
 puts "#{invoice.invoice_id}: #{invoice.state}, #{invoice.sent_by}, #{invoice.error_message}"
end
else
 puts response.status
end

server_time

Used for getting current server time for timestamping purposes.

/v1.1/api/server_time

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:server_time soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string string with the current server time (format “YYYYMMDDHHMMSS”)
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:server_timeResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">20191129145825</return>
      </n1:server_timeResponse>
   </env:Body>
</env:Envelope>

Examples
Example Ruby implementation

require 'soap/wsdlDriver'
server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

puts server.server_time

show_company_configuration

Shows current company configuration and available key/value pairs.

Read more about companies and settings

/v1.1/api/show_company_configuration

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:show_company_configuration soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:show_company_configuration>
   </soapenv:Body>
</soapenv:Envelope>

Output

return SettingValuesOutArray (array of SettingValuesOut)

Key Type Description
status string  
settings SettingValueArray Array of SettingValue

settings SettingValueArray

Key Type Description
website string Website of the company
print_and_send_request int Print&Send request sent (1=yes,0=no)
print_and_send_letter_class integer Print&Send mail class (1 = Priority, 0 = Economy)
print_and_send_own_pdf boolean Use own PDF images in Print&Send (true/false)
print_and_send_color boolean Print with colors in Print&Send (true/false)
print_attachments_disabled boolean Shows if printing of attachments is disabled or enabled (Note! Only for outside FI companies)
email_remind_freq int Frequency of email reminder’s for open invoices in days (e.g. 2)
email string Company email
invoice_email string Company invoice email (inbound invoice notifications)
errors_to_user int Send invoice relay errors to users or just error email? (1=yes,0=no)
error_emails string E-mail address for invoice errors
reports int E-mail reports activated (0 = no, 1 = weekly, 2 = monthly, 3 = daily)
reports_emails string E-mail for send reports
name string Name of the company
bid string Business ID, VAT, organization number etc.
country string Country of the company
stop_duplicates boolean Prevent (re)sending invoices with the same number (true/false)
notify_incoming boolean E-mail notification of incoming invoice (true/false)
disable_email boolean Sending of invoices by email notification. (true/false)
notifications_disabled int Enable/disable all e-mail notifications to the company email address, (1=disable, 0=enable)
internal_receive_via_peppol boolean Internal receiving via Peppol (true/false)
send_email_attachments int Send the invoice image as attachment (true/false)
send_invoice_email int Shows which email invoice sending method is in use. 0 = Do not send invoice via email. 1 = send all invoice e-mails with attachments (max size 5MB). 2 = Send all invoice e-mail with invoice objections. 3 = Send all invoice e-mails with a link to download PDF. Note! This setting will override send_email_attachments and disable_email settings
receive_finvoice2 int Receiving finvoice 2.x (1=yes,0=no)
invoice_receiving int Invoice receiving status, (1=enabled, 0=disabled)
invoicing_eia string invoicing EIA
invoicing_operator string invoicing operator.
invoicing_email string invoicing email address.
invoicing_street_address1 string invoicing postal address.
invoicing_street_address2 string invoicing additional postal address.
invoicing_post_code string invoicing post code.
invoicing_post_office string invoicing post office.
billing_company_id string Billing company id that handles the invoicing of the company
print_and_send_enabled string Print&Send enabled (true/false)
vat_number string Is the Norwegian company VAT registered, returns the VAT number
default_receive_vendor_api_key string Default vendor API key for receiving
default_send_vendor_api_key string Default vendor API key for sending
peppol_id string Peppol ID for the company
bank_send string Is the bank network connection open or not (true/false)
marketing_on_invoice string Electronic invoicing instruction page/marketing page enabled (true/false)
message_from_sender string Message from sender that is visible in the e-mail invoices
scan_return_email string Email address for returned scan material if scan account exists (active or disabled)
scan_return_postal string Postal address for returned scan material if scan account exists (active or disabled)
b2c_fallback string Shows B2C NO fallback route . (print/email)
b2c_reminder boolean Shows if B2C NO reminders are enabled or disabled. (true/false)
contact_person string Shows contact person that is shown in the email message when invoice is sent by email
contact_email string Shows contact email that is shown in the email message when invoice is sent by email
contact_phone string Shows contact phone that is shown in the email message when invoice is sent by email
scan_notification_interval string Supplier Activation e-mail interval (Service is enabled if one of the following is returned: ”monthly”, ”weekly”, ”daily” or disabled if ”disabled”
scan_notification_email string E-mail address for Supplier Activation e-mail delivery
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:show_company_configurationResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:SettingValuesOut">
            <status xsi:type="xsd:string">OK</status>
            <settings xsi:type="n2:Array" n2:arrayType="n1:SettingValue[48]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <key xsi:type="xsd:string">name</key>
                  <value xsi:type="xsd:string">Test Company</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">stop_duplicates</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">billing_company_id</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">disable_email</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">print_and_send_own_pdf</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">default_send_vendor_api_key</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_street_address1</key>
                  <value xsi:type="xsd:string">Company address</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_street_address2</key>
                  <value xsi:type="xsd:string">Kuja kakkonen</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">internal_receive_via_peppol</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_post_code</key>
                  <value xsi:type="xsd:string">00100</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">contact_person</key>
                  <value xsi:type="xsd:string">tapsa</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">reports_emails</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">email_remind_freq</key>
                  <value xsi:type="xsd:string">0</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_operator</key>
                  <value xsi:type="xsd:string">003721291126</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_post_office</key>
                  <value xsi:type="xsd:string">Helsinki</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">message_from_sender</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">send_invoice_email</key>
                  <value xsi:type="xsd:string">1</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">scan_return_postal</key>
                  <value xsi:type="xsd:string">Test Company Company address, 00100, Helsinki</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">contact_email</key>
                  <value xsi:type="xsd:string">company.contactemail@company.com</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">email</key>
                  <value xsi:type="xsd:string">company.companyemail@company.com</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">website</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">vat_number</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">receive_finvoice2</key>
                  <value xsi:type="xsd:string">0</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">default_receive_vendor_api_key</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">marketing_on_invoice</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoice_receiving</key>
                  <value xsi:type="xsd:string">true</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">print_attachments_disabled</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">bank_send</key>
                  <value xsi:type="xsd:string">true</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">scan_return_email</key>
                  <value xsi:type="xsd:string">company.email@company.com/value>
               </item>
               <item>
                  <key xsi:type="xsd:string">b2c_reminder</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">error_emails</key>
                  <value xsi:type="xsd:string">company.email@company.com/value>
               </item>
               <item>
                  <key xsi:type="xsd:string">reports</key>
                  <value xsi:type="xsd:string">0</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">notifications_disabled</key>
                  <value xsi:type="xsd:string">0</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">send_email_attachments</key>
                  <value xsi:type="xsd:string">1</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">print_and_send_enabled</key>
                  <value xsi:type="xsd:string">true</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_eia</key>
                  <value xsi:type="xsd:string">003723684781</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">scan_notification_email</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">errors_to_user</key>
                  <value xsi:type="xsd:string">1</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">print_and_send_letter_class</key>
                  <value xsi:type="xsd:string">1</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">b2c_fallback</key>
                  <value xsi:type="xsd:string">email</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">contact_phone</key>
                  <value xsi:type="xsd:string">111</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">peppol_id</key>
                  <value xsi:type="xsd:string">0037:003733686731</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">print_and_send_color</key>
                  <value xsi:type="xsd:string">false</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoicing_email</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">scan_notification_interval</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">invoice_email</key>
                  <value xsi:type="xsd:string"/>
               </item>
               <item>
                  <key xsi:type="xsd:string">notify_incoming</key>
                  <value xsi:type="xsd:string">true</value>
               </item>
               <item>
                  <key xsi:type="xsd:string">print_and_send_request</key>
                  <value xsi:type="xsd:string">true</value>
               </item>
            </settings>
         </return>
      </n1:show_company_configurationResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.show_company_configuration(api_keys)
if result['status'] == "OK"
  result['settings'].each do |x|
    puts "#{x['key']}: #{x['value']}"
  end
else
  puts result['status']
end

token_login

Returns a URL to access the web UI without needing to login.
Currently supports service parameter: FI_BANK_NETWORK_OPEN for opening Finnish bank network and COMPANY_SETTINGS for accessing setting page for given company.

Read more about companies and settings

/v1.1/api/token_login

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
service string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:token_login soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <service xsi:type="xsd:string">?</service>
      </sec:token_login>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
return string https://… Successfull request, URL can be accessed
ERROR: No rights to sign bank agreements User API key is for normal user
ERROR: Only available for Finnish companies Company uuid is for none Finnish company
ERROR: Bank agreement already active Company has already bank network connection
ERROR: Bank agreement already pending Company has already order the bank network opening
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:user_api_key] = ""
api_keys[:company_uuid] = ""

puts server.token_login(api_keys, "FI_BANK_NETWORK_OPEN")

# Output:
# https://testing.maventa.com/token_login/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2FwaV9rZXkiOiJlZGQwY2IzMi04YzE....

unlink_vendor_api_key

Unlinks company from vendor_api_key if company stops using ERP.

Read more about vendor api keys

/v1.1/api/unlink_vendor_api_key

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:unlink_vendor_api_key soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:unlink_vendor_api_key>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string “OK” or “ERROR: …”
Example API response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:unlink_vendor_api_keyResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:unlink_vendor_api_keyResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK
ERROR: COMPANY NOT ASSIGNED TO GIVEN VENDOR API KEY
Examples
Example Ruby implementation
require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

puts server.unlink_vendor_api_key(api_keys)

Used for uploading company logo to Maventa for PDF template output when PDF template is not generated in ERP. Most image formats are supported but not PDF. JPEG or PNG is preferred.

Read more about logo usage from the printing guide

/v1.1/api/update_logo

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

company_logo_params CompanyLogoParams

Key Type Description
logo base64 Company logofile
logo_h int deprecated, not used anymore
logo_w int deprecated, not used anymore
logo_x int deprecated, not used anymore
logo_y int deprecated, not used anymore
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:update_logo soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <company_logo_params xsi:type="sec:CompanyLogoParams">
            <logo xsi:type="soapenc:base64" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">Rvdsgsgbc456g...</logo>
         </company_logo_params>
      </sec:update_logo>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:update_logoResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK</return>
      </n1:update_logoResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK
ERROR: COULD NOT UPDATE LOGO File format not supported
ERROR: COULD NOT SAVE SETTINGS
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

company_logo_params = Hash.new
company_logo_params[:logo] = SOAP::Attachment.new(File.new("logo.png").to_s
company_logo_params[:logo_x] = 5

puts server.update_logo(api_keys, company_logo_params)

user_create_e

Used for creating a new or adding an existing user to a company.

After a new user creation an activation message will be sent to the given email address. This message will also include a randomly generated password for the user.

If on the user_create_e call either of the parameters notifications_disabled or emails_disabled is set as false, the account will not be usable until the user account is activated via accessing a link in the email.

If on the user_create_e call both parameters notifications_disabled and emails_disabled are set to true, the account will be activated immediately and no email activation is required. This is the recommended process for API only integrations.

Read more about companies and users

/v1.1/api/user_create_e

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

user_params UserParamsIn

Key Type Description
email string Email address, needs to be unique
user_role string Role can be ADMIN or USER. ADMIN has access to company settings etc.
first_name string First name for user, mandatory
last_name string Last name of user, mandatory
phone string Phone number
notifications_disabled boolean If set to true, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network)
emails_disabled boolean If set to true, user will not receive any e-mail notifications e.g. invoice send errors and such.
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:user_create_e soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <user_params xsi:type="sec:UserParamsInE">
            <!--You may enter the following 9 items in any order-->
            <notifications_disabled xsi:type="xsd:boolean">?</notifications_disabled>
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <emails_disabled xsi:type="xsd:boolean">?</emails_disabled>
            <password xsi:type="xsd:string">?</password>
            <user_role xsi:type="xsd:string">?</user_role>
            <first_name xsi:type="xsd:string">?</first_name>
            <last_name xsi:type="xsd:string">?</last_name>
            <password_confirmation xsi:type="xsd:string">?</password_confirmation>
         </user_params>
      </sec:user_create_e>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:user_create_eResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">ca65694d-2d3e-4100-9fd2-9544213d1b1e</return>
      </n1:user_create_eResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: USER ADDED When an existing user added to the company. The API key is not returned here for security reasons
36 char uuid API key for a new user
ERROR: NO RIGHTS TO ADD USERS Only admin user can add new users
ERROR: @errormessage Error message with validation errors for the user
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

user = Hash.new
user[:first_name]            = 'Test'
user[:last_name]             = 'Person2'
user[:email]                 = 'test.person2@company'
user[:phone]                 = '123-555-12345'
user[:user_role]             = 'USER' # Can be also ADMIN

puts server.user_create_e(api_keys, user)

user_delete

Used for deleting user from your company account. You cannot delete your own account.

/v1.1/api/user_delete

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:user_delete soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
      </sec:user_delete>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:user_deleteResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: USER DELETED FROM COMPANY</return>
      </n1:user_deleteResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK: USER DELETED FROM COMPANY User deleted successfully
ERROR: NO RIGHTS TO USER Only an admin can delete users
ERROR: USER NOT FOUND User with given user_id was not found
ERROR: CANNOT DELETE YOURSELF User cannot delete himself
ERROR: COULD NOT DELETE USER User could not be deleted for somea reason
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

puts server.user_delete(api_keys, "10f1626d-ceb6-414e-9120-bebd9d78524f")

user_list

Used for listing your company’s users.

/v1.1/api/user_list

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:user_list soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:user_list>
   </soapenv:Body>
</soapenv:Envelope>

Output

return UserParamsOutArray (Array of UserParamsOut)

Key Type Description
status string  
email string  
user_role string  
first_name string  
last_name string  
phone string  
id string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:user_listResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n2:Array" n2:arrayType="n1:UserParamsOut[2]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
            <item>
               <last_name xsi:type="xsd:string"/>
               <phone xsi:type="xsd:string"/>
               <id xsi:type="xsd:string">bf7cd218-d441-49d6-91fc-992682097524</id>
               <first_name xsi:type="xsd:string"/>
               <status xsi:type="xsd:string">OK</status>
               <email xsi:type="xsd:string">test.tester@testdomain.com</email>
               <user_role xsi:type="xsd:string">ADMIN</user_role>
            </item>
            <item>
               <last_name xsi:type="xsd:string"/>
               <phone xsi:type="xsd:string"/>
               <id xsi:type="xsd:string">bf7cd218-d441-48d6-91fc-292682097524</id>
               <first_name xsi:type="xsd:string"/>
               <status xsi:type="xsd:string">OK</status>
               <email xsi:type="xsd:string">test.tester2@testdomain.com</email>
               <user_role xsi:type="xsd:string">USER</user_role>
            </item>
         </return>
      </n1:user_listResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

results = server.user_list(api_keys)

if results[0].status == "OK"
  results.each do |result|
    puts result.first_name, result.last_name, result.email, result.user_role
  end
end

user_show

Used for showing information about a specific user.

/v1.1/api/user_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string Optional. Id of the user whuich information to return. If parameter is not given, information of the authenticating user will be returned
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:user_show soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
      </sec:user_show>
   </soapenv:Body>
</soapenv:Envelope>

Output

return UserParamsOut

Key Type Description
status string  
email string  
user_role string  
first_name string  
last_name string  
phone string  
id string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:user_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:UserParamsOut">
            <last_name xsi:type="xsd:string">Tester</last_name>
            <id xsi:type="xsd:string">bf7cd218-d441-49d6-91fc-992682097524</id>
            <phone xsi:type="xsd:string">0501234567891</phone>
            <first_name xsi:type="xsd:string">Test</first_name>
            <status xsi:type="xsd:string">OK</status>
            <email xsi:type="xsd:string">test.tester@testdomain.com<</email>
            <user_role xsi:type="xsd:string">ADMIN</user_role>
         </return>
      </n1:user_showResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: NO RIGHTS TO USER
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.user_show(api_keys, "123456-123123")

if result.status == "OK"
  puts result.first_name, result.last_name, result.email, result.user_role
end

user_update_e

Used for updating users details on your company account. You cannot update a user’s email address through the API.

/v1.1/api/user_update_e

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string  

user_params UserParamsIn

Key Type Description
email string  
user_role string  
first_name string  
last_name string  
phone string  
notifications_disabled boolean If set to true, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network)
emails_disabled boolean If set to false, user will not receive any e-mail notifications e.g. invoice send errors and such.
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:user_update_e soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
         <user_params xsi:type="sec:UserParamsInE">
            <!--You may enter the following 9 items in any order-->
            <notifications_disabled xsi:type="xsd:boolean">?</notifications_disabled>
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <emails_disabled xsi:type="xsd:boolean">?</emails_disabled>
            <password xsi:type="xsd:string">?</password>
            <user_role xsi:type="xsd:string">?</user_role>
            <first_name xsi:type="xsd:string">?</first_name>
            <last_name xsi:type="xsd:string">?</last_name>
            <password_confirmation xsi:type="xsd:string">?</password_confirmation>
         </user_params>
      </sec:user_update_e>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:user_update_eResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: USER SAVED</return>
      </n1:user_update_eResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: USER SAVED User updated successfully
ERROR: USER COULD NOT BE SAVEDS User could not be saved for some reason
ERROR: NO RIGHTS TO USER Only the user in question or an admin can update user information
ERROR: USER NOT FOUND User with given user_id was not found
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

user = Hash.new
user[:first_name]            = 'Test'
user[:last_name]             = 'Person2'
user[:phone]                 = '123-555-12345'
user[:emails_disabled]              = 'true'

puts server.user_update_e(api_keys, "10f1626d-ceb6-414e-9120-bebd9d78524f", user)

vendor_consumer_agreements_query

Checking status of existing agremeents by query for all companies under given vendor_api_key.

Read more about consumer invoicing in Norway

/v1.1/api/vendor_consumer_agreements_query

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

query ConsumerAgreementQuery

Key Type Description
name string  
phone string  
email string  
state string One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR
reference_nr string  
customer_nr string  
timestamp string Format YYYYMMDDHHMMSS (For example 20180401152042)
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:vendor_consumer_agreements_query soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <query xsi:type="sec:ConsumerAgreementQuery">
            <!--You may enter the following 7 items in any order-->
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <state xsi:type="xsd:string">?</state>
            <customer_nr xsi:type="xsd:string">?</customer_nr>
            <name xsi:type="xsd:string">?</name>
            <timestamp xsi:type="xsd:string">?</timestamp>
            <reference_nr xsi:type="xsd:string">?</reference_nr>
         </query>
      </sec:vendor_consumer_agreements_query>
   </soapenv:Body>
</soapenv:Envelope>

Output

return VendorConsumerAgreementQueryResponse

Key Type Description
status string  
results VendorConsumerAgreementQueryResultArray Array of VendorConsumerAgreementQueryResult

results VendorConsumerAgreementQueryResult

Key Type Description
company_id string  
agreements ConsumerInfoOutArray Array of ConsumerInfoOut

agreements ConsumerInfoOutArray

Key Type Description
state string One of REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR
name string  
phone string  
email string  
reference_nr string  
customer_nr string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:vendor_consumer_agreements_queryResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:VendorConsumerAgreementQueryResponse">
            <results n2:arrayType="n1:VendorConsumerAgreementQueryResult[0]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/"></results>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:vendor_consumer_agreements_queryResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: Timestamp format error
ERROR: No rights to vendor API key
ERROR: Unexpected error
Examples
Example Ruby implementation

require 'soap/wsdlDriver'
server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver
api_keys = Hash.new
api_keys[:user_api_key]   = ""
api_keys[:company_uuid]   = ""
api_keys[:vendor_api_key] = ""
query = Hash.new
query[:name] = "Test Consumer 1"
result = server.vendor_consumer_agreements_query(api_keys, query)
if result.status == "OK"
 result.results.each do |company|
   puts "Handling company: #{company.company_id}"
   company.agreements.each do |agreement|
    puts agreement.reference_nr
    puts agreement.customer_nr
   end
else
 puts result.status
end

postal_address_create

Used for adding a postal address for the company.

/v1.1/api/postal_address_create

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

company_postal PostalAddressParamsIn

Key Type Description
default boolean  
company_name string  
lang string  
state string  
post_code string  
post_office string  
phone string  
address1 string  
gsm string  
address2 string  
country string  
city string  
fax string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:postal_address_create soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <postal_address_params xsi:type="sec:PostalAddressParamsIn">
            <!--You may enter the following 13 items in any order-->
            <company_name xsi:type="xsd:string">?</company_name>
            <lang xsi:type="xsd:string">?</lang>
            <post_office xsi:type="xsd:string">?</post_office>
            <phone xsi:type="xsd:string">?</phone>
            <fax xsi:type="xsd:string">?</fax>
            <address1 xsi:type="xsd:string">?</address1>
            <gsm xsi:type="xsd:string">?</gsm>
            <country xsi:type="xsd:string">?</country>
            <state xsi:type="xsd:string">?</state>
            <address2 xsi:type="xsd:string">?</address2>
            <city xsi:type="xsd:string">?</city>
            <post_code xsi:type="xsd:string">?</post_code>
            <default xsi:type="xsd:boolean">?</default>
         </postal_address_params>
      </sec:postal_address_create>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: POSTAL ADDRESS SAVED Postal address created successfully
ERROR: @errormessage Error message with validation errors for the postal address
ERROR: COMPANY ALREADY HAS ADDRESS INFORMATION FOR @country / @lang Company can only have one postal address for each country and language pair
ERROR: COUNTRY CODE INVALID Given country code does not exist or is not supported
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

postal_address = Hash.new
postal_address[:address1]    = "Company address"
postal_address[:address2]    = ""
postal_address[:post_code]   = "00100"
postal_address[:post_office] = "Helsinki"
postal_address[:city]        = "Helsinki"
postal_address[:state]       = ""
postal_address[:country]     = "FI"

puts server.postal_address_create(api_keys, postal_address)

postal_address_list

Used for listing all the company’s postal addresses.

/v1.1/api/postal_address_list

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:postal_address_list soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
      </sec:postal_address_list>
   </soapenv:Body>
</soapenv:Envelope>

Output

return PostalAddressParamsOutArray (Array of PostalAddressParamsOut)

Key Type Description
status string  
default boolean  
lang string  
state string  
post_code string  
phone string  
post_office string  
address1 string  
gsm string  
city string  
country string  
id string  
address2 string  
fax string  
Example API response

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
      <n1:postal_address_listResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return n2:arrayType="n1:PostalAddressParamsOut[3]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
            <item>
               <state xsi:type="xsd:string"/>
               <lang xsi:nil="true"/>
               <fax xsi:type="xsd:string"/>
               <address1 xsi:type="xsd:string">Company address1</address1>
               <city xsi:type="xsd:string">HELSINKI</city>
               <post_office xsi:type="xsd:string">Helsinki</post_office>
               <gsm xsi:type="xsd:string"/>
               <id xsi:type="xsd:string">77224006-7765-4aee-99b1-cff67052cb6c</id>
               <post_code xsi:type="xsd:string">00100</post_code>
               <default xsi:type="xsd:boolean">true</default>
               <country xsi:type="xsd:string">FI</country>
               <phone xsi:type="xsd:string"/>
               <status xsi:type="xsd:string">OK</status>
               <address2 xsi:type="xsd:string">Company address1_2</address2>
            </item>
            <item>
               <state xsi:nil="true"/>
               <lang xsi:nil="true"/>
               <fax xsi:nil="true"/>
               <address1 xsi:type="xsd:string">Company address2</address1>
               <city xsi:type="xsd:string">HELSINKI</city>
               <post_office xsi:type="xsd:string">Helsinki</post_office>
               <gsm xsi:nil="true"/>
               <id xsi:type="xsd:string">f659aab7-bb39-4d31-884a-7262cbb188cc</id>
               <post_code xsi:type="xsd:string">00100</post_code>
               <default xsi:type="xsd:boolean">false</default>
               <country xsi:type="xsd:string">FI</country>
               <phone xsi:nil="true"/>
               <status xsi:type="xsd:string">OK</status>
               <address2 xsi:nil="true"/>
            </item>
         </return>
      </n1:postal_address_listResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

results = server.postal_address_list(api_keys)

if results[0].status == "OK"
  results.each do |result|
    puts result.id, result.address1, result.address2, result.post_code,
    result.post_office, result.city, result.state, result.country

  end
end

postal_address_show

Used displaying information for a specific postal address.

/v1.1/api/postal_address_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:postal_address_show soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
      </sec:postal_address_show>
   </soapenv:Body>
</soapenv:Envelope>

Output

return PostalAddressParamsOut

Key Type Description
status string  
default boolean  
lang string  
state string  
post_code string  
phone string  
post_office string  
address1 string  
gsm string  
city string  
country string  
id string  
address2 string  
fax string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:postal_address_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:PostalAddressParamsOut">
            <state xsi:type="xsd:string"/>
            <lang xsi:nil="true"/>
            <fax xsi:type="xsd:string"/>
            <address1 xsi:type="xsd:string">Company address1</address1>
            <city xsi:type="xsd:string">HELSINKI</city>
            <post_office xsi:type="xsd:string">Helsinki</post_office>
            <gsm xsi:type="xsd:string"/>
            <id xsi:type="xsd:string">77224006-7765-4aee-99b1-cff67052cb6c</id>
            <post_code xsi:type="xsd:string">00100</post_code>
            <default xsi:type="xsd:boolean">true</default>
            <country xsi:type="xsd:string">FI</country>
            <phone xsi:type="xsd:string"/>
            <status xsi:type="xsd:string">OK</status>
            <address2 xsi:type="xsd:string">Company address2</address2>
         </return>
      </n1:postal_address_showResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

result = server.postal_address_show(api_keys, "bc645d0c-64ed-4ad2-a8eb-bfc2af00ed46")

if result.status == "OK"
  puts result.id, result.address1, result.address2, result.post_code,
  result.post_office, result.city, result.state, result.country

end

postal_address_update

Used for updating an existing postal address.

/v1.1/api/postal_address_update

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string  

company_postal PostalAddressParamsIn

Key Type Description
default boolean  
company_name string  
lang string  
state string  
post_code string  
post_office string  
phone string  
address1 string  
gsm string  
address2 string  
country string  
city string  
fax string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:postal_address_update soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
         <postal_address_params xsi:type="sec:PostalAddressParamsIn">
            <!--You may enter the following 13 items in any order-->
            <company_name xsi:type="xsd:string">?</company_name>
            <lang xsi:type="xsd:string">?</lang>
            <post_office xsi:type="xsd:string">?</post_office>
            <phone xsi:type="xsd:string">?</phone>
            <fax xsi:type="xsd:string">?</fax>
            <address1 xsi:type="xsd:string">?</address1>
            <gsm xsi:type="xsd:string">?</gsm>
            <country xsi:type="xsd:string">?</country>
            <state xsi:type="xsd:string">?</state>
            <address2 xsi:type="xsd:string">?</address2>
            <city xsi:type="xsd:string">?</city>
            <post_code xsi:type="xsd:string">?</post_code>
            <default xsi:type="xsd:boolean">?</default>
         </postal_address_params>
      </sec:postal_address_update>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: POSTAL ADDRESS SAVED Postal address updated successfully
ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS Given postal_address_id not found for current company
ERROR: COUNTRY CODE INVALID Given country code does not exist or is not supported
ERROR: COMPANY ALREADY HAS ADDRESS INFORMATION FOR @country / @lang Company can only have one postal address for each country and language pair
ERROR: @errormessage Error message with validation errors for the postal address
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

postal_address = Hash.new
postal_address[:address1]    = "Company address updated"
postal_address[:address2]    = ""
postal_address[:post_code]   = "00100"
postal_address[:post_office] = "Helsinki"
postal_address[:city]        = "Helsinki"
postal_address[:state]       = ""
postal_address[:country]     = "FI"

puts server.postal_address_update(api_keys, "bc645d0c-64ed-4ad2-a8eb-bfc2af00ed46", postal_address)

postal_address_delete

Used for deleting postal address.

/v1.1/api/postal_address_delete

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
id string  
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="https://secure.maventa.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:postal_address_delete soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <api_keys xsi:type="sec:ApiKeys">
            <!--You may enter the following 5 items in any order-->
            <vendor_api_key xsi:type="xsd:string">?</vendor_api_key>
            <company_uuid xsi:type="xsd:string">?</company_uuid>
            <user_api_key xsi:type="xsd:string">?</user_api_key>
            <!--Optional:-->
            <license_key xsi:type="xsd:string">?</license_key>
            <license_meta xsi:type="xsd:string">?</license_meta>
         </api_keys>
         <id xsi:type="xsd:string">?</id>
      </sec:postal_address_delete>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
return string  
Example API response

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <env:Body>
      <n1:postal_address_deleteResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: POSTAL ADDRESS DELETED</return>
      </n1:postal_address_deleteResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK: POSTAL ADDRESS DELETED Postal address deleted successfully
ERROR: COULD NOT DELETE POSTAL ADDRESS Postal address could not be deleted
ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS Given postal_address_id not found for current company
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company

puts server.postal_address_delete(api_keys, "bc645d0c-64ed-4ad2-a8eb-bfc2af00ed46")

message_send

Used for sending SI-messages for B2C Finland. Returns OK and new message ID or ERROR. Note! Message needs to be XSD scheme valid and complete and it will get send to bank as it is so we do not make any additions or conversion to it. For SI message our system shows OK immediately when the message has been sent OK. Between the banks B2C messages can travel with delay up to 1-4 banking days so keep in mind that possible error messages can arrive even after a week to Maventa. If the message fails on the bank side you will get an error. If the message is ok, no separate message will be sent.

Read more about consumer invoicing in Finland

/banks/api/message_send

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

message base64

Key Type Description
file base64 SI-message file
Output

return MessageResponse

Key Type Description
status string Status string, includes OK or ERROR
message_id string 36 character UUID of new SI-message if successfully created
Return values
Key Type Message Description
return string OK
ERROR: DUPLICATE MESSAGEID Given message id is duplicate
ERROR: ONLY ONE MESSAGE PER FILE ALLOWED
ERROR: SOAP HEADER MISSING
ERROR: USER NOT FOUND
ERROR: COMPANY BANK CONNECTION NOT ACTIVE
ERROR: MESSAGE NOT FOUND OR NO RIGHTS

message_status

message_status method is used for getting the status of the sent SI-message (uses the UUID from the message_send method). In case SI message ends up in the error state in the sending bank side (which in our case is Danske Bank), error_message_list only returns SI message status as ERROR and won’t return any error reasons.

Read more about consumer invoicing in Finland

/banks/api/message_status

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

message_id string

Key Type Description
message_id string UUID message_id
Output

return MessageStatus

Key Type Description
status string Status string, includes OK or ERROR
message string Message
Return values
Key Type Message Description
return string OK
ERROR: USER NOT FOUND
ERROR: MESSAGE NOT FOUND OR NO RIGHTS

error_message_list

Used for listing error messages based on given timestamps. Returns status and a table that contains “id” and “original_id” (refers to the message UUID).

Read more about consumer invoicing in Finland

/banks/api/error_message_list

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
timestamp_start string start time for search, format “YYYYMMDDHHMMSS”
timestamp_end string end time for search, format “YYYYMMDDHHMMSS”
Output

return ErrorList

Key Type Description
status string Status
error_messages ErrorListMessageOut A table that contains “id” and “original_id” (refers to the SI-message UUID)

error_messages ErrorListMessageOut

Key Type Description
id string Error message id
original_id string SI-message UUID
Return values
Key Type Message Description
status string OK
ERROR: TIMESTAMP FORMAT INVALID FOR START TIMESTAMP
ERROR: TIMESTAMP FORMAT INVALID FOR END TIMESTAMP
ERROR: USER NOT FOUND
ERROR: UNKNOWN ERROR

error_message_show

method to download separate message from bank that contains the error reason.

Read more about consumer invoicing in Finland

/banks/api/error_message_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
error_message_id string error message id (uuid)
Output

return ErrorMessageOut

Key Type Description
status string Status of the API call
error_message base64 File contents in base64 format
Return values
Key Type Message Description
status string OK
ERROR: USER NOT FOUND
ERROR: MESSAGE NOT FOUND OR NO RIGHTS

ri_message_list

method to list UUIDs for RI messages received based on given timestamps. Returns status == “OK” and a table that contains UUIDs.

Read more about consumer invoicing in Finland

/banks/api/ri_message_list

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key (mandatory)
Key Type Description
timestamp_start string Start time for search, format “YYYYMMDDHHMMSS”
timestamp_end string End time for search, format “YYYYMMDDHHMMSS”
Output

return RiList

Key Type Description
status string Status of the API call
ri_message_ids Array RI-message ids
Return values
Key Type Message Description
status string OK
ERROR: TIMESTAMP FORMAT INVALID FOR START TIMESTAMP
ERROR: TIMESTAMP FORMAT INVALID FOR END TIMESTAMP

ri_message_show

method to download RI message.

Read more about consumer invoicing in Finland

/banks/api/ri_message_show

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
ri_message_id string RI-message id (uuid)
Output

return RiMessageOut

Key Type Description
status string Status of the API call
ri_message base64 File contents in base64 format
Return values
Key Type Message Description
status string OK
ERROR: USER NOT FOUND
ERROR: MESSAGE NOT FOUND OR NO RIGHTS

collection_send

Method for forwarding specific invoices for debt collection (COLLECTION) or to outsource reminder sending (NOTICE) for invoices that have past the due date. Reminders are sent and debt collection is handled by our partner Visma Duetto (Visma Financial Solutions Oy). Note! This service is only available for Finnish companies. When forwarding invoices to Visma Duetto for the first time you will get an email sent to your company email address to register as Visma Duetto customer and to confirm your assignments.

Soon out! If you want to outsource the whole receivables management we highly recommend you to check out our new Receivables management service done in a collaboration with Visma Financial Solutions Oy!

/v1.1/api/collection_send

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
invoices StringArray Array of string, containing invoice id’s for collection/notice
collection_type string collection or notice (reminder)
Output

return CollectionResponseArray (array of CollectionResponse)

Key Type Description
status string OK for those invoice sent successfully to Visma Duetto. ERROR and reason for the failed ones, e.g. ERROR: NOT EXPIRED
invoice_id string  
Return values
Key Type Message Description
status string OK
ERROR: COLLECTION TYPE MUST BE COLLECTION OR NOTICE
ERROR: NO INVOICES FOUND
ERROR: UNKNOWN ERROR
Examples
Example Ruby implementation

require 'soap/wsdlDriver'

server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver

api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company
  
invoices = Array.new
invoices.push("xxxxxxxxxxxxxxxxxxxxxx")
invoices.push("xxxxxxxxxxxxxxxxxxxxxx")
invoices.push("xxxxxxxxxxxxxxxxxxxxxx")
  
result = serv.collection_send(api_keys, invoices, "COLLECTION")
result.each do |i|
  puts "#{i.invoice_id}: #{i.status}"
end

register_duetto_payment

Method for informing direct payments to your company’s account for those invoices that have been forwarded to Visma Duetto for debt collection (see method collection_send).
Note! To be able to use this method there is a need for a manual account configurations from our end. Please contact sales@maventa.com.

/v1.1/api/register_duetto_payment

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key

duetto_payment_struct DuettoPaymentStruct

Key Type Description
payee_identification_number string Optional “9876543-2”
reference_number string Optional but recommended “1122334455”
invoicee_name string Mandatory “Asiakas yritys Oy”
invoicee_ytunnus string Mandatory “123456-9”
payee_name string Mandatory “Yritys maksaja Oy”
payment_day string Mandatory “05.04.2017” (4.4.2015 or 04.04.2015, future/past)
paid_amount string Mandatory “400,12”
invoice_number string Mandatory “1234”
Output
Key Type Description
status string  
Return values
Key Type Message Description
return string OK
ERROR: USER NOT FOUND
ERROR: VENDOR API KEY CANNOT BE BLANK
ERROR: NO RIGHTS TO USE THIS API Contact sales@maventa.com
Examples
Example Ruby implementation

require 'soap/wsdlDriver'
 
server = SOAP::WSDLDriverFactory.new("https://testing.maventa.com/apis/v1.1/wsdl").create_rpc_driver
 
api_keys = Hash.new
api_keys[:vendor_api_key] = "" # Partner software API key
api_keys[:user_api_key] = "" # User API key
api_keys[:company_uuid] = "" # UUID of current company
 
duetto_payment_struct = Hash.new
duetto_payment_struct[:invoicee_name] = "Asiakas yritys Oy" # mandatory
duetto_payment_struct[:invoicee_ytunnus] = "123456-9" # mandatory
duetto_payment_struct[:payee_identification_number] = "9876543-2" # optional
duetto_payment_struct[:payee_name] = "Yritys maksaja Oy" # mandatory
duetto_payment_struct[:invoice_number] = "1234" # mandatory
duetto_payment_struct[:payment_day] = "05.04.2017" # mandatory (4.4.2015 or 04.04.2015, future/past)
duetto_payment_struct[:paid_amount] = "400,12" # mandatory
duetto_payment_struct[:reference_number] = "1122334455" # optional but recommended
 
result = server.register_duetto_payment(api_keys, duetto_payment_struct)
puts result

atg_mandate_list

This method is used for listing changes to consumer mandates. Returns all changes after given timestamp.

Read more about consumer invoicing in Norway

/v1.1/api/list_company_actions

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
timestamp string format “YYYYMMDDHHMMSS”)
Output

return AtgMandateListResponse

Key Type Description
status string  
atg_mandates AtgMandateParamArray atg mandates

atg_mandates AtgMandateParamArray

Key Type Description
kid string  
account_number string  
notification boolean 1 - consumer wants to be notified of avtalegiro sends, 0 - consumer does not want notification
status integer 1 - active, 0 - inactive
updated_timestamp string  
Return values
Key Type Message Description
status string OK
ERROR: Timestamp format error
ERROR: Unexpected error
ERROR: No rights to settings

atg_agreement_configure

This method is used after setting up Avtalegiro agreement with the bank to inform AutoInvoice about the settings used so that changes to consumer mandates can be imported and used in routing.

Read more about consumer invoicing in Norway

/v1.1/api/atg_agreement_configure

Input

api_keys ApiKeys

Key Type Description
company_uuid string UUID of current company
user_api_key string User API key
vendor_api_key string Partner software API key
Key Type Description
account_number string Same account number than in the Avtalegiro agreement
kid_length integer Same kid length than in the Avtalegiro agreement
reference_position string Same reference position than in the Avtalegiro agreement. Example ‘1-6’
payment_type_position string Same payment type position number than in the Avtalegiro agreement. Example ‘1-6’
options string Can be used to disable print and/or email notifications when sending Avtalegiro without efaktura agreement. JSON format with keys ‘notif_print’ and ‘notif_email’ either true or false. Defaults to both true if not given
Output
Key Type Description
return string  
Return values
Key Type Message
return string OK
ERROR: Invalid payment_type_position
ERROR: Invalid reference_position
ERROR: Invalid kid_length
ERROR: Invalid account_number
ERROR: OPTIONS PARAMETER FORMAT IS INVALID
ERROR: UNKNOWN ERROR

Older, deprecated methods, which are used by older integrations.
See start of API methods for updated lists of relevant methods for new integration.

company_lookup

company_settings_show

company_settings_update

get_invoice_id

get_invoice_image_as_format

inbound_invoice_show

invoice_accept

invoice_confirm

invoice_create

Not recommended to use for new integrations!
We recommend using a method that creates invoices from existing XML files, e.g. invoice_put_invoice_with_metadata.

invoice_decline

invoice_dispute

invoice_put_file

invoice_put_finvoice

invoice_put_invoice

invoice_show_original_xml

list_company_actions

list_vendor_actions

partner_trx_list

user_create

user_update