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 endpoints below.
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

Business to Consumer (B2C) invoicing in Norway. Integration guide for consumer invoicing in Norway

Finland

Business to Consumer (B2C) invoicing in Finland. Integration guide for consumer invoicing in Finland

B2C Finland has it’s own WSDL:

WSDL address for B2C Finland (Testing environment)
WSDL address for B2C Finland (Production environment)

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

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 from Maventa, it doesn’t do any external lookups. 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

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: COMPANY ACCOUNT IS LOCKED Company's account is locked and can't be used
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 boolean Enable printing of attachments (true = enabled, false = disabled) The inverse setting, print_attachments_disabled, is also still supported for legacy reason (only one of these parameters should be used). Note! This setting only applies for FI, NO and NL companies. Printing of attachments is by default enabled for NO and NL companies, and disabled for 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 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, name can’t be empty and minimum lengt three(3) characters
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. 4 = Send all invoice e-mails with attachments (max size 5MB), all PDF attachments and the invoice image merged together in a single PDF file. 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 COMPANY SETTINGS Could not save settings for unknown reason
ERROR: BILLING E-INVOICING DETAILS INCOMPLETE E-invoicing address is incomplete: e-invoicing address (invoicing_eia) or operator (invoicing_operator) missing
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
ERROR: Cannot update billing company for partner accounts Partner account can't have billing company
ERROR: Company cannot be set as its own billing company
ERROR: Company is set as a billing company for another company
ERROR: Company is linked to an accounting office, billing company cannot be changed
ERROR: Invalid billing_company_id
ERROR: VAT NUMBER CANNOT BE SET TO BLANK
ERROR: INVOICE RECEIVING VALUE IS INVALID
ERROR: INVOICE RECEIVING CANNOT BE DISABLED WHEN SCAN ACCOUNT IS OPEN
ERROR: B2C REMINDER INVALID
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)

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
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 and for other attachments ATTACHMENT
filename string Original or service 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, value is empty if requested format is same as invoice’s original 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: INVOICE NOT COMPATIBLE WITH SELECTED FORMAT Invoice format specified is not compatible with original invoice format
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")]
result = server.invoice_download(api_keys, "12345678-90ab-cdef-1234-567890abcdef", ["teapps", "finvoice"], true, 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 Supported formats:
teapps30
siubl20
teapps
siubl12
peppolbis30
vismaubl30
vismaxml
svefaktura
sedi
oioubl
finvoice
finvoice30
ehf
peppolbis20
siubl11
vismaubl
e2b

metadata string

JSON struct, supports following parameters:

  • version string - Always 1.1.
  • uuid string - Specify unique invoice uuid, generated automatically if not specified.
  • lang string - Set invoice language. Language of PDF generated by us and email what recipient receives. Supported languages: FI SE NO DK NL EN
  • routing array - Routing details.
    • receiver_eia string - Receivers electronic address (e.g. EIA, OVT, GLN).
    • receiver_operator_id string - Receivers operator code.
    • receiver_email string - 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
      • dpi
      • email
      • print
  • recipient_type string - Only in Norway, set to consumer to use route_order array.
  • disabled_routes_out array - Routes that will not be tried, true means the route is disabled.
    • paper boolean
    • email boolean
    • relay boolean
  • payment_instruction_identifier string - PaymentInstructionIdentifier, used in Finnish B2C invoicing only.
  • extra array
    • sender_comment string - Text that will be added in the email message if invoice is delivered by email (max length 500 characters).

Example:

{
  "version":"1.1",
  "lang":"EN"
  "routing":{
    "receiver_eia":"00371111111",
    "receiver_operator_id":"003721291126"
  },
  "disabled_routes_out":{
    "paper":"false",
    "email":"false",
    "relay":"false"
  },
  "extra":{
    "sender_comment": "Text to the email"
  }
}
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: UNAUTHORIZED Company needs to complete customer authentication and be verified before sending
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 Supported formats:
nil
finvoice
finvoice20
finvoice30
teapps
teapps30
ubl
liinos
svefaktura
sedi
ehf
ehf20
vismaxml
vismaxml60
e2b
woodx
axflow
facturae
bgc
peppolbis20
peppolbis30
siubl
siubl12
siubl20
vismaubl
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 Invoiced quantity, dot as decimal separator, e.g. 1.50
price string Unit price, dot as decimal separator, e.g. ‘123.45’
tax double VAT percentage, dot as decimal separator, e.g. 24.0 is 24%
sum string VAT exclusive sum of the row, dot as decimal separator, e.g. ‘162.03’
sum_tax string VAT inclusive sum of the row, dot as decimal separator, e.g. ‘200.92’
item_code string Item code
definition string Additional definition for item (free text)
position int Position in item list
unit_type string Unit of item, e.g. ‘km’ or ‘h’
discount double Discount percentage, dot as decimal separator, e.g. 12.5 is 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 

<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]">
         <item>
            <attachment_type xsi:type="xsd:string">INVOICE_IMAGE</attachment_type>
            <filename xsi:type="xsd:string">invoice_123.pdf</filename>
            <file xsi:type="n2:base64">JVBERi0xLjMKJf..</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">123</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">email@address.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[2]" xsi:type="n3:Array">
         <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>
      </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]">
         <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">
         <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>

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:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <n1:list_operatorsResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:n1="https://secure.maventa.com/">
      <return xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/"
          n2:arrayType="n1:OperatorInfo[24]"
          xsi:type="n2:Array">
        <item>
          <operator_id href="#id70315172254900"></operator_id>
          <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">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">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">003701150617</operator_id>
          <name xsi:type="xsd:string">STRALFORS</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">B2CNO_AGIRO</operator_id>
          <name xsi:type="xsd:string">B2CNO_AGIRO</name>
        </item>
        <item>
          <operator_id xsi:type="xsd:string">5909000716438</operator_id>
          <name xsi:type="xsd:string">COMARCH</name>
        </item>
        <item>
          <operator_id xsi:type="xsd:string">CREDIFLOW</operator_id>
          <name xsi:type="xsd:string">CREDIFLOW</name>
        </item>
        <item>
          <operator_id href="#id70315172254900"></operator_id>
          <name xsi:type="xsd:string">AUTOINVOICE</name>
        </item>
      </return>
    </n1:list_operatorsResponse>
    <operator_id env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xsi:type="xsd:string"
        id="id70315172254900">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

This method is only for partners and requires a partner software API key.
It can be used to register new companies through the API with predefined password (if given).

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.

Read more about companies and settings

Before created account can be used for sending, receiving and activating services, customer authentication must be completed and account has to be verified.
Partner must make sure the user can read and understand the Terms of Service

Read more about verifying from here.

/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. Name has to be at least 3 characters long
company_bid string Company Business ID/Organization number/VAT number, 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

company_bid

Supported VAT/Business ID/Organization number types per country are

Country Type(s) Description and example
FI Y-TUNNUS, VAT Finnish Business Identity Code: 1111112-8 or VAT id: FI11111128
SE ORGNR, SSN Swedish Business Identity Code: 212000-0142 or social security number id: 810101-3608 or 19810101-3608
NO ORGNR Norwegian Business Identity Code: 111111111
DK CVR Danish unique identifier for a business in Denmark’s Central Business Register: DK11111114
NL KVK Netherlands Chamber of Commerce (KVK) number: 00006662
EE CC, VAT Estonian Company Code: 11111116 or VAT id: EE100591422
BE EN Belgian organisation number (CBE): 0111111124

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. Minimum length 8 characters.
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] = "1234567-1"

#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

Taking a new account into use requires that customer authentication process has been completed. Integrator can use their own customer authentication process or Maventa process provided by Visma Sign.

To complete customer authentication process use this method.
For Finnish companies the mehtod also initiates bank network opening.

Read more about company authentication from here.

/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 and should have signing rights or power of attorney to represent the company.
company_ids stringarray Array of company UUIDs to authorize. Admin user needs to have access 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 to provide proof of customer authentication process. Mandatory when partner has own customer authentication process.

Expects authorization_method key and optional require_auth key.
authorization_method - free text for explaining how customer authentication was done as well as giving an identifier(s) that links to event on partners side
require_auth - true to send out Visma Sign document for signing even when integrator in general uses own customer authentication
E.g. '{"authorization_method":"We have documents","require_auth":"true"}'
Output
Key Type
return string
Return values
Key Type Message Description
return string OK: Visma Sign document sent Invitation to sign has been sent to email given in the call. After signing is completed in Visma Sign service company status will change to verified.
OK: @x companies authorized Company account has been set to verfied. Account can be used to sending, reseiving and activating services. Happens only when partner has own customer authentication process in use.
ERROR: COMPANY AUTHORIZATION STATUS MISMATCH Given company / any of the given companies is already authorized.
ERROR: VENDOR API KEY CANNOT BE BLANK
ERROR: VENDOR API KEY INVALID OR DISABLED
ERROR: EMAIL ADDRESS INVALID
ERROR: LOCALE NOT SUPPORTED Given locale (country) is not supported
ERROR: AMOUNT OF COMPANIES TO SIGN NEEDS TO BE BETWEEN 1 to 50
ERROR: UNKNOWN ERROR

company_auth_status

To check the company authorization status which tells if company has completed customer authentication process.
In order to start sending, receiving and activating services the company_state needs to be verified.

Read more about company authorization from here.

/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 - Auth request sent to signer but not signed yet
SIGNED - Auth request signed
CANCELLED - Auth request has been cancelled, e.g. because time has expired
PENDING - Auth request created but not sent to signer yet
ERROR - Something unexpected has happened
auth_email string Email address used to sent the Visma Sign request to
company_state string unverified / verified / unknown, unverified companies cannot send, receive or activate services.
Return values
Key Type Message Description
return string OK: Visma Sign document sent Invitation to sign has been sent to email given in the call. After signing is completed in Visma Sign service company status will change to verified.
OK: Company authorized Company account has been set to verfied. Account can be used to sending, reseiving and activating services. Happens only when partner has own customer authentication process in use.
OK: No authorization requests No signing requests have been sent for the company
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
ERROR: SCAN ACCOUNT ACTIVATION FAILED MAVENTA SUPPORT WILL CONTACT YOU TO RESOLVE THE ISSUE The scan account activation has failed and you will be contacted to help resolve the issue an activate the account.
ERROR: SCAN ACCOUNT ACTIVATION IS PENDING The scan account is pending activation before it will be available to use.
ERROR: COMPANY DATA MISSING In order to activate the scan account please make sure your company address information is complete (address, postal code, city, email) and you have filled in the return addresses.
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

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. Note! The API method has a limitation on the age of invoices it can process. If the invoice is older than 2 years, the method will not function. Additionally, if more than 1000 IDs are provided, the limit is further reduced to 3 months.

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 boolean Shows if printing of attachments is disabled (false) or enabled (true)
print_attachments_disabled boolean Shows if printing of attachments is disabled (true) or enabled (false)
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. 4 = Send all invoice e-mails with attachments (max size 5MB), all PDF attachments and the invoice image merged together in a single PDF file. 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>
               
               And so on...

            </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.
PNG with transparency is not supported.

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>
            <user_role xsi:type="xsd:string">?</user_role>
            <first_name xsi:type="xsd:string">?</first_name>
            <last_name xsi:type="xsd:string">?</last_name>
         </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 ID of the postal address to show. Postal address IDs can be fetched with the postal_address_list method.
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 ID of the postal address to update. If set to nil, will default to the default address. Postal address IDs can be fetched with the postal_address_list method.

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: INVALID SENDER INTERMEDIATOR
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

ri_message_delete

Method to remove single RI message by ID. Returns OK/ERROR as status

Read more about consumer invoicing in Finland

/banks/api/ri_message_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
ri_message_id string RI-message id (uuid)
Output

return string

Key Type Description
status string Status of the API call, OK/ERROR
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.

Note! If an invoice is sent to Duetto using parameter NOTICE, the receiver will be reminded, after which the invoice will automatically go to collection if not paid. So there is no possibility to only outsource reminder sending.

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: SERVICE NOT ACTIVE
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

Notice! This API method will be removed soon as the Duetto service has been discontinued and replaced by Reskontravahti service.

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/atg_mandate_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 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. Example {“notif_print”:false,”notif_email”:true}
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

Old methods

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

Used to view current company settings.

This method is outdated. We recommend to use show_company_configuration.

/v1.1/api/company_settings_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_settings_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_settings_show>
   </soapenv:Body>
</soapenv:Envelope>

Output

return CompanySettingsParamsD

Key Type Description
status string Status for outbound struct
website string Website of company, displayed on invoice (depending on sending format)
print_and_send int Print&Send enabled
print_and_send_request int Print&Send enabled request (1=yes,0=no)
print_and_send_verified boolean Print&Send verified?
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
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 boolean Send invoice relay errors to users or just error email?
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
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_settings_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:CompanySettingsParamsD">
            <email_remind_freq xsi:type="xsd:int">0</email_remind_freq>
            <print_and_send_own_pdf xsi:type="xsd:boolean">false</print_and_send_own_pdf>
            <bid xsi:type="xsd:string">3348873-1</bid>
            <print_and_send xsi:type="xsd:int">3</print_and_send>
            <error_emails xsi:type="xsd:string">company.errors@companydomain.com</error_emails>
            <print_and_send_letter_class xsi:type="xsd:int">1</print_and_send_letter_class>
            <website xsi:type="xsd:string"/>
            <stop_duplicates xsi:type="xsd:boolean">false</stop_duplicates>
            <errors_to_user xsi:type="xsd:boolean">true</errors_to_user>
            <name xsi:type="xsd:string">Test Company Oy Ab</name>
            <print_and_send_verified xsi:type="xsd:boolean">true</print_and_send_verified>
            <reports_emails xsi:type="xsd:string"/>
            <invoice_email xsi:type="xsd:string"/>
            <country xsi:type="xsd:string">FI</country>
            <status xsi:type="xsd:string">OK</status>
            <print_and_send_request xsi:type="xsd:int">3</print_and_send_request>
            <email xsi:type="xsd:string">company.email@companydomain.com</email>
            <reports xsi:type="xsd:int">0</reports>
         </return>
      </n1:company_settings_showResponse>
   </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

result = server.company_settings_show(api_keys)

if result.status == "OK"
  puts result.print_and_send, result.invoice_email
end

company_settings_update

Used for updating company settings.

This method is outdated. We recommend to use configure_company.

/v1.1/api/company_settings_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

company_setting_params CompanySettingsParamsD

Key Type Description
status string Status for outbound struct
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)
print_and_send_own_pdf boolean Use own PDF images in Print&Send
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 boolean Send invoice relay errors to users or just error email?
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
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_settings_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>
         <company_setting_params xsi:type="sec:CompanySettingsParamsD">
            <!--You may enter the following 18 items in any order-->
            <status xsi:type="xsd:string">?</status>
            <print_and_send xsi:type="xsd:int">?</print_and_send>
            <errors_to_user xsi:type="xsd:boolean">?</errors_to_user>
            <print_and_send_letter_class xsi:type="xsd:int">?</print_and_send_letter_class>
            <email xsi:type="xsd:string">?</email>
            <bid xsi:type="xsd:string">?</bid>
            <print_and_send_own_pdf xsi:type="xsd:boolean">?</print_and_send_own_pdf>
            <reports xsi:type="xsd:int">?</reports>
            <country xsi:type="xsd:string">?</country>
            <website xsi:type="xsd:string">?</website>
            <stop_duplicates xsi:type="xsd:boolean">?</stop_duplicates>
            <reports_emails xsi:type="xsd:string">?</reports_emails>
            <invoice_email xsi:type="xsd:string">?</invoice_email>
            <email_remind_freq xsi:type="xsd:int">?</email_remind_freq>
            <print_and_send_verified xsi:type="xsd:boolean">?</print_and_send_verified>
            <error_emails xsi:type="xsd:string">?</error_emails>
            <name xsi:type="xsd:string">?</name>
            <print_and_send_request xsi:type="xsd:int">?</print_and_send_request>
         </company_setting_params>
      </sec:company_settings_update>
   </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_settings_updateResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: SETTINGS SAVED</return>
      </n1:company_settings_updateResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK: SETTINGS SAVED Settings saved successfully
ERROR: COULD NOT SAVE SETTINGS Could not save settings for some reason
ERROR: NO RIGHTS TO CHANGE SETTINGS Only admin user can change 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

settings = Hash.new
settings[:website]                = "http://company.com"
settings[:print_and_send_request]   = 1
settings[:print_and_send_letter_class]  = 1
settings[:stop_duplicates]        = true

puts server.company_settings_update(api_keys, settings)

get_invoice_id

Find invoice unique ID for given invoice number. Only works for unique hits per company.

/v1.1/api/get_invoice_id

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
invoice_number 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:get_invoice_id 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_number xsi:type="xsd:string">?</invoice_number>
      </sec:get_invoice_id>
   </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:get_invoice_idResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">ef0483ef-b2d0-4be2-a4fe-22dd8127652a</return>
      </n1:get_invoice_idResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string INVOICE ID 36 character UUID
ERROR: NO INVOICE NUMBER GIVEN
ERROR: NO INVOICE FOUND
ERROR: MULTIPLE INVOICES FOUND WITH NUMBER #{invoice_number}
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.get_invoice_id(api_keys, "1234")
if result =~ /ERROR/
  puts result
else
  puts "Invoice ID is: #result"
end

get_invoice_image_as_format

Returns given invoice’s invoice image in specified format (normally PDF). Currently only supports TIFF.

/v1.1/api/get_invoice_image_as_format

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
invoice_id string Invoice UUID
image_format string Format, currently only TIFF
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_invoice_image_as_format 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>
         <image_format xsi:type="xsd:string">?</image_format>
      </sec:get_invoice_image_as_format>
   </soapenv:Body>
</soapenv:Envelope>

Output
Key Type Description
     
Example API response 

Sorry, there is no example available for this method.

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.get_invoice_image_as_format(api_keys, "1276f4d5-4eff-4f4d-bd23-cab71bd226a6", "TIFF")
if result
  fa = result.first
  puts "Saving attachment #{fa.filename}"
  File.open("#{fa.filename}", 'wb') { |f| f << fa.file }
else
puts "Error"
end

inbound_invoice_show

Used for getting information about a specific inbound invoice.

/v1.1/api/inbound_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 Specify with exclamation mark to exclude invoice items from the response.
Supported invoice formats:
finvoice
finvoice2
finvoice30
teapps
teapps30
ebis
ubl
liinos
svefaktura
sedi
ehf
vismaxml
vismaxml60
e2b
woodx
facturae
bgc
ubl
peppolbis20
siubl11
siubl20

It is possible to get only the API-struct, meaning the invoice’s information not in any spcecific format by passing nil/empty/null as xmlformat. Do not pass it as a 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:inbound_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:inbound_invoice_show>
   </soapenv:Body>
</soapenv:Envelope>

Output
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
delivery_type string Delivery type (e.g. mail)
reference_nr string Invoice reference number
date string Invoicing date
date_due string Invoice due date
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 InvoiceDeliveryAddressIn  
invoice_seller_information InvoiceSellerInformationIn  
items ItemsOutArray Array of ItemsOut
attachments FileAttachmentArray Array Of FileAttachment
accounts InvoiceAccountParamsOutArray Array of InvoiceAccountParamsOut

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  

items ItemsOutArray

Key Type Description
subject string Subject string
amount double Invoiced quantity, dot as decimal separator, e.g. 1.50
price string Unit price, dot as decimal separator, e.g. ‘123.45’
tax double VAT percentage, dot as decimal separator, e.g. 24.0 is 24%
sum string VAT exclusive sum of the row, dot as decimal separator, e.g. ‘162.03’
sum_tax string VAT inclusive sum of the row, dot as decimal separator, e.g. ‘200.92’
item_code string Item code
definition string Additional definition for item (free text)
position int Position in item list
unit_type string Unit of item, e.g. ‘km’ or ‘h’
discount double Discount percentage, dot as decimal separator, e.g. 12.5 is 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  
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:inbound_invoice_showResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:InboundInvoiceParamsOutC">
            <customer_country xsi:type="xsd:string">FI</customer_country>
            <items xsi:type="n2:Array" n2:arrayType="n1:ItemsOut[1]" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <discount xsi:type="xsd:double"/>
                  <tax xsi:type="xsd:double">24</tax>
                  <subject xsi:type="xsd:string">SUBJECT</subject>
                  <position xsi:type="xsd:int">1</position>
                  <price xsi:type="xsd:string">100</price>
                  <item_code xsi:type="xsd:string">123456</item_code>
                  <sum_tax xsi:type="xsd:string">24</sum_tax>
                  <amount xsi:type="xsd:double">+1</amount>
                  <sum xsi:type="xsd:string">124</sum>
                  <definition xsi:nil="true"/>
                  <unit_type xsi:type="xsd:string">kpl</unit_type>
               </item>
            </items>
            <company_country>FI</company_country>
            <company_reminder xsi:nil="true"/>
            <state xsi:type="xsd:int">1</state>
            <user_phone>0501234567891</user_phone>
            <delivery_type xsi:nil="true"/>
            <customer_address2 xsi:nil="true"/>
            <company_post_code>01620</company_post_code>
            <payment_terms>30 päivää netto</payment_terms>
            <customer_nr/>
            <customer_email xsi:nil="true"/>
            <company_fax xsi:nil="true"/>
            <company_reference xsi:nil="true"/>
            <company_interest>8.0</company_interest>
            <date>20191106</date>
            <company_state xsi:nil="true"/>
            <currency>EUR</currency>
            <lang>FI</lang>
            <customer_state xsi:nil="true"/>
            <company_address2 xsi:nil="true"/>
            <company_website xsi:nil="true"/>
            <user_email>user.email@emails.com</user_email>
            <delivery_date xsi:nil="true"/>
            <customer_address1>CUSTOMER_ADDRESS1</customer_address1>
            <work_order_nr xsi:nil="true"/>
            <customer_reference xsi:nil="true"/>
            <company_gsm xsi:nil="true"/>
            <customer_name>CUSTOMER_NAME</customer_name>
            <accounts n3:arrayType="n1:InvoiceAccountParamsOut[2]" xsi:type="n3:Array" xmlns:n3="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <bank>TESTBANKFIHH</bank>
                  <account xsi:nil="true"/>
                  <swift>NDEAFIHH</swift>
                  <iban>FI14368</iban>
               </item>
            </accounts>
            <sum_tax>24</sum_tax>
            <company_city xsi:nil="true"/>
            <id>a873382c-6fdd-4df8-86f0-58d86e1d51ed</id>
            <customer_post_office>HELSINKI</customer_post_office>
            <attachments xsi:nil="true"/>
            <date_due>20181215</date_due>
            <company_name>CUSTOMER_NAME</company_name>
            <order_nr>ORDER_NUMBER</order_nr>
            <notes xsi:nil="true"/>
            <company_address1>STREET_ADDRESS1 19</company_address1>
            <user_name>USER_NAME</user_name>
            <customer_contact_p xsi:nil="true"/>
            <invoice_seller_information xsi:nil="true"/>
            <company_paper_fee xsi:nil="true"/>
            <company_phone>+358 9 123456789</company_phone>
            <customer_ovt>003733686731</customer_ovt>
            <sum>124</sum>
            <status>OK</status>
            <reference_nr>987654321</reference_nr>
            <customer_post_code>00100</customer_post_code>
            <company_post_office>Helsinki</company_post_office>
            <customer_bid>0163756-4</customer_bid>
            <company_comment xsi:nil="true"/>
            <invoice_delivery_address xsi:type="n1:InvoiceDeliveryAddressOut">
               <state xsi:nil="true"/>
               <address1>ADDRESS1</address1>
               <country>FI</country>
               <post_office>HELSINKI</post_office>
               <name>Refy</name>
               <id>c8d27953-b8ae-4e3f-b9d3-18499c59b447</id>
               <post_code>00100</post_code>
               <address2 xsi:nil="true"/>
            </invoice_delivery_address>
            <invoice_nr>123456</invoice_nr>
            <company_bid>0163756-4</company_bid>
            <company_email xsi:nil="true"/>
         </return>
      </n1:inbound_invoice_showResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: INVOICE NOT FOUND OR NO RIGHTS
ERROR: FORMAT NOT SUPPORTED Invoice format specified is not supported
ERROR: INVOICE NOT COMPATIBLE WITH SELECTED FORMAT Conversion to reqeusted format is not supported
ERROR: FORMAT IS NO LONGER SUPPORTED Format that was requested is not supported anymore. Please pick another format.
ERROR: XML GENERATION FAILED
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.inbound_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.push(fa.file)
      end
    end
  end
end

invoice_accept

Used for accepting incoming invoice. This means that the invoice and the contents seems to be legit according to an agreement. The acceptance sends a notification to the invoice sender so they know you have received the invoice.
Note! Only inside Maventa network.

/v1.1/api/invoice_accept

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
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_accept 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:invoice_accept>
   </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:invoice_acceptResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: INVOICE ACCEPTED</return>
      </n1:invoice_acceptResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: INVOICE ACCEPTED Invoice accepted successfully
ERROR: INVOICE NOT FOUND OR NO RIGHTS Given invoice_id was not found or user has no rights to it
ERROR: INVOICE STATE DOES NOT ALLOW ACCEPTANCE Invoice state is not “SENT” which is the only state from which - invoice can be accepted
ERROR: COULD NOT ACCEPT INVOICE Could not save invoice for some other 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.invoice_accept(api_keys, "00521759-4570-467c-98dd-c496b22de0bc")

invoice_confirm

Used for marking an outbound invoice as paid, meaning you have received payment and want to archive the invoice.

/v1.1/api/invoice_confirm

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  
payment_date string Date when payment was made (format: 20180319)
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_confirm 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>
         <payment_date xsi:type="xsd:string">?</payment_date>
      </sec:invoice_confirm>
   </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:invoice_confirmResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: INVOICE MARKED AS PAID</return>
      </n1:invoice_confirmResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: INVOICE MARKED AS PAID Invoice successfully marked as paid
ERROR: COULD NOT MARK INVOICE AS PAID Could not save invoice for some other reason
ERROR: INVOICE NOT FOUND OR NO RIGHTS Given invoice_id was not found or user has no rights to it
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.invoice_confirm(api_keys, "3b24eff1-50d2-4e67-b16c-8b711e87df15", "20090917")

invoice_create

We recommend using a method that creates invoices from existing XML files, e.g. invoice_put_invoice_with_metadata.

Used for creating new invoices.
Note! If you want to create a credit note, provide all the sums as negative, because there is no separate parameter for the invoice type.

/v1.1/api/invoice_create

Input

invoice_params InvoiceParamsInC

Key Type Description
customer_maventa_id string Customer Maventa ID
currency string Currency abbrevation
invoice_nr string Invoice number
order_nr string Company’s order number (seller). If also customer (buyer) order number is needed both values can be given separated with | character (”company_order_nr | customer_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
notes string Additional information for invoice
company_website string Company’s website, shown on PDF invoice
lang string Language code for invoice (Allowed values are FI, SE, EN, NO, DK, NL)
require_sign bool Require signing before send
work_order_nr string Work order nr
payment_terms string Payment terms
data string JSON input for extra parameters. Currently supports key payment_instruction_identifier needed for Finnish B2C invoicing
items ItemsInArray Array of ItemsIn
attachments FileAttachmentArray Array of FileAttachment
bank_accounts BankAccountParamsInArray Array of BankAccountParamsIn
disabled_routes RouteDisable  
customer CustomerParamsIn  
company_postal PostalAddressParamsIn  
invoice_delivery_address InvoiceDeliveryAddressIn  
invoice_seller_information InvoiceSellerInformationIn  

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

items ItemsInArray

Key Type Description
sum string VAT exclusive sum of the row, dot as decimal separator, e.g. ‘162.03’
subject string Subject string
discount double Discount percentage, dot as decimal separator, e.g. 12.5 is 12.5%
price string Unit price, dot as decimal separator, e.g. ‘123.45’
amount double Invoiced quantity, dot as decimal separator, e.g. 1.50
position int Position in item list
definition string Additional definition for item (free text)
item_code string Item code
tax double VAT percentage, dot as decimal separator, e.g. 24.0 is 24%
sum_tax string VAT inclusive sum of the row, dot as decimal separator, e.g. ‘200.92’
unit_type string Unit of item, e.g. ‘km’ or ‘h’

attachments FileAttachmentArray

Key Type Description
attachment_type string  
filename string  
file base64  

bank_accounts BankAccountParamsInArray

Key Type Description
account string  
default boolean  
iban string  
swift string  
bank string  

disabled_routes RouteDisable

Key Type Description
email boolean  
paper boolean  
relay boolean  

customer CustomerParamsIn

Key Type Description
customer_type string  
email string  
lang string Allowed values are FI, SE, EN, NO, DK, NL
name string  
state string  
post_code string  
phone string  
post_office string  
customer_nr int  
ovt string Operator code can be added after ovt and @ sign, e.g. 003712345678@003721291126
bid string  
address1 string  
gsm string  
country string  
address2 string  
contact_p 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  

invoice_delivery_address InvoiceDeliveryAddressIn (Invoice delivery address)

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

invoice_seller_information InvoiceSellerInformationIn (Invoice seller information)

Key Type Description
phone string  
name string  
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/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <sec:invoice_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>?</vendor_api_key>
            <company_uuid>?</company_uuid>
            <user_api_key>?</user_api_key>
            <!--Optional:-->
            <license_key>?</license_key>
            <license_meta>?</license_meta>
         </api_keys>
         <invoice_params xsi:type="sec:InvoiceParamsInC">
            <!--You may enter the following 32 items in any order-->
            <lang>?</lang>
            <sum_tax>?</sum_tax>
            <invoice_seller_information xsi:type="sec:InvoiceSellerInformationIn">
               <!--You may enter the following 3 items in any order-->
               <phone>?</phone>
               <email>?</email>
               <name>?</name>
            </invoice_seller_information>
            <work_order_nr>?</work_order_nr>
            <company_reference>?</company_reference>
            <payment_terms>?</payment_terms>
            <currency>?</currency>
            <date_due>?</date_due>
            <company_reminder>?</company_reminder>
            <customer xsi:type="sec:CustomerParamsInC">
               <!--You may enter the following 16 items in any order-->
               <lang>?</lang>
               <post_office>?</post_office>
               <phone>?</phone>
               <email>?</email>
               <ovt>?</ovt>
               <bid>?</bid>
               <address1>?</address1>
               <contact_p>?</contact_p>
               <gsm>?</gsm>
               <customer_type>?</customer_type>
               <country>?</country>
               <state>?</state>
               <address2>?</address2>
               <customer_nr>?</customer_nr>
               <name>?</name>
               <post_code>?</post_code>
            </customer>
            <items xsi:type="sec:ItemsInCArray" soapenc:arrayType="sec:ItemsInC[]"/>
            <company_postal xsi:type="sec:PostalAddressParamsIn">
               <!--You may enter the following 13 items in any order-->
               <company_name>?</company_name>
               <lang>?</lang>
               <post_office>?</post_office>
               <phone>?</phone>
               <fax>?</fax>
               <address1>?</address1>
               <gsm>?</gsm>
               <country>?</country>
               <state>?</state>
               <address2>?</address2>
               <city>?</city>
               <post_code>?</post_code>
               <default xsi:type="xsd:boolean">?</default>
            </company_postal>
            <disabled_routes xsi:type="sec:RouteDisable">
               <!--You may enter the following 3 items in any order-->
               <email xsi:type="xsd:boolean">?</email>
               <paper xsi:type="xsd:boolean">?</paper>
               <relay xsi:type="xsd:boolean">?</relay>
            </disabled_routes>
            <delivery_type>?</delivery_type>
            <delivery_date>?</delivery_date>
            <customer_reference>?</customer_reference>
            <invoice_delivery_address xsi:type="sec:InvoiceDeliveryAddressIn">
               <!--You may enter the following 7 items in any order-->
               <post_office>?</post_office>
               <address1>?</address1>
               <country>?</country>
               <state>?</state>
               <address2>?</address2>
               <name>?</name>
               <post_code>?</post_code>
            </invoice_delivery_address>
            <require_sign xsi:type="xsd:boolean">?</require_sign>
            <invoice_nr>?</invoice_nr>
            <company_comment>?</company_comment>
            <customer_maventa_id>?</customer_maventa_id>
            <company_website>?</company_website>
            <company_interest>?</company_interest>
            <date>?</date>
            <order_nr>?</order_nr>
            <attachments xsi:type="sec:FileAttachmentArray" soapenc:arrayType="sec:FileAttachment[]"/>
            <notes>?</notes>
            <sum>?</sum>
            <data>?</data>
            <company_paper_fee>?</company_paper_fee>
            <reference_nr>?</reference_nr>
            <bank_accounts xsi:type="sec:BankAccountParamsInArray" soapenc:arrayType="sec:BankAccountParamsIn[]"/>
         </invoice_params>
      </sec:invoice_create>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceStatus

Key Type Description
status string  
invoice_id string  
file_statuses FileStatusArray Array of FileStatus

file_statuses FileStatusArray

Key Type Description
status string  
filehash string  
filename string  
Example API response 

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: INVOICE CREATED Everything went OK and invoice will be sent
ERROR: ALL SEND ROUTES DISABLED Disabled_routes is 111 which leads to invoice not being sent at all
ERROR: INVALID FILETYPE _@filename_ Allowed filetypes .tif, .jpg, .gif, .txt, .xml, .xls, .xsl, .html, .htm, .pdf, .aix, .doc
ERROR: FILENAME CONTAINS INVALID CHARACTERS Only letters, numbers, underscore and dot are allowed in file names
ERROR: INVALID FILE ATTACHMENT ATTACHMENT_TYPE Currently allowed ATTACHMENT_TYPEs are: “ATTACHMENT”, “INVOICE_IMAGE”, “FINVOICE”, “TEAPPS”
ERROR: COMPANY HAS NO POSTAL ADDRESS AND NO ADDRESS GIVEN Company has no postal address set or given in request
ERROR: COULD NOT CREATE INVOICE Invoice saving failed for some reason, please contact support with timestamp of request
ERROR: AN ITEM IS NOT VALID An item does not have all required values (subject, price, amount, tax, sum, sum_tax)
ERROR: NO ITEMS FOUND No items in items array, invoice needs at least one item
ERROR: DATE FORMAT INVALID FOR DELIVERY DATE Invalid date format
ERROR: DATE FORMAT INVALID FOR DUE DATE Invalid date format
ERROR: DATE FORMAT INVALID FOR INVOICE DATE Invalid date format
ERROR: LANGUAGE @lang IS NOT VALID Given language is not supported
ERROR: COMPANY HAS NO POSTAL ADDRESS Company has no postal address set
ERROR: UNKNOWN ERROR Something unexpected happened, please contact support with timestamp of request
ERROR: CUSTOMER COUNTRY CODE INVALID Country code given in customer information is nit supported
ERROR: NO CUSTOMER INFORMATION FOUND No customer information given (maventa_id or the whole CustomerParamsOut)
ERROR: CUSTOMER COMPANY NOT FOUND WITH MAVENTA ID _@maventaid_ Maventa ID given for customer but no such id exists
ERROR: FILE @file NOT FOUND, INVOICE WAS NOT CREATED An attachment was specified in the creation call but no file with that name was 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

#Set up customer information
customer = Hash.new
customer[:customer_nr] = "1001"
customer[:name] = "Test Customer"
customer[:address1] = "Post Address"
customer[:post_code] = "00100"
customer[:post_office] = "TEST"
customer[:country] = "FI"
customer[:lang] = "FI"
customer[:contact_p] = "John Doe"
customer[:email] = "customer@maventa.com"
customer[:bid] = "FI1234567"
customer[:ovt] = "00371111111"

#Set up invoice items
items_out = Array.new
inv_item = Hash.new
inv_item[:subject]    = "Test item"
inv_item[:unit_type]  = "pcs"
inv_item[:amount]     = "1"
inv_item[:price]      = "200"
inv_item[:discount]   = "50"
inv_item[:definition] = ""
inv_item[:tax]        = "22"
inv_item[:sum]        = "100"
inv_item[:sum_tax]    = "122"
items_out.push(inv_item)

#Set up attachments
attachments_out = Array.new
fa = Hash.new
fa[:filename] = "invoice_1001.pdf"
fa[:file] = SOAP::Attachment.new(File.new("invoice_1001.pdf"))
fa[:attachment_type] = "INVOICE_IMAGE"
attachments_out.push(fa)

fa = Hash.new
fa[:filename] = "attachment_1001.doc"
fa[:file] = SOAP::Attachment.new(File.new("attachment_1001.doc"))
fa[:attachment_type] = "ATTACHMENT"
attachments_out.push(fa)

#Set up invoice information
invoice = Hash.new
invoice[:invoice_nr] = 1001
invoice[:date] = "20090915"
invoice[:date_due] = "20090930"
invoice[:currency] = "EUR"
invoice[:notes] = "TEST INVOICE / DO NOT PAY"
invoice[:sum] = "100"
invoice[:sum_tax] = "122"
invoice[:customer] = customer
invoice[:items] = items_out
invoice[:attachments] = attachments_out

#JSON input for setting PaymentInstructionIdentifier needed for Finnish B2C invoicing
#invoice[:data] = '{"payment_instruction_identifier":"PID554433"}'

#Create the invoice
result = server.invoice_create(api_keys, invoice)

puts result.status

invoice_decline

Used for declining incoming invoice in cases where they contain an error. Note! Will automatically notify sender of decline only inside Maventa network.

/v1.1/api/invoice_decline

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  
message 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_decline 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>
         <message xsi:type="xsd:string">?</message>
      </sec:invoice_decline>
   </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:invoice_declineResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: INVOICE DECLINED</return>
      </n1:invoice_declineResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: INVOICE DECLINED Invoice declined successfully
ERROR: COULD NOT DECLINE INVOICE Could not save invoice for some other reason
ERROR: INVOICE STATE DOES NOT ALLOW ACCEPTANCE Invoice state is not _SENT_ which is the only state from which invoice can be declined
ERROR: INVOICE NOT FOUND OR NO RIGHTS Given _invoice_id_ was not found or user has no rights to it
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.invoice_decline(api_keys, "00521759-4570-467c-98dd-c496b22de0bc",
                            "Message, why invoice was declined")

invoice_dispute

Used for disputing an invoice. This means that you consider the invoice to be fraudulent and is not the same as just declining an invoice that has something wrong! Maventa administrator will get notified and actions will be taken against sender if deemed necessary.

/v1.1/api/invoice_dispute

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  
message string Message for sender about the dispute
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_dispute 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>
         <message xsi:type="xsd:string">?</message>
      </sec:invoice_dispute>
   </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:invoice_disputeResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="xsd:string">OK: INVOICE DISPUTED</return>
      </n1:invoice_disputeResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
return string OK: INVOICE DISPUTED Invoice disputed successfully
ERROR: COULD NOT DISPUTE INVOICE Could not save invoice for some reason
ERROR: INVOICE STATE DOES NOT ALLOW ACCEPTANCE Invoice state is not “SENT” which is the only state from which invoice can be disputed
ERROR: INVOICE NOT FOUND OR NO RIGHTS Given invoice_id was not found or user has no rights to it
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.invoice_dispute(api_keys, "00521759-4570-467c-98dd-c496b22de0bc",
                            "Message, why invoice is disputed")

invoice_put_file

Used for creating new invoices from existing XML invoice files or ZIP files with XML files and attachments.

This method is outdated. We recommend to use invoice_put_invoice_with_metadata.

/v1.1/api/invoice_put_file

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  
filename string Allowed characters [A-z0-9_.-] (no spaces or other special characters allowed)
file base64  
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_file 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>
         <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/">FFD3fdsvsddv3t32</file>
            <attachment_type xsi:type="xsd:string">?</attachment_type>
            <filename xsi:type="xsd:string">?</filename>
         </file_in>
      </sec:invoice_put_file>
   </soapenv:Body>
</soapenv:Envelope>

Output

return FileStatusArray

Key Type Description
status string  
filehash string  
filename string  
Example API response 

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: INVOICE CREATED
OK: INVOICE CREATED SUCCESSFULLY
ERROR: NO INVOICE FILE FOUND
ERROR: FILENAME CONTAINS INVALID CHARACTERS
ERROR: INVALID FILENAME
ERROR: INVALID FILETYPE
ERROR: FILE #{current_file} IS EMPTY
ERROR: INVALID ZIP FILE
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"

results = server.invoice_put_file(api_keys, file_out)
results.each do |result|
  puts result.status
end

invoice_put_finvoice

Used for creating new invoices from existing Finvoice XML files or ZIP files with Finvoice XML files and attachments.

Since Finvoice XML does not have support for attachment, the method is very strictly defined so that only one XML is allowed per request and all other files are considered attachments. If a PDF document with the same filename as the XML file exists, it is used as invoice image.

This method is outdated. We recommend to use invoice_put_invoice_with_metadata.

/v1.1/api/invoice_put_finvoice

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

finvoice_in FinvoiceTrx

Key Type Description
files ActionWebService..Base64Array  
filenames StringArray Allowed characters [A-z0-9_.-] (no spaces or other special characters allowed)
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_put_finvoice 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>
         <finvoice_in xsi:type="sec:FinvoiceTrx">
            <!--You may enter the following 2 items in any order-->
            <files xsi:type="sec:ActionWebService..Base64Array" soapenc:arrayType="soapenc:base64[]"/>
            <filenames xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[]"/>
         </finvoice_in>
      </sec:invoice_put_finvoice>
   </soapenv:Body>
</soapenv:Envelope>

Output

return InvoiceStatus

Key Type Description
status string  
invoice_id string  
file_statuses FileStatusArray Array of FileStatus

file_statuses FileStatus

Key Type Description
status string  
filehash string  
filename string  
Example API response 

Sorry, there is no example available for this method.

Return values
Key Type Message Description
status string OK: INVOICE CREATED SUCCESSFULLY
ERROR: NO XML FILE OR MORE THAN ONE FOUND
ERROR: FILES OR FILENAMES BLANK OR COUNT DOES NOT MATCH
ERROR: FILE IS EMPTY
ERROR: FILENAME CONTAINS INVALID CHARACTERS
ERROR: FILENAME CONTAINS INVALID CHARACTERS OR IS INVALID TYPE
ERROR: FILENAME INSIDE ZIP CONTAINS INVALID CHARACTERS OR IS INVALID TYPE
ERROR: INVALID ZIP FILE
ERROR: COULD NOT SAVE FILES TO DISK
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

files_out = Hash.new
files_out[:files] = []
files_out[:filenames] = []

files_out[:files].push(SOAP::Attachment.new(File.new("finvoice.xml")))
files_out[:filenames].push("finvoice.xml")
files_out[:files].push(SOAP::Attachment.new(File.new("finvoice.pdf")))
files_out[:filenames].push("finvoice.pdf")

result = server.invoice_put_finvoice(api_keys, files_out)
puts result.status

invoice_put_invoice

Used for creating new invoices from existing XML invoice files or ZIP files with XML files and attachments.

This method is outdated. We recommend to use invoice_put_invoice_with_metadata.

/v1.1/api/invoice_put_invoice

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 Supported formats:
vismaxml
svefaktura
sedi
e2b
ehf
peppolbis20
siubl11
vismaubl
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 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>
         <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/">cid:850761575223</file>
            <attachment_type xsi:type="xsd:string">?</attachment_type>
            <filename xsi:type="xsd:string">?</filename>
         </file_in>
         <xmlformat xsi:type="xsd:string">?</xmlformat>
      </sec:invoice_put_invoice>
   </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 

Sorry, there is no example available for this method.

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"

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

invoice_show_original_xml

Used for getting the original XML file for a specified received (inbound) or sent (outbound) invoice.

/v1.1/api/invoice_show_original_xml

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:invoice_show_original_xml 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:invoice_show_original_xml>
   </soapenv:Body>
</soapenv:Envelope>

Output

return FileOut

Key Type Description
status string  
format string  
file base64  
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_show_original_xmlResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:FileOut">
            <status xsi:type="xsd:string">OK</status>
            <file xsi:type="n2:base64" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iSVNPLTg4NTktMSI/Pgo8
SU5WT0lDRV9DRU5URVI+CiA8VFJBTlNQT1JUX0ZSQU1FPgogIDxURl9DT0RF
PlRGMDE8L1RGX0NPREU+CiAgPFRJTUVTVEFNUD4yMDE5MTEwODEzMjcyNzwv
VElNRVNUQU1QPgogIDxCQVRDSF9JRD43YzFiNzMxMC0wMjFhLTExZWEtYTQ1
Yi1jN2FiNzNjMjE0Mjg8L0JBVENIX0lEPgogIDxDT05URU5UX1JFQ0VJVkVS
PgogICA8UkVDRUlWRVJfUkVGPjAwM...</file>
            <format xsi:type="xsd:string">FINVOICE30</format>
         </return>
      </n1:invoice_show_original_xmlResponse>
   </env:Body>
</env:Envelope>

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

require 'soap/wsdlDriver'

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

begin
 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_original_xml(api_keys, "1c555458-fa83-402b-a1f6-4d22071020a8")
 if result.status == "OK" 
  puts result.format
  puts "Saving file to inbound.xml"
  File.open("inbound.xml","w"){ |f| f << result.file }
 end

rescue
 puts$!.message
end

list_company_actions

List all actions for given company after given timestamp. This is used to query all company’s new actions in one request.

The output lists new actions since given timestamp and that information can then be used to for example download all new incoming invoices.

/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”)
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_company_actions 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 xsi:type="xsd:string">?</timestamp>
      </sec:list_company_actions>
   </soapenv:Body>
</soapenv:Envelope>

Output

return Array of CompanyActionOutput

Key Type Description
status string  
company_id string 36 character UUID of company
incoming_invoices Array of string Array of ids for new incoming invoices
invoice_errors Array of string Array of ids for invoices with new errors
incoming_orders Array of string Array of ids for new incoming orders
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:list_company_actionsResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:CompanyActionOutput">
            <invoice_errors n2:arrayType="xsd:string[2]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>25c9c7ea-0bcd-45e6-943c-85ba940dd400</item>
               <item>32a57527-86ee-4ee8-bcc5-a6165f1edba4</item>
            </invoice_errors>
            <incoming_invoices n3:arrayType="xsd:string[2]" xsi:type="n3:Array" xmlns:n3="http://schemas.xmlsoap.org/soap/encoding/">
               <item>e4038c41-6ecd-48ce-8c2e-5e6fe71d4adc</item>
               <item>90cdaee3-ca4e-4504-97e1-f2cfe75bf4c6</item>
            </incoming_invoices>
            <incoming_orders n4:arrayType="xsd:string[0]" xsi:type="n4:Array" xmlns:n4="http://schemas.xmlsoap.org/soap/encoding/"></incoming_orders>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:list_company_actionsResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: TIMESTAMP 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

res = server.list_company_actions(api_keys, "20120501152042")
if res.status == "OK"
  puts "INCOMING INVOICES: #{res.incoming_invoices.join(',')}"
  puts "ERRORS: #{res.invoice_errors.join(',')}"
  res.invoice_errors.each do |error|
    puts "    #{error}: #{server.invoice_show(api_keys, error, false, nil).error_message}"
  end
else
  puts res.status
end

list_vendor_actions

List all actions for given vendor API key after given timestamp. This is used to batch query all partner’s user companies’ actions in one request.

The output lists new actions since given timestamp per company and that information can then be used to for example download all new incoming invoices.

/v1.1/api/list_vendor_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”)
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_actions 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 xsi:type="xsd:string">?</timestamp>
      </sec:list_vendor_actions>
   </soapenv:Body>
</soapenv:Envelope>

Output

return Array of VendorActionOutput

Key Type Description
status string  
vendor_actions VendorActionArray Array of VendorAction

vendor_actions VendorActionArray

Key Type Description
company_id string 36 character UUID of company
incoming_invoices Array of string Array of ids for new incoming invoices
invoice_errors Array of string Array of ids for invoices with new errors
incoming_orders Array of string Array of ids for new incoming orders
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_actionsResponse env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:n1="https://secure.maventa.com/">
         <return xsi:type="n1:VendorActionOutput">
            <vendor_actions n2:arrayType="n1:VendorAction[1]" xsi:type="n2:Array" xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/">
               <item>
                  <invoice_errors n2:arrayType="xsd:string[3]" xsi:type="n2:Array">
                     <item>05c9c6ea-0bcd-45e6-943c-35ba940dd600</item>
                     <item>0d374942-0d72-4dfe-9899-6c4696d6d5eb</item>
                     <item>1114acf1-0733-478d-bda7-84661cb7d338</item>
                  </invoice_errors>
                  <incoming_invoices n2:arrayType="xsd:string[3]" xsi:type="n2:Array">
                     <item>e4038c71-6ecd-43ce-8c2e-2e6fe21d4adc</item>
                     <item>90cdaee2-ca3e-4704-97e1-f5cfe45bf4c5</item>
                     <item>3985bfb4-db31-48f5-946d-bc664fff80f6</item>
                  </incoming_invoices>
                  <company_id xsi:type="xsd:string">eaeb5067-d0b1-4108-80cf-4bddf51b9e42</company_id>
                  <incoming_orders n2:arrayType="xsd:string[0]" xsi:type="n2:Array"></incoming_orders>
               </item>
            </vendor_actions>
            <status xsi:type="xsd:string">OK</status>
         </return>
      </n1:list_vendor_actionsResponse>
   </env:Body>
</env:Envelope>

Return values
Key Type Message Description
status string OK
ERROR: VENDOR API KEY DISABLED
ERROR: TIMESTAMP 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

res = server.list_vendor_actions(api_keys, "20120501152042")
if res.status == "OK"
  res.vendor_actions.each do |va|
    puts "COMPANY: #{va.company_id}"
    puts "  INCOMING INVOICES: #{va.incoming_invoices.join(',')}"
    puts "  ERRORS: #{va.invoice_errors.join(',')}"
    api_keys[:user_api_key] = "12307dc7-a0f4-4b1a-957e-22a2039a044b"
    api_keys[:company_uuid] = "1239198d-437b-4ee1-9262-bb1ca565f7b6"
    va.invoice_errors.each do |error|
      puts "    #{error}: #{server.invoice_show(api_keys, error, false, nil).error_message}"
    end
  end
else
  puts res.status
end

partner_trx_list

DEPRECATED!
Was used for getting a list of all transactions from given software between given dates.

user_create

Used for adding a new user to your company.

An activation message will be sent to the given email address. The message will also include a randomly generated password for the user. The new account cannot be used until activation is done.
Returns string which contains the new user’s API key or an ERROR message.

This method is outdated. We recommend to use user_create_e.

/v1.1/api/user_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

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 false, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network)
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 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:UserParamsInD">
            <!--You may enter the following 8 items in any order-->
            <notifications_disabled xsi:type="xsd:boolean">?</notifications_disabled>
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <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>
   </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: USER SAVED User created and activation email sent
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(api_keys, user)

user_update

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

This method is outdated. We recommend to use user_update_e.

/v1.1/api/user_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  

user_params UserParamsIn

Key Type Description
email 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)
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 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:UserParamsInD">
            <!--You may enter the following 8 items in any order-->
            <notifications_disabled xsi:type="xsd:boolean">?</notifications_disabled>
            <phone xsi:type="xsd:string">?</phone>
            <email xsi:type="xsd:string">?</email>
            <password xsi:type="xsd:string">?</password>
            <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>
   </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: USER SAVED User updated successfully
ERROR: USER COULD NOT BE SAVED 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'

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