Get started Integration Guide Services & Reach API Specification Changelogs
Search
API overview REST API Getting Started Common & authentication API Invoices API Documents API Companies & settings API Lookups API Detect API Validator API Receivables API Billing API Scanning API B2CFI API B2CNO API B2CSE API Partner API SOAP API Getting Started API Methods Overview Account Configuration API Methods Invoice Sending API Methods Invoice Receiving API Methods B2C Norway API Methods B2C Finland API Methods Other API Methods

Invoice Sending API Methods

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.

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

FIX_IMAGE_PENDING

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

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)  

list_operators

Lists currently supported roaming operators and their operator codes.

/v1.1/api/list_operators

Input

list_operators

Output

return OperatorInfoArray

Key Type Description
operator_id string Operator code
name string Operator name

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:

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

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

Return values

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

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.

/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

FIX_LINK_PENDING

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

Return values

Key Type Message
status string OK
    ERROR: TIMESTAMP START FORMAT ERROR
    ERROR: TIMESTAMP END FORMAT ERROR

invoice_show

Used for getting information about a specific outbound invoice.

/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

FIX_XML_REQUEST_EXAMPLE

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
attachment_type string
filename string
file base64

accounts InvoiceAccountParamsOutArray

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

actions InvoiceActionParamsOutArray

Key Type
timestamp string
action string

FIX_XML_RESPONSE_EXAMPLE

Return values

Key Type Message
status string OK
    ERROR: INVOICE NOT FOUND OR NO RIGHTS
    ERROR: UNKNOWN ERROR

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

FIX_IMAGE_PENDING

Output

return InvoiceStateArray (array of InvoiceState)

Key Type
status string
state int
invoice_id string

FIX_IMAGE_PENDING

Return values

Key Type Message Description
status string OK  
    ERROR: NO INVOICES FOUND  
    ERROR: UNKNOWN ERROR  

Examples

FIX_IMAGE_PENDING

sent_invoices_status

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

API method has limitations on invoice age: 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.

 
/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

FIX_IMAGE_PENDING

Output

return (InvoiceStateArray)

Key Type
invoice_id string
state string
sent_by string
error_message string

FIX_IMAGE_PENDING

Return values

Key Type Message
status string OK
    ERROR: NO INVOICE IDS GIVEN

Possible state values are

State
SENT
ACCEPTED
PAID
VIEWED
PENDING
DECLINED
DISPUTED
ERROR

Possible sent_by values are

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

invoice_reroute

Used for re-routing a existing specific outbound invoice.

/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  

Output

return (InvoiceParamsOutD)

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

Return values

Type Message
string OK: Invoice routed successfully
string ERROR: Invalid parameters
string ERROR: Invalid route
string ERROR: Invoice reroute failed: #{message}
string ERROR: Invoice not found or no rights

collection_send

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 Amili Oy!

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

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.

 
/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
status string OK
    ERROR: COLLECTION TYPE MUST BE COLLECTION OR NOTICE
    ERROR: NO INVOICES FOUND
    ERROR: SERVICE NOT ACTIVE
    ERROR: UNKNOWN ERROR
Back to top
Give feedback Contact sales Chat with support

AI Chat Support 24/7

  • • Get help via AI chat available 24/7 whenever it suits you
  • • Chat extensively uses Maventa support pages, websites, and blogs in its answers
  • • If you need assistance that the AI cannot provide, you can also ask a customer service agent to join the conversation
  • • Support requests processed Monday to Friday
Cancel Open chat

Got feedback?

Did you not find what you were looking for? Or was something explained unclearly? Or just want to share your thoughts? We are happy to hear your feedback!

Note: This form is not a way to get support, this is only for feedback for the documentation website. If you need support, please contact Maventa support.

Integration Guide Services & Reach API Specification Changelogs Integration guide Getting Started Invoice sending Consumer Invoicing Printing Email Invoicing Invoice Receiving Scanning Detect Fraud reporting Webhooks Reference implementations Maventa Connector Embeddable User Interface Peppol Network Document Exchange Invoice Response Self-billing support Invoicing formats Validation Peppol BIS 3.0 Maventa JSON (table) Maventa JSON (json schema) Companies and Settings Users Billing Services and reach Maventa services and reach e-invoicing in Belgium e-invoicing in Denmark e-invoicing in Estonia e-invoicing in Finland Mass Printing Service Amili Kassavirta Amili Perintä Ropo Perintä e-invoicing in Germany e-invoicing in Italy e-invoicing in the Netherlands e-invoicing in Norway e-invoicing in Poland e-invoicing in Sweden Api specification API overview Getting Started Common & authentication API Invoices API Documents API Companies & settings API Lookups API Detect API Validator API Receivables API Billing API Scanning API B2CFI API B2CNO API B2CSE API Partner API Getting Started API Methods Overview Account Configuration API Methods Invoice Sending API Methods Invoice Receiving API Methods B2C Norway API Methods B2C Finland API Methods Other API Methods Changelogs Product changelog Developer Changelog
Clear Send

Enter your credentials to Maventa testing environment, to authenticate and try things out with the Swagger UI. This will fetch a Bearer token using OAuth2 with the endpoint POST https://ax-stage.maventa.com/oauth2/token. The token is stored in your browser's session storage (cleared when you close the tab) and used in Swagger calls done from this documentation website. The token is valid for 1 hour.

Never use your production credentials here. This is only for testing the Maventa test environment in the Swagger UI.
All None
eui global company lookup document:receive document:send invoice:receive invoice:send company:read company:write validate receivables:assignments analysis billing:reports partner:invoice_delivery_actions partner:lookups partner:takeovers partner:lyanthe_scan_service fi_bank_message:send fi_bank_message:receive
Cancel Sign In