Skip to content
English
Log in to support portal
  • There are no suggestions because the search field is empty.

Sending e-invoices

This guide covers the automated sending of sales invoices through Maventa's e-invoicing service and REST API. Maventa acts as an invoice exchange service and distribution network, to which invoices are delivered directly from accounting software in XML format. The article introduces the service's key features, such as automatic multi-channel routing, format conversions, attachment handling and delivery status tracking via webhooks. The guide also covers the different delivery channels, such as Peppol, the operator network, email and the print service, country-specific particularities, and the principles for manually testing and sending XML data.

Maventa's sales invoice sending API and e-invoicing service enable the automated delivery of sales invoices directly from accounting software.

Sending e-invoices in Maventa

It's important to note that Maventa acts only as an invoice exchange service; invoices are not created within the service itself. Using Maventa requires accounting software capable of generating XML invoice data in one of the invoice formats Maventa accepts. Maventa then acts as an automatic distribution network that routes invoices to the correct delivery channel and takes care of country-specific and network-specific formatting requirements.

Invoices should primarily be sent directly from accounting software integrated with Maventa, so that the system generates and sends the invoice data automatically in the background.

⚠️ Note: an invoice sent to Maventa cannot be cancelled or stopped. If necessary, the sender must contact the recipient directly, create a credit note or cancellation invoice, and send the recipient a new, corrected invoice.

How does e-invoice sending work?

This guide covers the use of the REST API; SOAP API users have their own SOAP invoice sending API guide.

Maventa's REST API enables the automated processing of invoices and takes care of secure invoice routing, updates to electronic addresses, and automatic format conversions between different e-invoicing networks.

📖 Maventa documentation: Invoice sending

The Maventa API provides a single way to deliver sales invoices, credit notes and their attachments to recipients, regardless of delivery channel or country:

Multi-channel routing: invoices can be delivered as e-invoices via country-specific operator and bank networks, the international Peppol network, by email, or via the print service.

Automatic routing order: if the e-invoice address is missing or incomplete, Maventa uses automatic routing to ensure delivery. The system looks for an alternative address using the Business ID and matches the data against the recipient's name. If no e-invoice address is found, the invoice is routed by email and, failing that, to the print service based on the address details.

ℹ️ More information is available in the documentation: Recipient lookup and routing.

Automatic format conversion and validation: invoice data can be sent from accounting software in any of the XML formats Maventa supports. Maventa validates the data and converts it into the format supported by the receiving operator. You can find an up-to-date list of the XML formats Maventa supports in the documentation: Supported XML formats.

Attachments in e-invoices: attachments (e.g. PDF, XLSX, JPG) are supported up to 10 MB per file and a total limit of 150 MB. If the receiving network or operator (e.g. a bank network) doesn't support attachments, Maventa converts the data and adds a link to a hosting service from which the attachments can be downloaded.

Error situations and protection: if an invoice ends up in an error state (e.g. due to incorrect address details or incompatibility), an error notification is generated for the sender with guidance on corrective action. A protection setting can also be activated in the system to prevent sending with the same invoice number within a specified protection period (7 days).

Automatic routing and delivery methods

An invoice is primarily delivered as an e-invoice based on the address and operator details included with it. If this information is missing or incomplete, Maventa uses automatic routing to ensure delivery, in the following order:

  1. Search by Business ID: an alternative e-invoice address is searched for based on the recipient's Business ID.

  2. Data matching: if there are several search results, both the Business ID and the company name must match exactly.

  3. Delivery by email: if no e-invoice address is found, the invoice is sent by email, provided email invoicing is allowed in the company account settings, the email route is enabled, and an address has been specified for the invoice.

  4. Delivery by post: if there is no e-invoice or email address, the invoice is routed to the print service. This requires the print service to be activated and complete address details (street address, postcode, city and country).

If no delivery method is available, the invoice moves to an error state and the sender receives an automatic notification of the sending error. The notification includes instructions for resolving the situation, such as completing missing address details.

Sending stages and the integration process

At integration level, sending and tracking sales invoices is based on clear endpoints:

1. Testing and validating data (optional)

Checking invoice data before sending is optional, since Maventa automatically validates all invoices during the sending process. However, calling the validation endpoint (POST /v1/validate) helps catch any errors as early as possible, before the invoice is actually sent.

More information is available in the documentation: Validate before sending.

2. Sending the invoice to the API (POST /v1/invoices)

Sending sales invoices is enabled by default on all company accounts, as long as the company's authorisation is complete (company_state is active).

The invoice is delivered via a call to POST /v1/invoices, where the XML file (or a ZIP package containing attachments) is sent Base64-encoded in the file parameter. Any API parameters included with the request always override the corresponding values in the XML file.

The invoice identifier received when sending (invoice_id / uuid) should always be stored in your own system for tracking delivery status.

Key sending settings and parameters:

  • Recipient and routing: the recipient's e-invoice address (recipient_eia) and operator ID (recipient_operator). Specifying a particular operator alongside the e-invoice address forces delivery via that network.
    Delivery routes can also be blocked using the disabled_routes parameter.

  • Secondary delivery methods: email (recipient_email, sender_comment, email_settings) or the print service can be set as a secondary delivery channel.

  • Invoice-specific settings: print service settings, language settings (lang) and country-specific invoicing fields (e.g. fields required for B2C invoicing) can be controlled per invoice.

  • Preventing duplicate invoices: duplicate sending can be prevented either by using your own invoice-specific UUID identifier (uuid) or by activating a company-level setting (stop_duplicate_numbers), which rejects the same invoice number within 7 days.

  • Special functions: the prevent_routing setting can be used to mark an invoice as SENT without delivering it to the recipient (used, for example, for reminder and collection assignments).

💡 Detailed parameter specifications, request examples and the JSON structure are available in the documentation: Send your invoice.

3. Delivery status tracking

Real-time information about changes to an invoice's status (such as delivered, error or rejected) is obtained by registering a DOCUMENTS.INVOICE.SENT or DOCUMENTS.INVOICE.ERROR webhook.

More information is available in the documentation: Follow up and handle errors.

Preventing reuse of the same invoice number

Maventa uses the invoice number to identify an invoice. To avoid duplicate sending and confusion, the system can prevent the same invoice number from being reused within seven (7) days of the previous sending. Once this protection period has passed, the same number can, if needed, be reused, for example on a reminder invoice.

Settings and instructions for activating this feature are available in the documentation here (API): Preventing duplicate invoices, and in the support article here (user interface): General settings for sending invoices.

Operators, network connections and country-specific delivery channels

Maventa handles invoice routing and format conversion according to country-specific and operator-specific requirements. Invoices can be delivered to most domestic and international network and bank operators.

General routing order and delivery channels

For B2B and B2G invoicing, Maventa always aims to deliver the invoice via the best possible electronic route. The general routing priority consists of the following channels:

  1. Maventa's internal network: instant delivery between Maventa customers, regardless of the companies' geographic location.

  2. Country-specific operator and authority networks: regional and national e-invoicing networks (e.g. Verkkolaskufoorumi in Finland, InExchange and the Swedish operator network, Nemhandel/Sproom in Denmark).

  3. Bank network (Finland only): domestic invoice delivery in Finvoice format via the bank network.

  4. International Peppol network: cross-border and international e-invoicing for Peppol-registered recipients.

  5. Secondary delivery channels (email and print service): if no electronic e-invoice address can be found, the invoice can be routed by email or sent to the print service for physical mailing.

Country-specific particularities and statutory formats

  • Consumer invoicing (B2C): in Finland, Sweden and Norway, online banks and electronic mailboxes (e.g. Kivra, Vipps) are used, while in other countries B2C invoices are mainly delivered by email or post.

  • Denmark (Nemhandel & Peppol): the Nemhandel network is used for domestic traffic and the Peppol network for international traffic (requires a complete Endpoint ID and support for Peppol BIS 3.0).

  • Poland (KSeF): invoices are reported to the KSeF system in FA(3) format. Domestically, KSeF handles distribution; for international trade, the invoice is delivered via the Peppol network after KSeF reporting.

  • Italy (SDI): invoices are reported to the SDI system in FatturaPA format (requires Maventa's code 61M0PS7). SDI handles domestic distribution; international traffic continues via Peppol or the internal network after SDI approval.

ℹ️ More information on services and country-specific coverage is available in the documentation here: Maventa Services & Reach - Overview.

Attachments in e-invoices

Attachments (such as invoice images and supporting documents) can be delivered with e-invoices, email invoices and print service invoices. Maventa automatically adapts how attachments are delivered according to the requirements of the receiving network and delivery channel.

Including a PDF invoice image is optional, the XML invoice must always be complete on its own. If the delivery method requires an invoice image (such as the print service) and none has been attached, Maventa automatically generates a visual invoice image based on the XML data.

Delivering attachments in different formats

How attachments are included depends on the invoice format used:

  • UBL-based formats (e.g. Peppol BIS 3.0): attachments are embedded directly within the XML file. The actual invoice image is identified by the description <cbc:DocumentDescription>CommercialInvoice</cbc:DocumentDescription>

  • Other formats (e.g. Finvoice 3.0): attachments are packaged in the same ZIP file as the XML invoice. The invoice image is identified by having exactly the same file name as the XML invoice (e.g. 12345.xml and 12345.pdf)

Technical restrictions and rules

  • Size limits: the maximum size of a single attachment is 10 MB, and the maximum size of the whole delivery package is 100 MB (some receiving operators may limit attachments to 5 MB).

  • File formats: supported formats include pdf, tif, jpg, png, txt, xlsx, doc and csv. PDF files must be unprotected, without password protection.

  • File naming: only letters (A–Z), numbers (0–9), full stops (.) and underscores (_) are allowed in file names. Special characters and Scandinavian characters (å, ä, ö) are not allowed, and the maximum name length is 50 characters.

Delivery across different distribution channels

  • Print service: supports attachments and uses the unprotected PDF image provided, or an automatically generated invoice template.

  • Bank network and operators without attachment support: if the receiving network doesn't support attachments, Maventa replaces them with a link to a hosting service, from which the recipient can download the attachments.

Invoice image and personalisation

Invoicing primarily uses the PDF invoice image produced by the sending accounting software. If needed, the print service can use your own PDF image, or Maventa's generated invoice template can be personalised with your company's logo.

Detailed instructions for setting up your own invoice image and logo are available in the documentation here (API): Configure account settings, and in a separate support article here (user interface): Invoice image settings.

Sending e-invoices abroad and across different networks

Maventa supports several international and regional distribution networks and takes care of format conversions automatically.

Peppol network

The Peppol network is widely used for e-invoice delivery across Europe and internationally. All invoices sent via Peppol are delivered in PeppolBIS format. When an invoice is sent from Maventa to the Peppol network, it is automatically converted to PeppolBIS format, regardless of the original invoice format.

Local and country-specific networks

Maventa supports regional operator and bank networks, as well as country-specific invoice formats (such as Finvoice, TEAPPS, Svefaktura and OIOUBL). Maventa always converts outgoing invoices into the format required by the receiving operator, for example, you can send Finvoice data to a Swedish recipient, and Maventa will take care of converting it into the format supported by the recipient's operator.

Maventa's internal network

Sending e-invoices to companies abroad is especially quick and easy when both the sender and the recipient are Maventa customers. In this case, the invoice travels within Maventa's internal network, regardless of geographic location.

Sending international e-invoices on the Maventa network

When both the sender and the recipient use Maventa as their invoicing operator, the invoice is always routed using Maventa's internal network settings.

Routing instructions and technical details:

  1. Confirm the recipient is a Maventa customer: check that the recipient is a Maventa customer.

  2. Use the correct operator ID: always use Maventa's operator ID, regardless of the companies' geographic location.

  3. Enter the details in your accounting software: enter the following routing details on your customer record or in the invoice routing details in your accounting software:

Field Value
Operator Maventa
Operator ID (intermediary ID) 003721291126
E-invoice address The recipient's unique address (found via address search)

ℹ️ Maventa recommends confirming the recipient's details directly with the recipient, via Maventa's search tool, or through public registers. If the company can't be found on the Maventa network, find out the company's Peppol address or the intermediary ID of their local operator.

Manually sending and testing XML invoice data in the Maventa user interface

If you want to send or test XML-format invoice data directly from the Maventa user interface, you need ADMIN-level access rights.

  • Sending an invoice: a ready-made XML invoice file can be uploaded and sent from the user interface. This function doesn't support attachments (e.g. PDF). The status of a sent invoice can be tracked on the Sent invoices tab.

  • Testing data: the technical and content compatibility of an XML file can be tested in advance, without sending or saving the invoice in the system. Testing is free of charge and gives immediate feedback on any structural errors.

Detailed step-by-step instructions for manually sending and testing invoices are available in a separate support article: Invoice tools.