Home Integration guide Invoice sending

Invoice XML & content

XML in e-invoicing

XML presents invoice data in a structured way. Maventa e-invoicing supports wide variety of XML based standard invoice formats and automatically converts the invoices from one format to another when needed. See the supported formats and xml examples below.

In general, we recommend using the Peppol BIS 3.0 format for invoice exchange. The format is widely supported and is well suitable for sending and receiving invoices across countries.

If you are planning to operate in the Finnish market only and have a need to send consumer invoices, we recommend Finvoice 3.0 or Teapps XML 3.0. Both of the formats can handle both B2B and B2C invoicing. All three formats fully support the European EN16931 (SFS-EN 16931-1:2017) invoicing standard. Please read more about the standard from here.

Supported XML formats

See all example XML files from here.
Please notice that Finvoice examples have two different files, one uses SOAP envelope and one uses MessageTransmissionDetails. Finvoice 2.0 has also version 2.01.

Supported attachment filetypes

  • .tif
  • .tiff
  • .jpg
  • .jpeg
  • .png
  • .gif
  • .txt
  • .xml
  • .xls
  • .xsl
  • .xlsx
  • .html
  • .htm
  • .pdf
  • .aix
  • .doc
  • .docx
  • .ods

These are the attachment types supported by Maventa SOAP and REST API.

Note that there might be also format and operator specific limitations. Remember check limitations from format’s documentation, e.g. PEPPOL support only these MimeCodes.

Invoice image and attachment handling

When sending e-invoices, a PDF version of the invoice is always sent, except in Peppol. It is expected that ERP generates and sends the invoice image in PDF format along with the XML. In that way the user can have better overview of the PDF view of the invoice.

The invoice image and attachments can be embedded within XML or sent within a zip with the XML itself, depending on the invoice format that is used.
If the invoice image is sent as an attachment within a zip file, the invoice XML and invoice image in the zip needs to be named the same way for Maventa to recognize the attachment as the invoice image. For example 12345.xml and 12345.pdf. Name of the other attachments doesn’t need to match with the XML file.

Attachment (image or other) size is maximum 10 Mb per file. Server limit for the whole package is 150 Mb. It is not recommended to use big attachments. Smaller the better.

In case PDF invoice image is not provided, a general invoice image will be created by Maventa based on the original XML invoice, using the Maventa PDF templates. The purpose of PDF templates is to provide bare minimum substitution of missing PDF invoice image, in order to avoid stopping the invoice sending process.

Maventa PDF templates include the core invoice content. This substitution PDF invoice image might not satisfy everyone’s needs, therefore it is recommended that the ERP provide own pdf invoice image along with the XML, especially when special content contrsuction or specific design of invoice image is needed.

In Maventa there are two different general templates in use, depending on market area / country where the invoice is sent to. Belowe you can find the examples.

The design of the general templates may change at time, however keeping all the existing document data in it.

PDF examples

Example XML files have tag names as values to make make it clear where they will be visualised in the PDFs. Note that if all the address details are given the PDF will easily expand to two or more pages.

Finvoice

The following example PDF is generated when invoice is sent in Finnish market, and the XML is in Finvoice 3.0 format.

Download as pdf

The following example PDF is generated when invoice is sent in other markets, and the XML is in Finvoice 3.0 format.

Download as pdf

Finnish market example has <SpecificationDetails> -element given (<SpecificationFreeText> tags). That element has different font and styling. The font is Courier (all the characters are equally wide). The purpose of using this font type in this case is to keep the formatted text as it is given in the XML.

Example usage of <SpecificationDetails> -element and how it would look like in the PDF

<SpecificationDetails>
  <SpecificationFreeText>LASKUN VAPAAMUOTOISET ERITTELYTIEDOT:</SpecificationFreeText>
  <SpecificationFreeText>Sarake-1              Sarake-2                                                             Sarake-3</SpecificationFreeText>
  <SpecificationFreeText>---------------------------------------------------------------------------------------------------</SpecificationFreeText>
  <SpecificationFreeText>1.sarakkeen tieto     2.sarakkeen tieto                                                       10,00</SpecificationFreeText>
  <SpecificationFreeText>Toinen rivi           Toinen rivi                                                          1 000,00</SpecificationFreeText>
  <SpecificationFreeText>Kolmas rivi           3/2                                                                      1,00</SpecificationFreeText>
  <SpecificationFreeText>Muotoituja tietoja voidaan käyttää mm.tarkemman erittelyn esittämiseen:</SpecificationFreeText>
</SpecificationDetails>

SpecificationDetails example

Teapps

The following example PDF is generated when invoice is sent in Finnish market, and the XML is in Teapps 3.0 format.

Download as pdf

The following example PDF is generated when invoice is sent in other markets, and the XML is in Teapps 3.0 format.

Download as pdf

Invoice validation & Autovalidator

Before invoices are sent there are certain validations made to ensure that the invoice XML contains the necessary data and is set up correctly. The validation requirements depend on where the invoice is sent to. Some of the routes such as Peppol network, require validation on structure and the invoice content level, for example that the invoice line amounts match the total amounts given on the invoice. If the route where invoice is going to requires validation, Maventa does this before distributing the invoice and returns an error if the invoice is not valid.

See more information of the validation below.

Against what are invoices validated to

Minimum invoice information requirements

XML schematron validation

  • Invoice structure and content validation
  • Used for Peppol BIS or EN-16391 tagged Finvoice 3.0 / TeApps 3.0
    • If the outgoing format is Peppol BIS (always EN-16931 content) the content is validated with Peppol provided schematron.
    • If the outgoing invoice is Finvoice or TeApps and it is marked as EN-16931 compatible it is validated by the schematron used commonly by the finnish operator network (Verkkolasku Foorumi).
  • If the invoice is routed to Print / eMail / internal delivery, the schematron result is ignored

Bank network validation

  • Bank network specific validations if invoice is sent to netbank (e.g. due date, Finvoice EPIDetails element in B2C invoices)

Note also that in all cases when Maventa converts files, the converted files are made to be structurally correct, i.e. they follow XML schema (XSD) of the target conversion format.

How do I know which validations need to be made?

Maventa does automatically the required validations and returns an error if the invoice is not valid for the route it is sent to.

First validation on minimum invoice information requirements is done before invoice appears on the outgoing invoice listing (UI / API calls). If the invoice doesn’t meet the requirements it will be rejected on the API.

The other validations schematron and bank network will be done if needed once the invoice is routed and prepared for sending. The status of the invoice will indicate whether it has been sent (1) or still in the sending process (0) or it has failed (99).

How can I make sure that the invoice doesn’t fail on validation?

Make sure that the material you are sending is following the specifications of the format you are using. This ensures also that conversion of the XML will work in a good way. Maventa handles conversions between the supported XML formats. However, note that there may be some limitations if the format version you are using is very old, i.e. there can be some elements that cannot be properly converted. We recommend to use the latest versions of the formats to ensure the best compatibility on conversions.

Links to some commonly used format documentation

Finvoice & Teapps phase-in error message

Validation rules require changes time to time. There is an error message which reveals the upcoming changes.

The phase-in error message is due to phase-in feedback having revealed an error in e-invoicing data that must be corrected. If not corrected, the error will cause an invoice to be rejected in the next version of rules. This provides a way for billers and developers to correct the discovered error now, before the launch of the next ruleset.

Can I validate/test my material before sending and how?

There are different validation tools that can be used for testing the material you are sending.

Maventa offers possibility to validate documents over API with the help of AutoValidator tool.

The tool supports also schematron validation of Peppol BIS 3.0, TeApps 3.0 and Finvoice 3.0.