Welcome to Maventa integration guide!
Here you will find information how to connect your ERP to Maventa e-invoicing and document exchange service. The guide contains overview of our APIs, information of the API methods available, what method to use in what situation as well as tips and useful routines for integrating.
Let’s go!
Here’s how you can get set up to start building and testing your integration.
If you are looking for more guidance on what type of integration to make we recommend checking our Overview section where you can learn more about the options Maventa offers.
To start using Maventa APIs, open a test account from here. The account will be created as type Company account.
In Maventa there are two type of accounts; Company accounts and Partner accounts. Company account is the default account type. Partner accounts are used by the integrating partners (ERPs and such with multiple customers) and have an own identifier (vendor_api_key) that is used to link actions to the partner.
When you have registered a company account in testing, contact Integration Care (integrations@maventa.com) or your integration contact point to convert your account into a partner account and create a vendor_api_key for you.
After having the necessary API keys you can start building the integration. Follow feature specific guides for detailed instructions on sending, receiving, account & settings configuration and service activation.
When integration is created and tested in testing environment, you will receive the keys to move to production. Follow the same process as in testing.
vendor_api_key
.To use the API you need three different API keys, which are used in almost every request towards Maventa API:
User_api_key and the company_uuid are returned when you create new users and companies. The vendor_api_key is given to you by your integration contact point from Maventa.
When using the API keys, make sure they are written as is and ensure there are no extra blanks before or after the key to avoid errors.
The purpose of the vendor_api_key is to identify the partner the customer and their transactions “belong” into. This is necessary for correct billing, reporting and support handling. It is very important that Partner and ERP integrations always use their own vendor_api_key in all API calls. Actions performed without supplying vendor_api_key will not be related to any vendor/ partner. All actions submitted without specifying vendor_api_key will be billed directly to related customer, based on general price list.
Usually, if a partner is developing multiple different ERP systems and wants to get their customer transactions sorted by ERP, a partner wants to have a different vendor_api_key for each ERP. In general, this key is then ”hard-coded” into the software or at least hidden so that a user cannot change it.
Note also that the testing and production endpoints of the API use different API keys. No API keys from testing will work on production and vice versa. Errors like ”USER NOT FOUND” mean that the user_api_key is wrong for that environment. Please, make sure you are using the correct API endpoint for your API key.
In SOAP API, authentication is performed by providing all keys on each request.
In REST API, authentication is performed by using oauth2 standard tokens. See more at REST API Authentication.
In testing server, electronic and print sends outside Maventa are simulated, but internal and e-mail sends work as in production environment. Since emails are actually sent out, make sure to use e-mail addresses that you own when conducting testing to avoid any confusion (e.g. do not use something like test@test.com since that domain really exists meaning that the e-mail address might also exist)
It is also good to note, that the testing environment is also used for internal testing, which means that it can differ from the production environment from time to time. The database of the testing server might be unavailable at times, and the server may be emptied without notice. Also for data privacy do not use real/production data in the testing environment.
APIs to use: SOAP API or REST API
Invoices are sent by providing an XML file and specifying other necessary data for send as parameters on the api call.
To deliver an e-invoice Maventa uses the electronic invoicing address and the operator code of the recipient. If only recipient’s e-invoice address or organization number is given Maventa does a lookup to find the rest of the information.
The recipient information can be given as
MessageTransmissionDetails
-element.If both are used, the information in the metadata overrides information in the XML.
Please note that specifying the operator code affects routing so it should only be given when the sender knows this information.
The default order to route an invoice is
E-invoice is tried first, and email and print are used as fallbacks.
If only recipient’s e-invoice address or organization number are given, and no valid electronic route can be found the fallback routes are automatically tried.
The fallback routes are NOT used if invoice has been sent to specific electronic route. The specific route means that in sending both electronic invoice address (EIA) and operator information are given (e.g. 0192:123456789, PEPPOL). In this case invoice is sent directly to specific route and no other routes are searched or tried. The system considers that the invoice is meant to be send as an e-invoice to that specific address and the sender would like to know if that e-invoice route fails.
Disabling routes specifically is also possible in the sending API call.
To send the invoice, use API method:
Which creates a new invoice from an existing XML invoice or a ZIP file with invoice XML file and attachments.
After creation the invoice is automatically sent to Maventa that does the the necessary conversions and validations before sending the invoice forward.
In addition to sending the invoice, the sending methods can be used to give extra information related to sending. You can give a specific electronic address where to send the invoice or choose which routes you want or don’t want to use to send the invoice.
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.
These are the attachment types supported by SOAP and REST API. There might be also format and operator specific limitations. Remember check limitations from format’s documentation, e.g. PEPPOL support only these MimeCodes.
For monitoring sent invoices we recommend to register to callback notifications. This way the sender can get the status changes of invoices immediately and take further actions if needed.
We also enable polling for the invoice status using the API methods:
direction=SENT
or GET /v1/invoices/{id}More information of invoices in error state can be seen by using API method:
Depending on the cause of the error invoices can be rerouted or a new invoice needs to be sent.
Validation errors Invoice data is structurally not correct or invoice content is not valid, for example due date for the invoice is in the past. To fix the issue create and send a new invoice with necessary corrections.
Routing errors The recipient is not found or the route is not in use. To fix the issue reroute the invoice to another route, or activate needed service and resend.
When sending e-invoices, a PDF version of the invoice is always sent and if no such PDF exists, it will be created using Maventa PDF templates. It is recommended that ERP generates and sends the invoice image in PDF format with the XML, in that way the user knows which template will be used for PDF viewing of the invoice.
The image can be sent as embedded attachment within xml or within a zip file 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 file within the zip need to be named the same way for Maventa to recognize the attachment as the invoice image. For example 12345.xml and 12345.pdf.
PDF is filled with corresponding Finvoice tags to make it clear which tag is visualised where.
<?xml version="1.0" encoding="ISO-8859-15"?>
<?xml-stylesheet type="text/xsl" href="Finvoice.xsl"?>
<Finvoice Version="3.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SellerPartyDetails>
<SellerPartyIdentifier>1234567-8</SellerPartyIdentifier>
<SellerOrganisationName>SellerOrganisationName</SellerOrganisationName>
<SellerOrganisationTaxCode>FI12345678</SellerOrganisationTaxCode>
<SellerOrganisationTaxCodeUrlText>http://ec.europa.eu/taxation_customs/vies/vieshome.do</SellerOrganisationTaxCodeUrlText>
<SellerPostalAddressDetails>
<SellerStreetName>SellerStreetName</SellerStreetName>
<SellerTownName>SellerTownName</SellerTownName>
<SellerPostCodeIdentifier>SellerPostCodeIdentifier</SellerPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>CountryName</CountryName>
<SellerPostOfficeBoxIdentifier>SellerPostOfficeBoxIdentifier</SellerPostOfficeBoxIdentifier>
</SellerPostalAddressDetails>
</SellerPartyDetails>
<SellerCommunicationDetails>
<SellerPhoneNumberIdentifier>SellerPhoneNumberIdentifier</SellerPhoneNumberIdentifier>
<SellerEmailaddressIdentifier>SellerEmailaddressIdentifier</SellerEmailaddressIdentifier>
</SellerCommunicationDetails>
<SellerInformationDetails>
<SellerHomeTownName>SellerHomeTownName</SellerHomeTownName>
<SellerPhoneNumber>SellerPhoneNumber</SellerPhoneNumber>
<SellerFaxNumber>SellerFaxNumber</SellerFaxNumber>
<SellerWebaddressIdentifier>SellerWebaddressIdentifier</SellerWebaddressIdentifier>
<!-- If bank details given here they override details given in EpiPartyDetails on PDF creation -->
<!--SellerAccountDetails>
<SellerAccountID IdentificationSchemeName="IBAN">SellerAccountID</SellerAccountID>
<SellerBic IdentificationSchemeName="BIC">SellerBic</SellerBic>
<SellerAccountName>SellerAccountName</SellerAccountName>
</SellerAccountDetails-->
</SellerInformationDetails>
<InvoiceRecipientPartyDetails>
<InvoiceRecipientPartyIdentifier>7654321-8</InvoiceRecipientPartyIdentifier>
<InvoiceRecipientOrganisationName>InvoiceRecipientOrganisationName</InvoiceRecipientOrganisationName>
<InvoiceRecipientPostalAddressDetails>
<InvoiceRecipientStreetName>InvoiceRecipientStreetName</InvoiceRecipientStreetName>
<InvoiceRecipientStreetName>InvoiceRecipientStreetName2</InvoiceRecipientStreetName>
<InvoiceRecipientTownName>InvoiceRecipientTownName</InvoiceRecipientTownName>
<InvoiceRecipientPostCodeIdentifier>InvoiceRecipientPostCodeIdentifier</InvoiceRecipientPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>CountryName</CountryName>
</InvoiceRecipientPostalAddressDetails>
</InvoiceRecipientPartyDetails>
<InvoiceRecipientLanguageCode>FI</InvoiceRecipientLanguageCode>
<BuyerPartyDetails>
<BuyerPartyIdentifier>7894561-2</BuyerPartyIdentifier>
<BuyerOrganisationName>BuyerOrganisationName</BuyerOrganisationName>
<BuyerOrganisationTaxCode>FI78945612</BuyerOrganisationTaxCode>
<BuyerPostalAddressDetails>
<BuyerStreetName>BuyerStreetName</BuyerStreetName>
<BuyerStreetName>BuyerStreetName2</BuyerStreetName>
<BuyerTownName>BuyerTownName</BuyerTownName>
<BuyerPostCodeIdentifier>BuyerPostCodeIdentifier</BuyerPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>CountryName</CountryName>
</BuyerPostalAddressDetails>
</BuyerPartyDetails>
<BuyerContactPersonName>BuyerContactPersonName</BuyerContactPersonName>
<DeliveryPartyDetails>
<DeliveryOrganisationName>DeliveryOrganisationName</DeliveryOrganisationName>
<DeliveryPostalAddressDetails>
<DeliveryStreetName>DeliveryStreetName</DeliveryStreetName>
<DeliveryTownName>DeliveryTownName</DeliveryTownName>
<DeliveryPostCodeIdentifier>DeliveryPostCodeIdentifier</DeliveryPostCodeIdentifier>
</DeliveryPostalAddressDetails>
</DeliveryPartyDetails>
<DeliveryDetails>
<DeliveryDate Format="CCYYMMDD">20200501</DeliveryDate>
<DeliveryTermsText>DeliveryTermsText</DeliveryTermsText>
<DeliveryNoteIdentifier>DeliveryNoteIdentifier</DeliveryNoteIdentifier>
</DeliveryDetails>
<InvoiceDetails>
<InvoiceTypeCode CodeListAgencyIdentifier="SPY">INV01</InvoiceTypeCode>
<InvoiceTypeCodeUN>380</InvoiceTypeCodeUN>
<InvoiceTypeText>LASKU</InvoiceTypeText>
<OriginCode>Original</OriginCode>
<InvoiceNumber>InvoiceNumber</InvoiceNumber>
<InvoiceDate Format="CCYYMMDD">20200101</InvoiceDate>
<OriginalInvoiceNumber>Orig.Inv.Number</OriginalInvoiceNumber>
<InvoicingPeriodStartDate Format="CCYYMMDD">20200101</InvoicingPeriodStartDate>
<InvoicingPeriodEndDate Format="CCYYMMDD">20201231</InvoicingPeriodEndDate>
<SellerReferenceIdentifier>SellerReferenceIdentifier</SellerReferenceIdentifier>
<SellersBuyerIdentifier>SellersBuyerIdentifier</SellersBuyerIdentifier>
<OrderIdentifier>OrderIdentifier</OrderIdentifier>
<AgreementIdentifier>AgreementIdentifier</AgreementIdentifier>
<BuyerReferenceIdentifier>BuyerReferenceIdentifier</BuyerReferenceIdentifier>
<RowsTotalVatExcludedAmount AmountCurrencyIdentifier="EUR">100,00</RowsTotalVatExcludedAmount>
<InvoiceTotalVatExcludedAmount AmountCurrencyIdentifier="EUR">100,00</InvoiceTotalVatExcludedAmount>
<InvoiceTotalVatAmount AmountCurrencyIdentifier="EUR">24,00</InvoiceTotalVatAmount>
<InvoiceTotalVatIncludedAmount AmountCurrencyIdentifier="EUR">124,00</InvoiceTotalVatIncludedAmount>
<VatSpecificationDetails>
<VatBaseAmount AmountCurrencyIdentifier="EUR">100,00</VatBaseAmount>
<VatRatePercent>24</VatRatePercent>
<VatCode>S</VatCode>
<VatRateAmount AmountCurrencyIdentifier="EUR">24</VatRateAmount>
</VatSpecificationDetails>
<InvoiceFreeText>InvoiceFreeText</InvoiceFreeText>
<PaymentTermsDetails>
<PaymentTermsFreeText>PaymentTermsFreeText</PaymentTermsFreeText>
<InvoiceDueDate Format="CCYYMMDD">20201201</InvoiceDueDate>
<PaymentOverDueFineDetails>
<PaymentOverDueFinePercent>14</PaymentOverDueFinePercent>
</PaymentOverDueFineDetails>
</PaymentTermsDetails>
</InvoiceDetails>
<FactoringAgreementDetails>
<FactoringAgreementIdentifier>FactoringAgreementIdentifier</FactoringAgreementIdentifier>
<EndorsementClauseCode>F</EndorsementClauseCode>
<FactoringFreeText>FactoringFreeText</FactoringFreeText>
<FactoringFreeText>FactoringFreeText</FactoringFreeText>
<FactoringPartyIdentifier>3216549-8</FactoringPartyIdentifier>
<FactoringPartyName>FactoringPartyName</FactoringPartyName>
<FactoringPartyPostalAddressDetails>
<FactoringPartyStreetName>FactoringPartyStreetName</FactoringPartyStreetName>
<FactoringPartyTownName>FactoringPartyTownName</FactoringPartyTownName>
<FactoringPartyPostCodeIdentifier>FactoringPartyPostCodeIdentifier</FactoringPartyPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>Suomi</CountryName>
</FactoringPartyPostalAddressDetails>
</FactoringAgreementDetails>
<VirtualBankBarcode>423571690200529290000246000000000000329041884403200320</VirtualBankBarcode>
<InvoiceRow>
<ArticleIdentifier>ArticleIdentifier</ArticleIdentifier>
<ArticleName>ArticleName</ArticleName>
<DeliveredQuantity QuantityUnitCode="kpl">1,00</DeliveredQuantity>
<OrderedQuantity QuantityUnitCode="kpl">1,00</OrderedQuantity>
<InvoicedQuantity QuantityUnitCode="kpl">1,00</InvoicedQuantity>
<UnitPriceAmount UnitPriceUnitCode="kpl" AmountCurrencyIdentifier="EUR">200,00</UnitPriceAmount>
<UnitPriceNetAmount AmountCurrencyIdentifier="EUR">100,00</UnitPriceNetAmount>
<RowIdentifier>RowIdentifier</RowIdentifier>
<RowOrderPositionIdentifier>1</RowOrderPositionIdentifier>
<RowPositionIdentifier>1</RowPositionIdentifier>
<RowDeliveryDate Format="CCYYMMDD">20200515</RowDeliveryDate>
<RowBuyerReferenceIdentifier>RowBuyerReferenceIdentifier</RowBuyerReferenceIdentifier>
<RowFreeText>RowFreeText</RowFreeText>
<RowDiscountPercent>50,0</RowDiscountPercent>
<RowDiscountAmount AmountCurrencyIdentifier="EUR">100,00</RowDiscountAmount>
<RowDiscountTypeText>RowDiscountTypeText</RowDiscountTypeText>
<RowVatRatePercent>24,0</RowVatRatePercent>
<RowVatCode>S</RowVatCode>
<RowVatAmount AmountCurrencyIdentifier="EUR">24</RowVatAmount>
<RowVatExcludedAmount AmountCurrencyIdentifier="EUR">100,00</RowVatExcludedAmount>
<RowAmount AmountCurrencyIdentifier="EUR">124,00</RowAmount>
</InvoiceRow>
<SpecificationDetails>
<SpecificationFreeText>SpecificationFreeText</SpecificationFreeText>
</SpecificationDetails>
<EpiDetails>
<EpiIdentificationDetails>
<EpiDate Format="CCYYMMDD">20200101</EpiDate>
<EpiReference>EpiReference</EpiReference>
</EpiIdentificationDetails>
<EpiPartyDetails>
<EpiBfiPartyDetails>
<EpiBfiIdentifier IdentificationSchemeName="BIC">EpiBfiID.</EpiBfiIdentifier>
<EpiBfiName>EpiBfiName</EpiBfiName>
</EpiBfiPartyDetails>
<EpiBeneficiaryPartyDetails>
<EpiNameAddressDetails>EpiNameAddressDetails</EpiNameAddressDetails>
<EpiBei>1234567-8</EpiBei>
<EpiAccountID IdentificationSchemeName="IBAN">EpiAccountID</EpiAccountID>
</EpiBeneficiaryPartyDetails>
</EpiPartyDetails>
<EpiPaymentInstructionDetails>
<EpiPaymentInstructionId/>
<!-- Used to identify invoice as B2C invoice -->
<EpiRemittanceInfoIdentifier IdentificationSchemeName="ISO">0123456789</EpiRemittanceInfoIdentifier>
<EpiInstructedAmount AmountCurrencyIdentifier="EUR">122,00</EpiInstructedAmount>
<EpiCharge ChargeOption="SHA">SHA</EpiCharge>
<EpiDateOptionDate Format="CCYYMMDD">20201201</EpiDateOptionDate>
</EpiPaymentInstructionDetails>
</EpiDetails>
</Finvoice>
If you want to find out if a company can receive electronic invoices through Maventa or through external operators before the send, you can use API method:
to find out recipient’s invoicing information. The search can be done using indentifiers such as company name, company organization number or business ID, VAT code or e-invoice address (e.g. EDI, OVT, EAN, GLN)
Some of the routes invoices are sent to, such as PEPPOL or net bank require validation of the invoice data. The purpose of the validation is to ensure data is structurally correct and the content is in alignment within an invoice, for example the invoice total amounts match the line amounts. 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. If you are interested of validation on your system side, contact your integration contact point or Maventa to discuss the tools we have to offer.
When invoice recipient details (InvoiceRecipientPartyDetails
) are provided, we expect it to be the entity who should receive the invoice (via e-invoice, email or print).
There are requirements in Maventa side what details the entity should have in order to route it successfully:
InvoiceRecipientPartyDetails
) are sometimes incomplete.BuyerPartyDetails
) in Finvoice 1.x/2.x/3.0 versions if possible.Invoice recipient details are complemented with buyer details when:
NAME
is not the same as Name
)SOAP/To identifier
or MesasgeTransmissionDetails/MessageReceiver/ToIdentifier
does not exist or is equal with valueInvoice recipient details are not complemented with buyer details when:
Example:
<?xml version="1.0" encoding="ISO-8859-15"?>
<Finvoice Version="1.3">
<InvoiceRecipientCommunicationDetails>
<InvoiceRecipientPhoneNumberIdentifier>123456</InvoiceRecipientPhoneNumberIdentifier>
<InvoiceRecipientEmailaddressIdentifier>email@email.com</InvoiceRecipientEmailaddressIdentifier>
</InvoiceRecipientCommunicationDetails>
<BuyerPartyDetails>
<BuyerPartyIdentifier>3333333-3</BuyerPartyIdentifier>
<BuyerOrganisationName>Name1</BuyerOrganisationName>
<BuyerOrganisationName>Name2</BuyerOrganisationName>
<BuyerOrganisationTaxCode>FI33333333</BuyerOrganisationTaxCode>
<BuyerPostalAddressDetails>
<BuyerStreetName>StreetName</BuyerStreetName>
<BuyerTownName>TownName</BuyerTownName>
<BuyerPostCodeIdentifier>11111</BuyerPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>Finland</CountryName>
</BuyerPostalAddressDetails>
</BuyerPartyDetails>
<BuyerCommunicationDetails>
<BuyerPhoneNumberIdentifier>123456</BuyerPhoneNumberIdentifier>
<BuyerEmailaddressIdentifier>email@email.com</BuyerEmailaddressIdentifier>
</BuyerCommunicationDetails>
<InvoiceDetails>
<InvoiceTypeCode>INV01</InvoiceTypeCode>
</InvoiceDetails>
</Finvoice>
Output:
<?xml version="1.0" encoding="ISO-8859-15"?>
<Finvoice Version="1.3">
<InvoiceRecipientPartyDetails>
<InvoiceRecipientPartyIdentifier>3333333-3</InvoiceRecipientPartyIdentifier>
<InvoiceRecipientOrganisationName>Name1</InvoiceRecipientOrganisationName>
<InvoiceRecipientOrganisationName>Name2</InvoiceRecipientOrganisationName>
<InvoiceRecipientOrganisationTaxCode>FI33333333</InvoiceRecipientOrganisationTaxCode>
<InvoiceRecipientPostalAddressDetails>
<InvoiceRecipientStreetName>StreetName</InvoiceRecipientStreetName>
<InvoiceRecipientTownName>TownName</InvoiceRecipientTownName>
<InvoiceRecipientPostCodeIdentifier>11111</InvoiceRecipientPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>Finland</CountryName>
</BuyerPostalAddressDetails>
</InvoiceRecipientPartyDetails>
<InvoiceRecipientCommunicationDetails>
<InvoiceRecipientPhoneNumberIdentifier>123456</InvoiceRecipientPhoneNumberIdentifier>
<InvoiceRecipientEmailaddressIdentifier>email@email.com</InvoiceRecipientEmailaddressIdentifier>
</InvoiceRecipientCommunicationDetails>
<BuyerPartyDetails>
<BuyerPartyIdentifier>3333333-3</BuyerPartyIdentifier>
<BuyerOrganisationName>Name1</BuyerOrganisationName>
<BuyerOrganisationName>Name2</BuyerOrganisationName>
<BuyerOrganisationTaxCode>FI33333333</BuyerOrganisationTaxCode>
<BuyerPostalAddressDetails>
<BuyerStreetName>StreetName</BuyerStreetName>
<BuyerTownName>TownName</BuyerTownName>
<BuyerPostCodeIdentifier>11111</BuyerPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>Finland</CountryName>
</BuyerPostalAddressDetails>
</BuyerPartyDetails>
<BuyerCommunicationDetails>
<BuyerPhoneNumberIdentifier>123456</BuyerPhoneNumberIdentifier>
<BuyerEmailaddressIdentifier>email@email.com</BuyerEmailaddressIdentifier>
</BuyerCommunicationDetails>
<InvoiceDetails>
<InvoiceTypeCode>INV01</InvoiceTypeCode>
</InvoiceDetails>
</Finvoice>
The following states can be returned as invoice state values.
State code | Reason | Description |
---|---|---|
0 | PENDING | Awaiting delivery (scheduled transmission) |
1 | SENT | Invoice sent |
2 | DECLINED | Rejected/declined by the recipient (Only e-mail and internal Maventa)* |
3 | ACCEPTED | Accepted/approved by the recipient (Only e-mail and internal Maventa)* |
6 | PAID | Invoice marked as paid (Internal Maventa only)* |
7 | VIEWED | Invoice link opened by the recipient (Only e-mail and internal Maventa)* |
92 | DISPUTED | Disputed by the recipient (Only internal Maventa)* |
99 | ERROR | Send error occurred |
* = Internal and should be used for information only.
The main invoice states used are 0=PENDING, 1=SENT and 99=ERROR. Additionally invoice can get other states if it is sent from Maventa user to another. Note that these states are informational only! For example state “DISPUTED” does not mean legal disputing of invoice.
When invoice is sent it first gets the value “PENDING”, after that the invoice will go to either state “SENT” or state “ERROR”.
For internal recipients (recipients also using Maventa service) invoice can after sent state get further status based on the actions made on the invoice (“DECLINED”, “ACCEPTED”, “VIEWED” “PAID”, “DISPUTED”). If the invoice is sent to external operator or network it is possible that the state of the sent invoice changes to “ERROR” if operator or network returns an error of not being able to deliver the invoice.
Invoice state functionality is similar to SOAP API, but with REST only three different states are returned:
APIs to use: SOAP API or REST API
Invoices are received by listing new incoming invoices in Maventa and then downloading the invoice and attachments into your financial system.
Invoice listing gives information of the new incoming invoices in Maventa.
First step of invoice receiving is to list the incoming invoice id’s and save them locally.
Both of the methods can be used to list the new incoming invoices. Invoice_list_ids is usually used by on-premise systems where as SaaS systems use list_vendor_inbound_invoices.
direction=RECEIVED
, received_at_start
, and received_at_end
to get list of invoices available for download. It is possible to use the param fields
to limit the amount of data returned on the response.Incoming invoices are downloaded with
API to use: SOAP API
All companies using Maventa have an own account that is registered with unique business ID and company details. After registration company settings can be configured, including activation of different services and networks. Before account is ready to be used fully, it needs to be verified by partner or the end user company.
Company accounts will always be linked to at least one user. Users are created based on an email address. The user can be a real “human” user or a technical/API user only. This gives possibility to create the user set up in a very flexible way, taking into account the integration needs.
In company and user management note that
You can use either API or user interface to open and manage a company account. However, the user interface requires manual work so if the integration will have multiple companies or a complex set-up, API is recommended.
To create a new company, register a company account using API method
Note! In situations where a new user is created, method returns unique company_uuid and user_api_key. If method is called with an existing user, only company_uuid is returned.
When company account has been created, it can be configured by updating company settings, adding new users and activating services. Some services for receiving can only be activated after the verification step.
API methods:
You can update the receivig setting (enable/disable) also using company_invoice_receiving. Note,that invoice receiving needs to be enabled in order to register company account to Peppol network or to use additional services such as Scanning.
To prevent possible misuse of the service, company account needs to be verified before it can be used for sending and receiving. The requirements to use the account are that customer company has been strongly authenticated and has signed Terms of Service
The account verification takes place with Visma Sign electronic signature service. A person who has rights to represent company related to electronic invoicing authenticates strongly with bank credentials or mobileID and signs a document where they confirm that account can be taken into use for the company.
If the customer has already signed the Terms of Service and has been strongly authenticated on the integrator side, it is possible to agree with Maventa about verification without the Visma Sign step.
API methods
Note!
Strong authentication includes an element that enables the service provider to verify the identity of the user with certainty. It can be implemented e.g. with login codes of online banks, mobile ID, bankID, an electronic identity card or passport.
If the same signee has rights to represent more than one company it is possible to use one signing for multiple companies. One API call can be used to authorize up to 50 companies in time. For example in case of a housing company or accounting office that has signing / representation rights for multiple customers. For the authorisation to work, the companies that are authorised need to be from the same country.
Process for company account activation over API
New companies with a new user can be created for:
If you need ro create a new company for an existing user, log-in to Maventa UI first.
Before account can be used it needs to be verified using strong authentication and electronic signing. When the user logs in to the account for the first time, user needs to go through a set-up wizard where they add information of the company and configure some of the basic settings. The last step of the wizard is the company verification process with Visma Sign service.
Different settings can be configured further in the web UI after user has logged in. Dedicated sections help to find the wanted settings and tell more information what the settings are about.
In Maventa there are two type of accounts; Company accounts and Partner accounts. Company account is the default account type. Partner accounts are used by the integrating partners (ERPs and such with multiple customers).
The key difference between a Partner and a regular Company account is that Partner accounts have an own identifier, vendor_api_key, that is used to link actions to the partner company. The vendor api key is used for billing and reporting purposes. One Partner company can own many vendor_api_keys, for example one for each country they have customers in.
Integrators don’t need to worry about controlling the account types, all accounts registered to Maventa are first created as Company account and changed to account type Partner if and when needed by Maventa.
Users are created to Maventa based on an email address. Creation happens at the time of the company account opening, or separately over API or user interface. A user can be connected to many companies and a company can have many users.
Created company user can be real person or an api-user that is a technical user only. Same api-user can be added to multiple accounts, but usually for integrators with larger amount of customers it is for security reasons recommended to have own api-user per account. For example email could be formatted as Maventauser+companyBID@example_domain.com.
Access to Maventa web user interface requires access to user email for authentication. If the new users will log in to UI make sure they have access to their email address.
You can control the user rights by changing the user role. There are two roles, user and admin user. Compared to admin, users have more limited rights to service, they cannot for example modify company details or settings or add new users to the company.
You can configure user specific setting in Maventa, e.g. notifications which user would like to get.
API methods for user management
Take into use different services and networks enabled by Maventa. Select the services that you want to include in your integration and check here the service specific guides for implementation instructions.
Send invoices to consumers into their net bank or mobile application. Use email or printing service as a fallback options for sending.
Invoices to consumers can be sent through Maventa via email, print, or then as an e-invoices or direct payments to the consumer’s netbank.
For sending invoices to consumers via the email or print route you can force the sending using (invoice_put_invoice_with_metadata)
Consumer e-invoicing (B2C) in Finland enables suppliers to send e-invoices to consumers’ personal netbanks and direct payments to consumers who do not use an online banking service. This service is only available for Finnish companies registered to Maventa. If you need to send invoices from Finnish company to consumers outside Finland only option is to send them via email or by print.
In Finland B2C e-invoicing to netbank requires activation through bank messaging. Suppliers activate the consumer e-invoicing via Sender info SI-message and by that notify the consumers of the option to receive e-invoices from that supplier. Consumers inform that they want to receive e-invoices from the supplier with Receiver info RI-message. The ReceiverProposal message RP-message is used when the supplier asks for the consumer’s e-invoice address.
B2C e-laskutuksen avaus
Ensin pitää yritykselle luoda Maventa -tili. Sen saa avattua käyttäen metodia register_with_password. Kun yritys on luotu voidaan yrityksen asetuksia muuttaa metodilla configure_company. Jos halutaan nähdä yrityksen tämän hetkiset asetukset, onnistuu se metodilla show_company_configuration. Uusi käyttäjä Maventa-tilille voidaan luoda metodilla user_create_e.
Pankkiverkon avaus tehdään metodilla authorize_companies. company_auth_status metodilla voi tarkastaa koska pankkiverkko on avattu ja valmiina käyttöön. Pankkiverkon avauksessa kestää muutamia päiviä Danske Bankin kiiretilanteesta riippuen. Vasta kun pankkiverkko on auki, voi aloittaa kuluttajalaskutus sanomien lähettämisen.
Uusi kuluttajaverkkolaskuja lähettävä asiakas
Luodaan ADD (uusi laskuttajailmoitus) tyyppinen SI-sanoma, joka lähetetään APIn yli käyttäen metodia message_send. Täältä löytyy sivu, jolla voi muodostaa laskuttajailmoituksen eri sanomia. Tässä linkki ilmoittamispalvelun soveltamisohjeeseen, josta löytyy sanomien tarkemmat kuvaukset.
Myös RP-sanomat voit lähettää samalla metodilla.
SI-sanoman tilan pollaukseen voidaan käyttää metodia message_status. Huom! SI-sanoman liikkumiseen operaattorin ja pankin välillä saattaa kestää useampi pvä, jopa 5 päivää.
Kun kuluttaja on valinnut yrityksen laskuttajakseen, palautuu RI-sanoma. Saapuneet RI-sanomat ensin listataan ri_message_list metodilla jonka jälkeen sanomat ladataan yksitellen käyttäen metodia ri_message_show.
Asiakas jolla on kuluttajalaskutus käytössä jo toisen operaattorin kautta
Tehdään CHANGE-sanoma, jolla sopimus siirretään vanhalta operaattorilta Maventalle. CHANGE-sanoman saa tehtyä näppärästi olemassa olevan ADD-sanoman pohjalta. CHANGE-Sanoma lähetetään vanhaa yhteyttä pitkin eli vanhan operaattorin kautta pankeille.
Jos myös ERP järjestelmä vaihtuu, kannattaa myös huolehtia siitä, että asiakas saa jotenkin siirrettyä RI-sanomat (tai ainakin niiden tiedot) vanhasta järjestelmästään uuteen järjestelmään. Kun sopimus siirtyy vanhalta operaattorilta Maventa:lle CHANGE -sanomalla, siirtyvät RI-sanomien sopimukset uudelle operaattorille, mutta itse tiedostot eivät. Uudelta operaattorilta näkee siis vain ne uudet RI-sanoma tiedostot, jotka kuluttajat tekevät sen jälkeen kun sopimus on siirretty.
Voitte halutessanne lähettää täysin saman CHANGE sanoman myös Maventa tililtä kaikille pankeille, jotta tiedostot jäävät Maventa -tilille talteen mahdollisia tulevaisuuden muutostarpeita varten.
Uudet RI-sanomat saapuvat jatkossa asiakkaan Maventa tilille, ja näiden lataus onnistuu APIn yli samoilla metodeilla kuin edellisessä tapauksessa (kts. kohta 3.)
There are currently two types of messages supported by Maventa and needed for opening the service and to setting up the consumer e-invoicing, SI-messages and RI-messages. Prerequirement for using the consumer e-invoicing is to have the bank connection activated for the supplier.
In briefly:
SI-message (Sender info) is a notification to the banking system whereby the supplier notifies banks and inform consumers of its readiness to send consumer e-invoices and direct payments. It could be considered as a consumer e-invoicing agreement between the supplier and the bank.
To make a new agreement SI-message MessageActionCode ADD is sent with the method message_send to each bank the supplier wants to use for consumer e-invoicing. To poll the status of sent message use message_status. For SI message our system shows OK immediately when the message has been sent OK to the operator bank. 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. When all is ok new RI-messages will start to flow in.
If the message fails on the bank side you will get an error. In case SI-message is in error state, you can get the errors by first listing them with error_message_list and then viewing the error message with error_message_show method.
If there is a need to change or add some information for the agreement it can be done by sending SI-message with the type CHANGE (e.g. when bank account information is changed or new account needs to be added, or if service provider has changed). Supplier agreement can be deleted by sending SI-message with the type DELETE. This will also delete all the consumer agreements (RI-messages) linked to this supplier agreement.
Implementation guidelines for creating the SI-messages can be found from Finance Finland’s webpage
Billing Subject
Consumer billing includes mandatory billing subject code (PaymentInstructionIdentifier) which is an identifier specified by the sender in the SI-message. Billing subject code is used to identify the reason for payment. Same supplier can have multiple SI-messages with different billing subject. When sending consumer e-invoices this same billing subject code needs to be given in the invoice XML. In Finvoice the billing subject is given in the optional EpiPaymentInstructionID field and in TEAPPSXML description, the corresponding element is HEADER / PAYMENT_INSTRUCTION_IDENTIFIER.
To get this reason for payment to be visualised for the consumers in their netbank or web payment services you will need to specify it in SellerInvoiceTypeText element and with all language code (FI, SE, EN).
<SellerInvoiceDetails>
<PaymentInstructionIdentifier>Vuokra</PaymentInstructionIdentifier>
<SellerInstructionFreeText LanguageCode="FI">Anna viimeisimmän laskun viitenumero </SellerInstructionFreeText>
<SellerInstructionFreeText LanguageCode="SV">Ge den senaste fakturans referensnummer </SellerInstructionFreeText>
<SellerInstructionFreeText LanguageCode="EN">Enter the reference number </SellerInstructionFreeText>
<SellerInvoiceTypeDetails>
<SellerInvoiceTypeText LanguageCode="FI">Vuokra lasku</SellerInvoiceTypeText>
<SellerInvoiceIdentifierText LanguageCode="FI" SellerInvoiceIdentifierType="01">Viitenumero</SellerInvoiceIdentifierText>
</SellerInvoiceTypeDetails>
<SellerServiceCode>01</SellerServiceCode>
</SellerInvoiceDetails>
Bank account information
Supplier’s bank account information is given in the SellerAccountDetails element in SI-message. Bank account numbers must be in IBAN format and supplier needs to define all the account numbers to be used in the consumer e-invoicing. When sending consumer e-invoices the IBAN given in the invoice must match to at least one IBAN given in the SI-message.
List of Finnish banks supporting consumer e-invoicing. We recommend to send SI-message to each of these banks:
Bank Identifier Code | Bank name |
---|---|
AABAFI22 | Ålandsbanken |
DABAFIHH | Danske Bank |
HANDFIHH | Handelsbanken |
HELSFIHH | Aktia |
ITELFIHH | Säästöpankit, Oma Säästöpankki |
NDEAFIHH | Nordea Pankki |
OKOYFIHH | OP-Pohjola-ryhmä |
POPFFI22 | POP Pankit |
SBANFIHH | S-Pankki |
DNBAFIHX | DNB NOR Bank |
RI-messages (Receiver info) can be considered as consumer e-invoicing agreements between the consumer and the supplier and they are always linked to the existing SI-message. There will be as many RI-messages as there are consumers using that particular bank and would like to have the e-invoicing with the supplier in question.
RI-messages with MessageActionCode ADD will be sent to the supplier when a new consumer chooses the supplier as their e-invoicer from their netbank. If consumer’s information is changed, RI-message with the type CHANGE will be sent to the supplier and if a consumer wants to end the consumer agreement with the supplier RI-message with the type DELETE will be sent. It’s recommended to keep own consumer register on the ERP side that has the updated status for each RI-messages. To list received RI-messages use ri_message_list method and to download the messages one by one use ri_message_show method. We recommend to list and download all the new RI-message daily and then update your consumer register accordingly.
If you send an e-invoice and get a sending error that consumer agreement is not active, poll for the RI messages, there should be the delete message for that consumer.
Handy tip for testing: You can send RI-messages to your own account using message_send method. You can both send and download RI-messages yourself to verify that the integration is working before going to production.
RP-message (Receiver Proposal message) is used when the supplier asks for the consumer’s e-invoice address before e-invoices can be sent. When consumer accepts the proposal, RI-message is sent to the supplier. RP-message is a way to get more consumers to take the e-invoicing into use.
• The supplier and the consumer in question have agreed that the supplier requests the e-invoicing address with an RP message.
• SI-messages are sent (supplier has consumer e-invoicing agreement with the banks).
• The PaymentInstructionIdentifier field has same data content in the RP as it does in the SI-message.
NOTE! If the Customer has not reacted within 30 calendar days, the Bank deletes the RP-message from the consumer’s netbank. The deletion is not in any way notified with an ack message.
Implementation guidelines for creating the RP-messages and more information for the process can be found from Finance Finland’s webpage
Consumer e-invoicing can be deactivated by sending SI-messages with the type DELETE. This will delete the supplier agreements with the banks and remove the supplier from the list of companies providing consumer e-invoicing from the netbanks. Deactivation and deleting of SI-messages will also delete all the consumer agreements (RI-messages) linked to the supplier agreement in question. In case there is only a need to change the service provider or other information on the SI-messages there is no need to delete the existing agreements but instead the information can be changed easily by sending SI-messages with the type CHANGE.
In case the service provider will be changed you will need to send SI-messages with the type CHANGE from the old service provider and with those SI-messages inform which will be the new service provider. In this way all the existing consumer agreements (RI-messages) will follow along to the new service provider and there is no changes needed to be done by the consumers. Note! It might take few banking days for the SI messages to travel to each bank and to get validated so you should be prepared for the possible errors to arrive few days after the sending of the messages. This means that you should not close down the old connection immidiately but instead you should wait for couple of days (5 days should be enough). Only after those few days if no errors arrive you can close the old connection. Note! RI-message files from the old service provider are not moved to the new service provider in any automated way. You will need to make sure you have downloaded the files or saved the information to your end.
InvoiceSenderAddress
and InvoiceSenderIntermediatorAddress
should have the current sender information and with NewInvoiceSenderAddress
and NewInvoiceSenderIntermediatorAddress
you can inform the new sender information:
<InvoiceSenderInformationDetails>
<InvoiceSenderAddress>003712345678</InvoiceSenderAddress>
<InvoiceSenderIntermediatorAddress>DABAFIHH</InvoiceSenderIntermediatorAddress>
<NewInvoiceSenderAddress>003787654321</NewInvoiceSenderAddress>
<NewInvoiceSenderIntermediatorAddress>NDEAFIHH</NewInvoiceSenderIntermediatorAddress>
</InvoiceSenderInformationDetails>
Invoices can be sent through AutoInvoice consumers via direct debit (avtaleguiro), eFaktura, Vipps, DPI, e-mail and print. The invoice can be specificed to go a specific route like efaktura or it can be specified to try all routes in a predefined order.
In order to send invoices to consumer the main vendor agreements needs to be signed. The agreement capture, and the direct debit service cant be activated at the same time or after the vendor agreement is active.
Before you can send any invoices B2C through AutoInvoice, or enable any of the extra features, the main Vendor agreement must be activated. Only a norweigian company account in AutoInvoice can send invoices to consumers and be able to activate the business to consumer vendor agreement.
Note that when the agreement is activated the supplier gives consent for visma to delete any old agreement they might to currently send eFaktura, and fetch all their existing consumer agreements.
This can be done either through the API or UI. API method:
Note! This feature will be depricated by Nets december 1st 2021.
Agreement capture (Avtalefangst) is a bank feature where the consumer gets a suggestion to enter into an e-invoice agreement with the vendor, when paying the paper invoice in the nettbank. By using this feature the vendor will reach a high number of consumer e-invoice agreements in the fastest way possible. This is an easy, fast, and user friendly way to enter into a consumer - vendor agreement. The consumer does not need to know their e-invoice reference since that is reported in the KID number. This feature is dependent on the issuer having an OCR agreement with their bank.
How it works:
When the issuer of the invoice reports in their KID, bank account number, and the e-invoice reference position in the KID to Nets through AutoInvoice, then Nets creates an agreement capture rule in the bank. This works so that when the consumer gets the paper invoice and punches in the data manually in the online bank, the bank recognizes the bank account and the KID and identifies that there is an agreement capture in place. When this happens the consumer will get a questions like “This supplier can send you e-invoice in the future. Would you like to accept?”. When the consumer accepts then the bank creates the consumer e-invoice agreement based on the e-invoice reference that has previously been reported and is located in the KID number. That information is then fetched by AutoInvoice and is entered into the CV registry and the next invoice will be sent directly to the netbank as an eFaktura.
This can be enabled through the API or the UI API method:
Note! In pilot mode
Through AutoInvoice it is possible to send an invoice and AutoInvoice will route it is a direct debit invoice to Nets if there is an agreement active, and there is an active consumer mandate. The supplier does not need to create a deduction file, that is done based on the invoice at Nets.
To get started the supplier needs a direct debit agreement (avtalegiro) with their bank. This is a manual process today that is handled outside of Visma. In the agreement with the bank the supplier must specify customer ID = 229221. This is to identify the direct debit feature with visma.
If the supplier already have an active agreement with their bank they can activate direct debit through AutoInvoice and we configure the agreement with Nets.
AutoInvoice needs the following information from the company:
Note! If the supplier already has an active agreement and are already sending deduction files through another route, activation in AutoInvoice does not stop the old route like it does for eFaktura to netbank. Meaning they can send invoice combo through us and deduction file through old channel and it will not be stopped at Nets. However, the mandates can only be fetched from Nets by Visma.
Agreement can be activated through the API or UI. API method:
Note! In pilot mode. Requires a seperat activation which can be done by contacting AutoInvoice team.
Instead of the supplier creats a deduction file and sends to Nets, or through another channel like AutoPay, the supplier can instead send the invoice via AutoInvoice and the deduction file is created based on that invoice. The notification (eFaktura, e-mail or print) is also handled and sent out by AutoInvoice. Meaning the supplier does not have to relate to two different channels. Mandates will be collected and stored in AutoInvoice.
Prerequisites
Notification on upcoming Direct Debit
Its the consumers choice if they want to be notified on an upcoming direct debit and they make that choice when they en they enter into an atg agreement with their supplier. Its either a yes or no to notification, not a how. As a priority the notification will always go as efaktura if they have that activated, if not it can go as e-mail or print. IF the consumer does not want to be notified AutoInvoice only sends the invoice as a direct debit with no notification.
Notification via eFaktura
If the consumer has efaktura activated, either through Y2A or with a direct agreement with the supplier, the notification will always be sent to netbank. It will be shown as an invocie with a direct debit and will not be possible for the consumer to pay.
Notification via e-mail
If the consumer wants to be notified, and does not have eFaktura, then the notification will be sent as e-mail as long as there is an address available. The text in the e-mail specifies that this is a direct debit agreement to eliminate the risk of it getting payed twice.
Notification via print
If the consumer wants to be notified, and does not have eFaktura or any e-mail address, then the notification will be sent to print. AutoInvoice will add a coversheet to the invoice where it specifies that this is a direct debit and should not be payed.
If there is no active mandate the invocie will be routed to the next specified route.
When the vendor agreement is active the first invoice can be sent. If the supplier has moved over from an other solution, the existing efaktura consumer agreements will be fetched to AutoInvocie when the vendor agreement is active. In order to send an invoice as eFaktura the receiver must have a consumer agreement directly with the supplier, or be registered in the “Yes to all” registry with Nets (JTTA).
Consumer vendor registry:
Note! Unique consumer agreements with one supplier will be depricated December 1st 2021 and to be replaced enteirly with JTTA registry.
The consumer vendor registry stores all the consumer agreements, or the consumer eFaktura reference in various states. A consumer’s eFaktura reference is what identifies the consumer with the vendor, and it works as a connection between the consumer and their invoices. It is the central role in transporting B2C invoices between the vendor and the consumer as eFaktura.
There are 4 scenarios where consumer agreements are added into the CV-Registry:
When a customer activates the B2CNO vendor agreement in AutoInvoice the existing agreement that they might have will be automatically deactivated and all of their existing consumer agreements that are active will be copied from Nets and enteres into the customers CV-Registry.
AutoInvoice sends out a consumer request requesting the consumer to activate an e-invoice agreement with this vendor. Consumer does this by following the link in the e-mail/SMS and accepting through BankID. Agreement then gets copied from Nets to AutoInvoice CV-Registry.
Agreement capture with OCR (Avtalefangst med OCR). If agreement capture is active, its a seperat activation, then when consumer pays an invocie in the nettbank it will trigger a question to the consumer if they want to receive an eFaktura next time. This consumer agreements is then fetched and seen in the suppliers consumer - vendor registry.
When the supplier enters into the B2CNO vendor agreement with AutoInvoice, they will automatically be searchable in all netbanks. A consumer can then search for the vendor in their nettbank, and activate their e-invoice agreement automatically.
When the vendor sends an invoice to a consumer with an existing e-invoice agreement the invoice will be directly transported to Nets and then to the consumers netbank. Note the following:
API methods:
Yes to all:
Yes to all, or Ja takk til Alle (JTTA), is used to send an eFaktura to Nets if there is no active consumer agreement in place. Instead of an efaktura reference, the consumer is identified using a eFaktura identifier. With an e-invoice reference there is a direct connection between the vendor and the consumer, but an e-invoice identifier is more general that all vendors can use to send an e-invoice to that consumer. The consumer activates this by logging into their nettbank and activates yes to all, meaning that the consumer accepts e-invoices from all vendors that are able to send e-invoice. If this is activated then there is no need for the supplier to send out any consumer requests and the first invoice can be sent directly to the consumers nettbank.
Note! AutoInvoice does a check towards Consumer Vendor Registry (CVR) before doing a lookup towards Y2A. If there is an active agreement in CVR then there will be no lookup towards Y2A.
When the consumer activates Y2A in their netbank the banks pushes certain information to Nets Y2A registry that Autoinvocie uses for lookup to get the consumers e-invoice identifier. Today it is mandatory for all banks to push Social Security Number (SSN) to the registry but other aliasas include e-mail, phone, address, postal code, first name, and last name. On the basis of these AutoInvoice does a look up towards the registry. If there is a hit then we forward the invoice directly to the netbank.
AutoInvoice does a lookup with the following information (Note that these can change):
If AutoInvoice cannot find an active eFaktura reference, or a eFaktura identifier, the invoice will be routed to the next route.
AutoInvoice will check towards Vipps based on mobile number and get back a token if the consumer has activated Y2A either in their netbank or in their vipps application. If the consumer has not activated Y2A the invoice will not be sent to vipps.
Requirements on consumer to receive an invoice in Vipps:
The invoice will then be sent directly to Vipps and because of the merge between Nets and Vipps eFaktura, the invoice will also be visible in the nettbank. Invoice can be payed in either and status updates in both. The same is true the other way around, if the invoice is sent to nettbank, the invoice will also be shown in Vipps.
However the following scenarios need to be taken into account:
KID number: Supplier does not have to send KID when sending invoices to Vipps. If the sender does not have OCR agreement with their bank, and does send KID number then the payment will not go through.
Fallback settings: There is no fallback setting to sending to Vipps. Instead when using the operator code B2C_VIPPS and B2CNO the invoice automatically gets sent to fallback e-mail and print through route_order if the recipient has not activated Vipps eFaktura.
Creditnotes: Not supported. Invoices can be sent to Vipps and invoices with total amount = 0.
Direct debit invoices: Direct debit invoices, or avtalegiro + efaktura combination invoices, are not supported through Vipps.
Attachments and invoice image: Attachments are supported through visma document hotel. Limitations are the same as to print. AutoInvoice send a link to Visma document hotel where we show only PDFs. If the invoice contains other formats like .png we do not pass these on to consumer.
Status:
When sending an invoice to Vipps the invoice is then validated and been sent to the consumers application and is visible under the payment section in the application. This is done in about 15 minutes. Status with Vipps is then pending and status with AutoInvoice is sent. Sent status is the final status of this invoice. There it will stay until 14 days after due date then it is removed from the application.
There is no way to know if the consumers has payed the invoice. Vipps does not collect the information from the banks.
Explanations of the states in Vipps: https://github.com/vippsas/vipps-invoice-api/blob/master/vipps-invoice-api.md#detailed-information-about-invoice-states-and-transitions
Note: ERPs that use invoice_create method can not send invoices to VIPPS because the phone number could not be saved to Database
AutoInvoice can route an invoice to DPI, which is used only by municipalities (Enterprise). When sending to DPI the payload must contain a social security number (personnummer) in a .aix file. The SSN will be used to check the consumer against the Kontakt og Reservasjonsregistret (KRR). In KRR the consumer has choosed if they want to receive invoices or not to their DPI account, and if that account is in either eBoks och DigiPost.
In order to send to DPI or send with SSN contact partner support or AutoInvoice team.
If all is OK the invocie will be routed to DPI..
guide
Send and receive electronic invoices and other trading documents in an international Peppol network.
Peppol eases the trade between suppliers and buyers by providing a standardised way for exchanging trading documents electronically within countries and cross-border. Sending and receiving between recipients takes place over Peppol Access Points that connect the buyers and suppliers to the network.
Maventa is one of the cerfified Peppol Access Points. This means that when you are integrated to Maventa you can easily provide connection to Peppol to your customers.
0192
. For Norwegian company whose organisation number would be 123456789
Peppol address would be 0192:123456789
APIs to use
REST API - Invoices and other documents
SOAP API - Enable/disable, invoices only
Note that using different Access Points for different document types is possible, e.g. one to receive invoices, another to receive orders, but company cannot register the same document type to different Access Points.
If the company is already registerd to receive invoices through another Access Point than Maventa this registration needs to be removed by the old Access Point before Maventa can do the registration
To create registration to Peppol
REST API Call POST /v1/company/profiles
INVOICE_AND_CREDIT_NOTE
PEPPOL
{
"profiles": [
"INVOICE_AND_CREDIT_NOTE"
],
"profile_version": null,
"endpoint_id": "003712345678",
"scheme": "0037",
"network": "PEPPOL"
}
SOAP API Call enable_operator with enabled=true
INVOICE_AND_CREDIT_NOTE
Maventa creates the registration with the following identifiers (schemes)
0192
)0037
)0007
)9902
)0106
or 9944
- depending which is used to register company account to Maventa)If you want to register a participant outside of these countries or with a different identifier please contact Maventa.
REST API
REST API
To follow up when the registration has been succesfully completed you can register to callback notifications. Use the event type NETWORKS to get notification of all changes in the registration statuses.
To remove registration from Peppol network
REST API
SOAP API
enabled=false
INVOICE_AND_CREDIT_NOTE
Use print service to print the invoice and deliver it by post to recipients who cannot receive electronic invoices. Define the settings based on your customer needs.
Print can be used as the option to deliver the invoice if it is not possible to send it by e-invoicing or email.
The requirements to send the invoice by print are that:
See the used price list for print related transaction costs.
To activate the print service call API method configure_company and set parameter print_and_send_request = 1 (1 = yes, 0 = no). Show_company_configuration method and parameter print_and_send_enabled (true/false) can be used to check the status of the print service.
Note! For Finnish and Swedish companies (without VAT number) activation will take some time since requests are confirmed manually. Bear this in mind especially if activating the service takes place outside regular business hours.
Invoices sent via print service will by default use the Maventa PDF-template. This template is optimized for effective handling. If you wish to use your own company logo on the PDF-invoice, you can upload it with update_logo API method. To remove the uploaded logo use remove_logo method.
If you wish to use your own PDF-template, in configure_company method set parameter print_and_send_own_pdf = true. This will add a coversheet with address information to all printed letters, which means they will always be at least two pages. C5 envelopes are used for the print service.
Note that using your own template is done on your own risk and the result may not be as desired due to technical restrictions. Please make sure to keep the top and right margins empty and do not send any invoice image or attachment that with black/dark background.
All files must be of PDF format (or have the same content requirements) for it to be printed correctly. That means that the file cannot contain dynamic components and that all fonts, images and others are included in the file (ie the files should be 100% “self-contained”). All new customers must test their PDF files (all variants of fonts, images, etc.) to verify that the PDFs can be handled. If the PDF contains graphics, such as logos, charts, and other images, they must be of good quality.
Invoices sent via print service will by default use the Maventa PDF-template. This template is optimized for effective handling. See the example PDF-template
If you use your own PDF-template familiarize yourself with the address positionin rules provided by the printing service provider.
Prints are always double-sided if there is more than one page.
There is a possibility for customers to choose if they want their invoice images to be printed with colors or black & white. Note that using color printing might cause extra costs depending on the price list used. To enable the color printing use configure_company method and set print_and_send_color parameter to true. Default setting is black & white.
Invoices that are sent to Maventa before 24:00 will get printed during that night and delivered to the post office next morning. Post will deliver invoices to the receivers according to the chosen letter class. There are two letter class options available for Finnish companies to choose from, economy and priority. You can change the letter class using configure_company method and print_and_send_letter_class (1 = Priority, 0 = Economy) parameter. Priority is the default value.
Separate attachments are not printed only the invoice image is. To get the attachments printed they must be merged with invoice image before being sent to Maventa.
When this setting is turned on every printed paper invoice using default PDF-tempate is automatically accompanied with instruction page which explains how your customer can receive invoices electronically instead of paper. Instruction page is free of charge for you. To use the automatic e-instructions page call configure_company method with parameter marketing_on_invoice = true.
OmaPosti is an application customer can use to receive letters electornically instead of the paper version. If OmaPosti account is found, the invoice will be scanned and re-directed there. If not found, the invoice goes to printing and as a letter to the recipient. Combination of receiver’s name and postal address is used to identify if the receiver has OmaPosti account. Also personal identification number is used as an identifier but it is highly recommended not to use such ids on invoices.
Invoices sent via print service will by default use the Maventa PDF-template. This template is optimized for effective handling. See the example PDF-template
If you wish to use your own PDF-template familiarize yourself with the address positioning rules provided by the printing service provider seen on the image below:
Separate PDF attachments are printed with following rules:
Note! There is an extra charge per page printed.
By default the printing of attachments is enabled. If you wish to disable it you can do it by calling configure_company method and setting the parameter print_attachments_disabled to true (true = disabled, false = enabled).
Invoices sent via print service will by default use the Maventa PDF-template. This template is optimized for effective handling. See the example PDF-template
If you wish to use your own PDF-template familiarize yourself with the address positioning rules provided by the printing service provider seen on the image below:
Separate attachments are not printed only the invoice image is. To get the attachments printed they must be merged with invoice image before being sent to Maventa.
By default customer own invoice image is used for prints and a coversheet (with address information) will get added with no extra cost. If there is no image given we will generate our invoice template.
configure_company parameter print_and_send_own_pdf does not have any effect on Dutch companies. Dutch printing service will always use own PDFs.
Separate PDF attachments are printed with following rules:
Note! There is an extra charge per page printed.
By default the printing of attachments is enabled. If you wish to disable it you can do it by calling configure_company method and setting the parameter print_attachments_disabled to true (true = disabled, false = enabled).
There are two options for letter class, economy and priority. You can change the letter class by calling configure_company method and setting the parameter print_and_send_letter_class to 1 = Priority or 0 = Economy.
By default everything is printed with colors. configure_company parameter print_and_send_color does not have any effect on Dutch companies.
To close the print service, call configure_company method with parameter print_and_send_request = 0.
To reopen the service, just follow the steps in chapter Opening service. The print service is enabled immediately after activation, without approval needed.
Print service activation, closing and configuring the settings can all be done over the Maventa UI. The print service settings can be found under Invoice sending settings.
Use Maventa Direct Print API to send EPL and PDF files as letters through print service. The service is currently available in Finland only.
Maventa Mass printing service (also known as Payslip) is a service that enables sending of EPL and PDF files as letters through the printing service in Finland. Service was initially build to send payslip material, but it can be used for sending any kind of letters, as long as the printing service rules are followed.
Payslip can be used either through the UI from address https://payslip.maventa.com (testing https://payslip-stage.maventa.com) or via HTTP API.
You need a separate user account for the Mass printing API in order to use it. You can open the account with an API call to https://payslip.maventa.com/register using existing vendor_api_key and company_uuid for Maventa.
Key | Example | Description |
sw_api_key | d33e92be-a46b-4963-8ada-25452712e0a6 | Existing software API key from Maventa |
company_uuid | 99445728-5fd3-428a-96e1-ca0cab692276 | Existing company uuid from Maventa |
company_name | Test Company Oy | Name of the company, needs to be unique! |
user_email | test@yritys.fi | User email address that will be used as user name, needs to be unique! |
user_pw | secret1234 | Password for the user |
test_mode | 1 | 1 opens the account in test mode which means that material is not really send out. Note! Contact support to disable the test mode. 0 opens the account in production mode |
disable_notify_on_complete | 1 | 0 (default) user will get an email notification when material is printed successfully. |
The response code will always be a HTTP 200 and the response body is one of the following:
Value | Description |
“OK” | Successful registration, letters can be send and login works |
“ERROR: COMPANY UUID ALREADY REGISTERED” | Registration failed, company exists already in Payslip service |
“ERROR: USER EMAIL ALREADY REGISTERED” | Registration failed, user email exists already in Payslip service |
“ERROR: ONLY FINNISH COMPANIES ALLOWED” | Only Finnish companies allowed to register |
“ERROR: USER EMAIL INVALID” | Invalid email address |
“ERROR: INVALID VENDOR KEY” | Invalid software API key |
“ERROR: INVALID COMPANY UUID” | Invalid company uuid |
“ERROR: INVALID VALUES” | Company_name, user_email or user_pw empty |
“ERROR: REGISTRATION FAILED” | Most likely company name already exists in Payslip service. |
To send a letter to Mass printing service call the API endpoint payslip.maventa.com/input_public.
You need to give authentication using HTTP headers. You can give either:
USERNAME
and USERPW
with which you registered your Mass printing API accountCOMPANY-UUID
and USER-API-KEY
of your Maventa accountKey | Example | Description |
version | MyOwnERP | Name of the software (and its version) making the sending. Makes problem solving easier |
filename | letters_2019_12.zip | Name of the ZIP package, should be unique |
file | RVBMMTExMzQ0O | Base64 encoded ZIP file content |
zipHash | 69a56b2b66d548d7b51f6dcc9003e90bafce2162 | SHA1 hash of ZIP content, will get check in server to make sure package came through as whole |
hash | 856697ad0cae67ec48f7627be4cef74feaa2f36b | SHA1 has of EPL content, will get saved to server for duplicate prevention. Same hash key cannot be used for sending again |
document_type | PDFXML | PDFXML or EPL |
letter_class | economy | Economy or priority (default value). Letter class to use for sending |
sw_api_key | 5992955a-3b66-4439-94d1-a854a764da49 | Existing software API key from Maventa. Value given in sending call will override the one set for the Payslip company account in registration |
license_key | 1234-5678-MKSK-1234 | License key of software making the call (255 chars max) |
license_meta | License key for MyOwnERP | Additional information about the licensing system |
color_print | true | Color printinting true Black&White false (default value) |
duplex | true | Duplex printing for both sides of the letter. default is false |
The response code will be a HTTP 200 and the response body is one of the following or “401 Unauthorized” if authentication fails:
Value | Description |
“OK: sent_filename.zip” | Successful sending |
“ERROR: HASH VALUE DOES NOT MATCH” | Parameter zipHash does not match to the SHA1hash |
“ERROR: ERROR: DUPLICATE FILE” | Found file with parameter hash |
“ERROR: FILE TOO LARGE” | API allows max 10Mt files |
“ERROR: DOCUMENT TYPE UNSUPPORTED” | document_type is something else than EPL or PDFXML |
“ERROR: FILE IS NOT ZIP” | Parameter filename needs to be .zip |
“ERROR: ZIP FILE CONTAINS UNSUPPORTED FILES” | When sending EPL, allowed is only .epl file. When sending PDF, allowed is only .pdf files |
“ERROR: ONLY ONE EPL FILE ALLOWED IN ZIP” | Only one .epl is allowed per one sending |
“ERROR: ZIP FILE CORRUPTED” | Unzipping failed |
“ERROR: NO LETTERS FOUND” | No letter were found. EPL version used is not supported or no .pdf files found inside the zip file |
“ERROR: sent_filename.zip” | Unexpected error, sending failed. Contant our support for more information |
All files must be of PDF format (or have the same content requirements) for it to be printed correctly. That means that the file cannot contain dynamic components and that all fonts, images and others are included in the file (ie the files should be 100% “self-contained”). All new customers must test their PDF files (all variants of fonts, images, etc.) to verify that the PDFs can be handled. If the PDF contains graphics, such as logos, charts, and other images, they must be of good quality.
<?xml version="1.0" encoding="ISO-8859-1"?>
<lb:LetterBundle schemaVersion="v0x4" senderFileId="FileD1" xmlns:lb="urn:itella-letterbundle-v0x4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:itella-letterbundle-v0x4 LetterBundle_V0x4.xsd">
<lb:Bundle senderBundleId="">
<lb:BundleCommon creationDate="2020-06-24T13:17:00.0Z" isTest="false">
<lb:Sender companyName="Maventa Oy" contact="" contactPerson="Maventa Support" email="support@maventa.com" phoneNumber="010-5058474" ovtID="003721291126">
<lb:SenderAddress>
<lb:Eu1 name="Your company Oy" address="PL 000" postalCode="00101" city="Helsinki" countryCode="FI"/>
</lb:SenderAddress>
</lb:Sender>
<lb:StdBundleProcessing customerId="" departmentClassification="false" electronicArchiving="T" envelope="S" fileFormat="0" isDuplex="true" letterClass="2" paper="0" password="" serviceFunction="0"/>
<lb:ExternalFile fileName="sent_filename.pdf" format="PDF" senderFileId="wm_0c5c09e0-03d3-4340-bb6b-0c3c14be7f42">
<lb:CheckSum type="MD5" value="nnnnnnnnnnnnn"/>
</lb:ExternalFile>
</lb:BundleCommon>
<lb:Letter senderLetterId="LetterID1">
<lb:LetterMeta>
<lb:Location pages="1" startPage="1"/>
<lb:Recipient>
<lb:Address>
<lb:Eu1 address="Kotikatu 1" city="Helsinki" countryCode="FI" name="Asiakas Anssi" postalCode="01001"/>
</lb:Address>
</lb:Recipient>
</lb:LetterMeta>
</lb:Letter>
</lb:Bundle>
</lb:LetterBundle>
Latest instructions for the letter layout
Receiver information should be marked as clearly as possible with the following order to make sure machine readability:
To check the status of the sent package, use https://payslip.maventa.com/file_status. API call contains HTTP-header where user name and password are given with USERNAME and USERPW parameters. In addition a GET for giving the sent file name with filename parameter.
You need to give authentication using HTTP headers. You can give either:
USERNAME
and USERPW
with which you registered your Mass printing API accountCOMPANY-UUID
and USER-API-KEY
of your Maventa accountKey | Example | Description |
filename | sent_filename.zip | Name of your ZIP package |
Value | Description |
“DONE” | Package is processed and sent successfully |
“PENDING” | Package is still in sending process |
“ERROR” | Sending of the package has failed (in these cases our support will get notified and they will contact the sender with more detailed reason for error) |
“ERROR: No file found” | No file found with the given filename |
PDF material that has been sent to Maventa before 24:00 will get printed during the same night and sent to post office next morning. Post will deliver material to the receivers according to the chosen letter class.
If you wish to close the service please contact Maventa support.
Activate Maventa Receivables Management Service to accelerate cash flow and free resources from manual work. The service handles reminders, payment monitoring, payment allocation, and debt collection after the invoice has been sent. Note! Only available for Finnish companies.
The Receivables Management service handles payment monitoring, payment allocation, sending of reminders, and debt collection on behalf of the company. Company only needs to create and send the invoice as normally (including the error handling) and the service does the rest. The service is provided by Visma Financial Solutions Oy through Maventa and it is included in the Maventa service with no additional costs for using it. Only costs there might be are related to the debt collection process in later phases and if assignments are cancelled (see price list).
SEND ERROR (REASON: RECEIVABLES-SERVICE: Postal code for CITY_NAME xxxxxx not found (code #5))
and won’t get sent out to the receiver. You will need to create a new invoice with corrected address and send it again.SEND ERROR (REASON: RECEIVABLES-SERVICE: The due date for the invoice is within three (3) days or has already passed (code #13))
and won’t get sent out to the receiver. You will need to create a new invoice with proper due date and send it again.(SEND ERROR (REASON: RECEIVABLES-SERVICE: Invoice already exists (code #6 e5006e70-dfab-49da-90fd-2e47d2eb8ea6)))
and won’t get sent out to the receiver.In all of the above cases the invoice is not sent to the Receivables service which means that it won’t be sent to the receiver either.
To open the Receivables Management service use REST API method PUT /v1/services/receivables
to initiate the activation process. In order to get the service activated an electronic agreement between the company and Visma Financial Solutions needs to be filled and signed by a person having authorized signatory rights for the company (or the one signing needs to have a letter of attorney which needs to be attached to the agreement). Signing of the electronic document requires authorized person to authenticate themselves using their personal online bank identifiers or mobile signature. Authentication and signing process is done by our partner VismaSign. With the parameter authorization_email you can specify the email address for which the VismaSign request is sent to.
Parameter | Description |
---|---|
iban | Account information (IBAN) that Visma Financial Solutions will use when they pay the money they get from the receivers/debtors. There can only be one account. |
bic | Bank identification code e.g. DABAFIHH |
bank | Name of your bank |
contact_person | Contact person name |
contact_email | Email for possible problem cases and contacting |
contact_phone_number | Phone number for the contact person |
authorization_email | Email for sending the request to sign the electronic agreement. Should be someone having the signing right for the company |
customer_service_email | This email will be shown on the factoring clause that Visma Financial Solutions will add to the invoices routed through them |
customer_service_phone_number | This phone number will be shown on the factoring clause that Visma Financial Solutions will add to the invoices routed through them |
billing_address | Billing address for possible service costs related to the debt collection processes in the later phase. Price list |
postal_address | Company’s postal address |
When agreement is signed and verified the service gets activated. Note! If you have consumer invoicing enabled you will need to add Visma Financial Solution’s provided IBAN to your sender agreements (SI-messages). You will get the IBAN as a response parameter from the GET /v1/services/receivables
call. Read more How to handle Finnish consumer invoicing.
Use GET /v1/services/receivables
to fetch the status of the activation to see when the service is activated. Or register a webhook to get a callback notification from Maventa when the service gets activated (or rejected).
Receivables Management service can also be activated through our user interface.
If you have the Finnish consumer invoicing enabled on your company’s account, there is an important change you will need to do before this Receivables Management service can be used with e-invoicing to netbanks. There will be a 5 days delay to do the needed changes. During these 5 days all the consumer e-invoices will still go directly to the banks instead of going through the Receivables Management. After the delay the consumer e-invoices are also routed through receivables Management like all the other invoices. This change will enable consumer e-invoices to be sent to your consumers with the Visma Financial Solutions IBAN information.
You will need to update your consumer agreements (SI-messages) by adding Visma Financial Solutions’s provided IBAN to them.
You will need to send CHANGE type senderinfo messages SI-messages to each bank you have the agreement with. In the SI-message you will need to add Visma Financial Solutions’s provided IBAN number as a new seller account (note! we do not recommend to override the existing seller account information but instead just add that as a new one). If there is a functionality to create and send the SI-messages directly from your ERP you can most likely do the change easily through that. If you are unsure if there is such functionality in your ERP or you don’t know how to use it contact your ERP support team. After the messages are created they can be sent through our UI or via the API. More information about SI-messages and a link to message_send method to use for sending.
After the Receivables management service is in use sent invoices will always have Visma Financial Solutions created reference number when sending them to the receivers. If reference number is used to link new consumer agreements in your ERP’s consumer register you might want to check the reference number used by Visma Financial Solutions from the assignment details using GET /v1/assignments/{assignment_id}
method from the “reference_ids” parameter, value for the type “number”. And then connect also that reference number to your register. Visma Financial Solutions’ reference number will be the one consumers will use and fill in to the consumer agreement in their netbanks. Another option is to change the id (SellerInvoiceIdentifier) used to link consumers to something else than the reference number.
Read more about the RI-messages from the Consumer invoicing for Finland guide.
If you wish to change or update any information you will need to contact our support.
From all the invoices sent through the Receivables Management service an assignment is created. Assignment is something through which the company can follow up the process on the Visma Financial Solutions side and if the invoice gets paid on time by the debitor (receiver). Assignment is also used for all the communication between the sender company and Visma Financial Solutions. To link the sent invoice and assignment together, there is parameters reference_ids and invoice_id in the assignment having the invoice uuid of the sent invoice. There are 3 different statuses the assingment can have:
Parameter | Description |
---|---|
id | Assignment id |
status | Open (unpaid) / closed (paid or cancelled) / partially_closed (Invoice is paid but not the reminder or collection charges) |
debtor | Name: Name of debtor (receiver of the invoice) |
due_date | due date from the original invoice or new due date if due date change request is accepted (see Request a due date change event) |
issued_at | Invoice date from the original invoice |
number | Invoice number from the original invoice |
sum | Total sum of the invoice |
paid | Amount that is paid or credited |
currency | Currency from the original invoice |
created_at | When assignment was created |
updated_at | When assignment was updated last time (e.g. when paid sum was updated) |
closed_at | When assignment was closed by Visma Financial Solutions |
reference_ids | Contains tree ids: agency_id = Visma Financial id, invoice_id = id of the original invoice (invoice uuid), number = New reference number that was changed to the original invoice |
[
{
"id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
"status": "open",
"debtor": {
"name": "Hanna's Test Company"
},
"due_date": "2020-04-20",
"issued_at": "2020-04-01",
"number": "64488",
"sum": 12.3,
"paid": 10,
"currency": "EUR",
"created_at": "2020-04-15T05:47:07Z",
"updated_at": "2020-04-15T21:01:18Z",
"closed_at": null,
"reference_ids": [
{
"type": "agency_id",
"value": "078dbb88-ef8e-4115-8260-c8a542aaa87c"
},
{
"type": "invoice_id",
"value": "f6dcf18d-a1bd-4e72-bb8a-80908527b6c8"
},
{
"type": "number",
"value": "356241887794"
}
],
"events": [
{
"id": "c0c56722-a28b-49d1-aa87-1c4d7f3cf1af",
"type": "paid",
"data": {
"sum_paid": 10,
"booked_at": "2020-04-16",
"archive_number": "12345"
},
"party_id": "938fc79f-9c00-47af-8507-cdf15838aa96",
"seens": [
{
"seen_at": "2020-04-15T22:00:06Z",
"seen_by": "Visma Financial Solutions FI"
}
],
"created_at": "2020-04-15T21:01:18Z",
"happened_at": "2020-04-16T00:00:00Z"
}
]
}
]
REST API for assignment handling.
Parties connected to an assignment (company and Visma Financial Solutions) can add events to communicate changes to the assignment. Events describe what has happened to the assignment for example when the debtor pays the invoice Visma Financial Solutions will add an Paid event to the assignment. Events can also be used to update assignment information from the sender side like requesting a new due date or inform direct payments. Events can be considered as a communication channel between Visma Financial Solutions and your company.
We highly advice to automate these events as far as it is possible from the ERP. At least paid
and credit_note
events for making sure these will be commnunicated always to the Visma Financial Solutions without needing to rely end user to remember to do these through our UI.
REST API for event handling.
comment
- Add a comment or question. With this event you can add a comment or ask a question from Visma Financial Solutions related to the assignment in question. Visma Financial Solutions will also use this event for sending comments or questions to your company.
It is highly recommended to follow up closely these comment
events. Good solutions would be to build some separate view to list only the comment
events for a clear separation from all the other events. In this way you will ensure that customers will easily see if an assignment gets a question or a comment from Visma Financial Solutions that they might need to respond to somehow.
Both company and Visma Financial Solutions can send this event.
paid
- This event is used for notifying when assignment gets paid by the debtor, for informing direct payment and for marking credit note as used.
Notifying when assignment gets paid by the debtor: Visma Financial Solutions will use this event to notify when the debtor has paid the assignment either fully or partly. If the debtor pays the whole sum Visma Financial Solutions marks the assignment as closed (close
event is added).
If the debtor pays more than the invoice sum is the extra money is returned to the debtor. So there is no way of paying more than one invoice at a time. Visma Financial Solutions won’t save the money to upcoming payments.
Inform direct payments: With this event you can inform Visma Financial Solutions Oy if the debtor has made a direct payment to your company’s account. Amount paid can be either full or partial payment. Use a comment
event if you want to give some additional information related to the payment. If assignment is fully paid Visma Financial Solutions will close the assignment afterwards (close
event is added). It is really important to use this event to inform the direct payments in order for Visma Financial Solutions to know to update the sum that is still open or to close the assignment. We highly advice to automate this event from the ERP when direct payments happens.
Mark credit note as used: When credit note is sent and connected to an assignment (credit_note
event is used) credit note is also needed to be marked as used and that can be done using this event for the credit note and giving the paid sum as negative value. In this way Visma Financial Solutions will get the information to also mark the credit note as closed (close
event is added). (When connecting a credit note to an assignment through our UI the credit note is marked automatically as used.)
Paid event will update the parameter “paid” in the assignment. the assignment “sum” does not get updated.
{
"type": "paid",
"data": {
"sum_paid": 200.5,
"booked_at": "2019-01-04",
"archive_number": "12345"
}
}
Both company and Visma Financial Solutions can send this event.
due_date_change_request
- Request a due date change. If there is a need to update the due date of an assignment, you can request the change. Visma Financial Solution Oy will either accept or reject the request depending on the new due date and how far in the collection process the assignment already is. If the debt collection process has been started, due date change will be rejected. When a due date change request is accepted you will receive a confirmation event (due_date_changed
event is added) about the acceptance and due date is updated accordingly for the assignment (parameter due_date gets a new value).
If request is rejected you will get a comment with the reason for the rejection (comment
event is added).
Only company can send this event.
due_date_changed
- This is an event that will be received when due date change request is approved by Visma Financial Solutions. This will update the assignment’s due date. Note! This won’t update the original invoice in question.
Only Visma Financial Solutions can send this event.
credit_loss
- You can report a credit loss on assignment in question. Reporting a credit loss is only done for the accounting purposes and has no impact on the payment control and monitoring. Visma Financial Solutions will continue the collection process. Usually Visma Financial Solutions will suggest that the sender marks the assignment as credit loss if they know the debtor won’t pay it. Note! After posting, the credit loss cannot be reversed or modified.
Only company can send this event.
credit_note
- You can connect a credit note to an assignment by giving the credit note number and credit sum with this event. This event is added for the assignment in question you want to connect the credit note to. Give the credit note sum as positive value in the request. If assignment is fully credited Visma Financial Solutions will close the assignment (close
event is added). If the credit note is sent through Maventa you will also need to mark the credit note as used and connected by adding a paid
event to the credit note assignment and give the paid sum as negative value. If the credit note is not sent through Maventa you should still use this event to inform Visma Financial Solutions for crediting the assignment so that they know to close the assignment, or if only part of the assignment is credited they will continue payment monitoring and possible debt collection process with a different sum.
If whole assignment is credited with the credit note:
Assignment gets credit_note
event with credit sum given as positive value
Credit note gets paid
event with paid sum as negative value
We highly advice to automate this event in the ERP side to always create credit_note event to an assignment when user creates credit notes in the ERP.
Only company can send this event.
cancel
- You can cancel the whole receivable process for the assignment. Please note that this will close the assignment (close
event is added) and the closing cannot be reversed or modified afterwards. Visma Financial Solutions will not monitor the assignment or take actions to collect the debt. Company is then responsible for monitoring the assignment. Do not use this for reporting a credit loss. NOTE! There will be an extra costs related to the cancelling of assingments so this event is not recommended to be used only for making sure the receiver does not get reminders or end up in the debt collection. We recommend to put the assignment to a temporary prohibition of collection for a long period of time.
Only company can send this event.
freeze
- You can freeze the collection process for the assignment in question until a certain date. Please note that once a prohibition of collection has been set, Visma Financial Solutions will not monitor the assignment or take actions to collect the debt. Company is then responsible for monitoring the assignment. The prohibition of collection period you set will automatically be removed after the expiration date. You can update the prohibition of collection expiration date by choosing a new date or you can end the prohibition by setting today as the end date.
With parameter “frozen” the prohibition is either set (true) or deleted (false)
{
"type": "freeze",
"data": {
"frozen": true,
"end_date": "2019-01-04"
}
}
Only company can send this event.
interest_paid
- With this event Visma Financial Solutions will inform if there was interest paid for an assignment and what was the interest amount. This event is usually received at the same time than the paid event.
Only Visma Financial Solutions can send this event.
cash_discount
- With this event Visma Financial Solutions informs if the debtor used cash discount on the payment and how much was the cash discount amount.
paid
sum + cash_discount
sum = assignment’s sum
This event is usually received at the same time than the paid event.
Only Visma Financial Solutions can send this event.
collection_started
- This event is used by Visma Financial Solutions to inform when the debt collection process has been started for an assignment.
Only Visma Financial Solutions can send this event.
reminder_sent
- This event is used by Visma Financial Solutions to inform when a reminder is sent to the debtor.
Only Visma Financial Solutions can send this event.
close
- This event is used by Visma Financial Solutions to mark the assignment as closed. Assignment gets closed when it is fully paid by the debtor, marked as fully paid by the sender or if the sender wants to cancel the assignment.
Only Visma Financial Solutions can send this event.
partially_closed
- This event is used by Visma Financial Solutions to mark the assignment as partially closed. This is used when invoice sum is fully paid but debtor did not pay reminder or collection charges. This means that from the mandator’s perspective the assignment is closed, but the debtor still needs to pay more money to the Visma Financial Solutions. When assignment gets this event it’s status changes to ‘partially_closed’.
When debtor eventually pays the remining reminder or collection charges Visma Financial Solutions will add the close
event and the assignment status changes to ‘Closed’
Only Visma Financial Solutions can send this event.
delivery_status
- This event is mainly created for Visma Financial Solutions to follow up if the original invoice sending has been successful or if it has failed. If the original invoice has ended up in the error state and haven’t reached the receiver Visma Financial Solutions will set the assignment related to it to the temporary prohibition of collection. It is sender’s responsibility to make sure the original invoice reaches the receiver and sender should handle the error cases (resend, credit or cancel the assignment). Setting the assignment to the temporary prohibition of collection state is to avoid situtations where receiver would eventually get reminders or the debt collection process would be started without them actually ever seeing the original invoice. If the invoice remains in error state more than a week, Visma Financial Solutions contacts the sender.
Only Maventa can send this event.
Full API integration (all done inside the ERP) | Lightweight Integration | No API integration | |
---|---|---|---|
Activation | Through API using PUT and GET /v1/services/receivables |
Full API integration / No API | Through the UI using our form |
Consumer invoicing | ERP creates and sends automatically the SI CHANGE messages when service gets activated. The IBAN needed is in the response of GET /v1/services/receivables. ERP handles the targeting of the new RI messages in case reference number is the connecting information: The reference number VFS used in the invoice can be found from the assignment details “reference_ids” and type “number” | Full API integration / No API | End customer creates SI CHANGE messages and then sends them through our UI. VFS IBAN is shown in the Receivables Settings page. Customer needs to then also somehow handle the targeting of new RI messages manually |
Assignment listing | /v1/assignments, /v1/assignments/{assignment_id} and /v1/assignments/{assignment_id}/events. Assignments could be listed as their own view or then you could think of having the assignment information (and possibility to add event) shown under the invoice details. | Full API integration / No API | End customer uses our listing of assignments in our UI |
Events | /v1/assignments, /v1/assignments/{assignment_id}, /v1/assignments/{assignment_id}/events and /v1/events. You should think a bit how much your customers would like to follow up the receivables and which events do they want to see or being able to add themselves. Is it enough to see if there is something happening, for example a comment is added by VFS or if there has been a reminder sent for a debtor that hasn’t paid on time? Should these events create some notification on the ERP side when arriving through the API? Adding of events to an assignment is something that should be fully integrated as part of the ERP processes. For example if direct payment comes in then paid event is automatically created from the ERP to the Receivables API. Also having some separate handling for comment events would be beneficial so that important comments or questions from VFS would not get lost and it would be easy for the customer to reply | We highly advice to automate at least the events for direct payments (paid event) and connecting credit notes (credit_note event). Also the request to change a due date and then the confirmation for that (due_date_change_request , due_date_changed ) |
Customer needs to handle all the events through our UI which migh in some cases mean double work. For example requesting a new due date might also then need them to do a change also on the ERP side. Informing of direct payments and connecting credit notes are then on the hands of the customer. These are something that are really important to remember to do so that VFS does not start collection process even though the debtor has already paid the invoice |
Debtor specific prohibition of collection | It is not recommended to use the cancel event for this purpose but instead the freeze event. Using cancel will cost for the customer since it requires always manual handling from VFS side. What you should do is it to automatically add freeze event after the invoice is sent from the ERP and assignment is created (can be found from the assignment list) for those debtor’s invoices you want to be set to prohibition of collection. In that freeze event define the expiration time for long in the future. This way debtor won’t get any reminders even if they wouldn’t pay on time. And when the debtor pays assignment gets closed by VFS. |
Full API integration / No API | Prohibition of collection needs to be done through the UI by the customer assignment by assignment |
Service can be closed by either deregistering the profile from the RECEIVABLES network through the API or then by closing the service through the user interface. After the service is closed new invoices sent are not routed through Visma Financial Solutions anymore. Visma Financial Solutions will still handle the open assignments.
Reopening the service needs manual handling and therefore being in contact with our support.
Use scanning service to receive PDF and print invoices in electronic format. Open scan accounts where suppliers can send print and PDF invoices. The invoices are scanned and then delivered to the companies as electronic invoices.
The scanning service receives invoices either as PDF (by email) or as paper invoices, which are scanned into PDF. An Optical Character Recognition (OCR) system is used to interpret keywords from the invoices.
After the OCR interpretation and validation, all invoices are checked in an extra quality control. If the program finds any deviation, the invoices will be manually checked one more time.
The resulting XML invoice and original PDF are delivered to recipient’s Maventa account, from where the recipient’s ERP can fetch them. It is important that the recipient always checks the accuracy of scanned invoices.
Field | Field in e2b | Source | Validation | Comments |
---|---|---|---|---|
Invoice number | InvoiceNumber | Scanned | ||
Invoice date | InvoiceDate | Scanned | Valid date, not too old | |
Invoice due date | DueDate | Scanned | Valid date, not too old, not too far into the future | |
Currency | Currency | Scanned | Valid currency | |
Supplier Organisation number OR Supplier VAT number | Supplier/OrgNumber OR Supplier/VatId | Scanned | Valid format and modulus |
NO: Organisation number (for foreign suppliers VAT number is used in the OrgNumber field) SE: Organisation number and VAT number NL: KvK number and VAT number DK: CVR number FI: Organisation number (y-tunnus) and VAT number |
Supplier name | Supplier/Name | Searched from a list of companies | Searched from a list by organisation number. Not first time when invoice is passed, second time automatic.If name of the company can’t be found by search, organisation number will be shown as the name. If organisation number cannot be interpreted invoice will be passed with UNKNOWN_VENDOR as the supplier name. | |
Buyer Organisation number | Buyer/OrgNumber | Email address / Scanned | When an invoice is sent to scan service by email, the email address contains organisation number. For a paper invoice, organisation number is intepreted from the scan. If no organisation number or scan id (serial number) can be found, buyer's name will be used to find organisation number. | |
Gross amount (including VAT) | InvoiceSummary/InvoiceTotals/GrossAmount | Scanned | Gross amount should agree with VAT amount | |
Net amount (excluding VAT) | InvoiceSummary/InvoiceTotals/NetAmount | Calculated by Scan service | Calculated: Gross amount - VAT amount | |
VAT amount | InvoiceSummary/InvoiceTotals/VatTotalsAmount | Scanned | Gross amount should agree with VAT amount | |
VAT percent | InvoiceSummary/VatTotalsInfo/VatPercent | Calculated by Scan service | Calculated from Gross amount and VAT amount, and delivered without decimals.If there are products with different VAT percents on the invoice, the calculated VAT percent will be somewhere between the actual VAT percents. If there is a rounding amount on the invoice, it is not taken into account when calculating the VAT percent. | |
Invoice identification (debit/credit) | Reminders and other documents that are not invoices or credit notes are sent from Scan service to customers by email. | |||
Supplier IBAN number OR Supplier account number | Supplier/AccountInformation/IbanNumber OR Supplier/AccountInformation/AccountNumber | Scanned | Modulus checked for account numberValid IBAN |
NO: Account number, for foreign suppliers IBAN number is used in the AccountNumber field. SE: Account number (bank giro or post giro), for foreign suppliers IBAN number is used in the AccountNumber field NL: IBAN number DK: Both Account number and IBAN. If the account number is missing from the invoice, the last part of the FIK code is used. FI: IBAN number |
Payment reference or reference number / OCR number | Payment/KidNumber | Scanned | Modulus checked |
NO: KID SE: OCR number NL: Nothing DK: FIK code, all the numbers and signs FI: Viitenumero |
Their reference | InvoiceReferance/BuyersProjectCode | Scanned |
DK: Their reference and order number FI: Text in "Viitteenne" field SE,NO,NL: - |
|
Number of pages | AttachmentNoOfPages |
The standard delivery time is within 36 hours. Files are transmitted to company’s account every 15 minutes.
The scan account can be opened calling scan_account_order method or through the UI from company settings.
Before opening the scan account for a company, make sure company has the receiving setting turned on. Scanned invoices from the scanning service are delivered to the Maventa customer like any other incoming e-invoice and for this reason the invoice receiving must be on to enable scanning.
New scan account requests are processed every night. Scan account is opened and Scan ID number is created automatically by the Maventa based on the customer organisation number.
When opening the scanning service, customer needs to specify return e-mail address where all other material than invoices are delivered by the scanning service. Changes to company return address or other information can be made using scan_account_order method.
Company informs their suppliers about their scan address they have received when service is activated. Scan address contains the company’s scan ID number that is used to identify the recipient.
There are two ways suppliers can send invoices to the scanning service to be scanned; by e-mail or by post.
Finland, Sweden, Norway, Denmark and Netherlands
Requirements for sending
Finland, Sweden and Norway
Scan service identifies the recipient using following information found from the invoice image if invoice is sent by post:
Finland | Sweden | Norway | Denmark | Netherlands | |
---|---|---|---|---|---|
Scan ID | company business ID | company business ID | company business ID | CVR number |
VAT number or KvK number |
Email scan address |
invoice-BID@kollektor.fi e-mail address without “-“ in business identity code (e.g. invoice-12345678@kollektor.fi) |
BID@autoinvoice.se | BID@autoinvoice.no | CVRnumber@autoinvoice.dk |
KvKnumber@autoinvoice.nl or VATnumber@autoinvoice.nl Depending which one was used when the company was registered to Maventa |
Postal scan address |
Company name Scan ID PL 100 80020 Scan service |
Company name Scan ID Box 4 73721 FAGERSTA |
Company name Scan ID POSTBOKS 3261 7439 TRONDHEIM |
- | - |
Scan service delivers only invoices and credit notes electronically. When a customer opens the scan service they need to specify a scan return address that is used to deliver none invoice materials. Marketing materials are not delivered.
Delivered as e-invoices:
Delivered via e-mail:
Delivered via post:
Thrown away:
See your used price list for the relevant delivery prices.
End users can report interpretation errors by email to support@maventa.com. Support contacts the validation teams at scan service provider to use auto learning process, where interpretation is manually changed so that invoices are correctly interpreted the next time.
If there are problems on the invoice, users can also request rescanning.
Closing the service (disabling the scanning service) is done by calling API method scan_account_disable or via the UI’s scan account page.
After the scan account is closed in the Maventa, information is sent to the scanning service provider. Service provider receives closing requests every night. When the account is fully closed the scan e-mail address stops working. If some party still sends material to it they will receive an automatic reply that the e-mail address is no longer in use.
Material sent by post will be scanned and delivered to the recipient by e-mail (to the return e-mail address) for the next 60 days and after that everything is destroyed. The scanning service does not inform the senders that their paper invoices were not delivered. When closing a scan account, the company should inform their suppliers about the way the company will receive invoices from them in the future.
Receive data from different checks performed on the incoming invoices and companies. Use the data to improve purchase invoice handling and boost data-driven decision-making. For example give useful notifications to the users to improve fraud detection, supplier management and quality of bookings and payments.
Detect includes currently checks for sender business id,supplier activation to electronic invoicing, vat registration and warning list for fraud and suspicious companies. If you are interested please contact your Maventa integration contact point.
Maventa Connector is a simple Maventa client program for Windows. If your ERP does not have a direct Maventa integration but can create invoices as XML files, you can use Maventa Connector to send those invoices. More information available in Finnish at www.maventa.fi and our support portal.
Download maventa-connector-installer.exe
We do not recommend using old versions of Maventa Connector, please always use the latest available version. For special cases we keep some old versions available:
Download maventa_connector_installer_2018_04_26.exe
Download maventa_connector_installer_2018_04_11.exe
Connector’s security depends 100% on the OS security and folder privileges that it is running on. Connector client program moves documents between a folder and Maventa API using HTTPS same as all other ERP traffic. As the client program only makes API calls and copies files between API and folder and is triggered from the OS side there are no additional security aspects to consider as there are no incoming ports the software listens to. All local users that are given access to the filesystem that contain the configuration files can read the contents (API keys) thus the application should be protected from the OS side users using folder permissions. The program is using an old framework so software framework itself is outdated and this should be taken into consideration when thinking about using it.
Invoices can also be sent as an email invoices to the recipients. Email route is used as a secondary delivery route if invoice could not be sent as an e-invoice and if recipient e-mail address is available. Email invoice sending can also be forced or then disabled completely.
Email is the first fallback route that our automated routing tries when it cannot find a way to send the invoice as an e-invoice. Routing order is the following 1. as an e-invoice 2. as an email 3. through the print service. Email route can also be forced if the desired way to reach the receiver is email. This can for example be a case for consumer invoicing when the recipient doesn’t have a way to receive invoices electronically through netbank (Read more about consumer invoicing).
Email sending is by default enabled on all company accounts. If needed it can be disabled from company settings or then invoice by invoice in sending. More about the disabling here.
Email route is used when sending as an e-invoice is not possible. To be able to route invoice as an email the receiver’s email address needs to be present in the XML.
It is possible to force the invoice to be sent as an email by using invoice_put_invoice_with_metadata or POST /v1/invoices
methods for sending. In the metadata other routes are being set as disabled to force email route. Also the receiver’s email address can be given in the metadata. Email address given in the metadata will be used instead the one in the XML.
Forcing to email route is also possible with certain XML formats:
S-EDI: If OutputMedia is set as “PDF” only e-mail route is enabled
There are 3 choices from which the sender can choose how they want their e-mail invoices to be send out. These e-mail settings can be changed via UI or using configure_company or PATCH /v1/company/settings
API methods.
Selecting this option means that the invoice e-mail will contain a link to download the invoice from Maventa service. There is also a passcode on the email that the receiver needs to give behind the link to access the invoice. When the receiver clicks the link and open the invoice, the sender receives a notification e-mail.
Selecting this option means that all invoice e-mails will contain an image of the invoice in PDF format. Note that the total sizes of attached documents in an e-mail must be under 5 megabytes. If the attachments are larger, no attachments will be attached but instead the receiver needs to download using the provided link in the e-mail. Note! There will always be also the link to download because there might be some unexpected issues showing attachments and in this way we will ensure that the receiver will always get the attachments.
Virtual barcode is also added into the email body when sending invoice with image attached.
By selecting invoice objections, the receiver must accept the invoice before being able to view any payment information. Receiver can also choose to decline the invoice, with the option to notify sender the reason for the decline. When any changes occur to the invoice, for example, the receiver accepts the invoice, the sender receives a notification e-mail and the status in Maventa is updated accordingly.
Sender can define a message and define contact details that are shown in the email body either through API or via our UI. When using API use either configure_company method with giving the information in the parameters message_from_sender, contact_person, contact_email and contact_phone, or PATCH /v1/company/settings
.
Note! When you define a contact email address we will send a confirmation email to this email address where you need to confirm that the address may be used for that purpose.
Email language depends on the input format (XML) and how language is set there. We currently support the following languages: Finnish (FI), English (EN), Swedish (SE), Norwegian (NO), Danish (DK) and Dutch (NL). Not all are according to the ISO 639-1 codes but we hope to get support soon for at least SV, NN, NB and DA soon.
Click the XML your product is sending from the list below to see how the language of the email invoice is defined:
InvoiceRecipientLanguageCode
Fallback / default: FI
Finvoice also supports SV (Swedish) because Finvoice uses ISO 639 Language Codes e.g. FI, SV, to define the language. So both SV and SE will result the same, Swedish language.
Sender’s Maventa account country code (FI/SE/NO/DK/NL only, when AccountingCustomerParty/Party/PostalAddress/Country/IdentificationCode empty)
BuyerParty/Party/Address/Country/IdentificationCode (FI/SE/NO only) NOT WORKING CURRENTLY
Fallback / default: EN
Sender can specify how often a reminder email is sent if the invoice has not been accepted, declined or the link has not been opened by the receiver. This does not apply if the invoices are sent as attachments.
configure_company email_remind_freq or PATCH /v1/company/settings
“reminder_frequency”.
If you have defined a contact email that is used as the reply-to address for email invoices. If not defined the fallback is the user’s email address (either API user’s email or an email address from the XML if defined). If that does not exists, fallback is the company email address.
If the email bounces due to for example a non existing email account the invoice will go into error state. The sender will be notified by email as long as the email notifications are not disabled. Error is also returned through API when asking after status of the sent invoice.
Note that the invoice will not go into error state if the recipients email box is full, or if recipients email marks the email as spam. If you will be sending out an email invoice with big attachments it is good practise to contact the receiver afterwards and making sure they really received the invoice to their email box.
Email sending is by default enabled on all company accounts. You can either disable the whole email sending possibility from company settings or then disable it invoice by invoice in sending.
To disable the whole email invoice sending use configure_company API method and set parameter send_invoice_email to 0, or with REST API use PATCH /v1/company/settings
set “enabled” as false under the “send_invoice_email”. By choosing this setting the email route is skipped in automated routing.
To disable the email sending invoice by invoice use invoice_put_invoice_with_metadata or POST /v1/invoices
methods for sending and set the email route as disabled. This will skip the email route for that particular invoice. If you are using some other method for sending also leaving the receiver’s email address empty will cause the email route to be skipped.
The Embeddable User Interface (EUI) is Maventa user interface that can be embedded into the ERP. With EUI customers don’t need to visit any external webpage to access their Maventa account but instead they can access their Maventa related settings, activate additional services and view their invoice listings directly from inside the ERP system. EUI is highly customizable which means that every ERP using it can create their own look of it by hiding parts of it their customers don’t need.
By using EUI you have the possibility to skip part(s) of the API integration towards us and still provide your customers everything directly from your product.
What is still needed and highly recommended to be done by the ERP through a normal Maventa API integration:
Basically all the rest can be done via the EUI:
EUI is highly customisable and every ERP can create their own look and feel of it. You can decide what to show to your end customers through the EUI and what should be hidden from them. For example if there is no invoice receiving capabilities in the ERP, received invoices list can be hidden and as well all the invoice receiving related settings. Customised view will greatly improve the user experience by always provide only useful information to the end customers. Customisation of the EUI is a really cool feature.
Customisation can be done using the ERP profiles and optional setup parameters:
ERP profiles are the main way to customise the views and are created for each ERP using the EUI. Using profile in a call toward EUI will load the ERP specific view. ERP profiles are created and modified by Maventa team based on the ERP’s needs and requirements. So before you start to build the integration towards the EUI, please contact Maventa support and ask for an EUI profile. One ERP can have multiple profiles. For example one for each version of the system or if you have different customer groups and would like to show them different content based on what functionalities they have in use.
...&profile=name_of_the_profile
When we add something big to the EUI for example a new service or functionality we will always contact all the EUI ERPs if they wish to have that new service visible also to their customers. Using EUI comes really handy by reducing the time to market of new services. Of course it is good to keep in mind that some of the new services might also require some changes from the ERP side or to the API integration but some services work just fine only through the EUI.
Profiles are great way of setting up the EUI look and feel, but if you want to have further control use the EUI setup parameters. EUI setup parameters have the same structure as the profiles and those can be used in combination with a profile. EUI setup params will override any setting from the profile so if you want to have a bit different views for one specific customer you can do it by using setup parameters. Empty values for any EUI setup parameter, equals false.
Let’s say that you have few customers that do not receive invoices through your ERP at all and you want to provide them a different view than for the rest of your customer by hiding all that is related to the invoices receiving:
EUI setup parameters will look like:
...&setup[sections][invoices][inbound]=false
&setup[sections][settings][invoice][receiving]=false
Here is a list of setup parameters you can use to hide or show parts of the EUI. If you wish to hide or show something that is not on this list please contact us and we will see if can fulfill your request.
With direct URLs customers can be redirected straight to the page you want. In the part of the ERP where invoices are handled could be a direct link to the invoices list of the EUI. And in the part where there are all the setting there could be a link to open up a settings page of the EUI.
First you should think a bit what do you want your end customers to see. What parts of the EUI they need? And then decide how to show those views. Should you add one button to open up the whole EUI and let customers navigate themselves to the page they need or should you show different views in different parts of the ERP depending on the context (Settings view embedded into the part which shows ERP’s settings, and invoices lists where there are invoices listed on the ERP)?
Read more about the customisation of the EUI. Our team is happy to assist you in deciding what would be the best fit for your ERP. If you want help in deciding or if you have made some decisions youself contact Maventa support and ask for an EUI ERP profile. We will then set up you profile based on your preferences.
Then you should choose how to embed. We currently host the EUI under 3 different domains:
If you want to embed EUI using iframe technique into your product that is already running in the user’s browser there are most likely difficulties when it comes to the loading of cross-domain content. There are solutions to overcome this issue but we need to have discussion about it to decide together what is the best approach for your product.
Implement the authentication
Authentication and access to the EUI is done using token based login (based on company_uuid, user_api_key and vendor_api_key).
The endpoints for the process are the following:
Testing | Production | |
---|---|---|
Endpoint for getting the token | https://ax-stage.maventa.com/oauth2/token | https://ax.maventa.com/oauth2/token |
Endpoint for initiating a new EUI session | https://autointerface-embeddable-stage.maventa.com/authentication/token | https://autointerface-embeddable.maventa.com/authentication/token |
Endpoint for renewing the token | https://autointerface-embeddable-stage.maventa.com/authentication/renew | https://autointerface-embeddable.maventa.com/authentication/renew |
The token to open EUI is fetched using the AX Oauth2 endpoint using the following parameters
Parameter | Desciption | Value/example |
---|---|---|
vendor_api_key | The vendor API key for the ERP | 37fc1ebc-dd4f-11ea-87d0-0242ac130003 |
scope | The scope that is needed, eui is required | eui |
grant_type | The OAuth2 grant type | client_credential |
client_secret | company_uuid | 32d74434-dd4f-11ea-87d0-0242ac130003 |
client_id | user_api_key | 298c6ce2-dd4f-11ea-87d0-0242ac130003 |
curl -X POST "https://ax-stage.maventa.com/oauth2/token"
-H "accept: application/json"
-H "Content-Type: multipart/form-data"
-F "grant_type=client_credentials"
-F "client_id=company_uuid"
-F "client_secret=user_api_key"
-F "scope=eui"
-F "vendor_api_key=erp_vendor_api_key"
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudG......",
"token_type": "bearer",
"expires_in": 3600,
"scope": "eui"
}
While the user’s EUI session is active you need to act when the token is about to expire. The expires_in attribute in the token response tells how long the access token is valid. To be sure deduct a few minutes from the time to not run into issues. It’s important to stop the renewal process if the user closes the EUI session or the user have logged out in some other way.
The provided token in the initial request will be valid for one hour and if the token is not renewed the users session will end when the token expires. This means if the user has the EUI open for over one hour the session will be unusable and needs to be restarted with a new authentication. To prevent this the token can be updated for the user in the background without the user noticing anything (Step 4). To be able to renew the token the first thing to do is to pass a unique ID as the session id for each authentication that is initiated, this to be able to associate to the session on renewal. The unique ID is given in the session_id parameter on the initial authentication request (see the step 3).
token = fetch_token
setTimeout(function(){
if(user_session_active()) {
renew_token();
} else {
// user has closed the EUI window
}
}, token.expires_in - 60*5);
When you have a token you are ready to open EUI in a browser window.
Depending on the browser component capabilities it varies a little how the EUI session can be initiated. The token can be put in either the POST body or in the Authorization header as a Bearer token.
Parameter | Desciption | Value/example |
---|---|---|
token | access_token property from the OAuth2 response | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…. |
profile | Each ERP using the EUI will have their own (profile) for customisation | my_erp_profile_name |
locale | For defining language of the EUI (fi,se,no,dk,nl) | no |
redirect_to | What page to open. List of (direct URLs) | /invoices |
session_id | Define a session id. We prefer UUID | erp_users_session_id |
curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/token"
-H "Content-Type: multipart/form-data"
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9......"
-F "profile=my_erp_profile_name"
-F "locale=no"
-F "redirect_to=/invoices"
-F "session_id=erp_users_session_id"
<!DOCTYPE html>
<html>
<head></head>
<body>
<form action="https://autointerface-embeddable-stage.maventa.com/authentication/token" method="POST" target="_blank">
<fieldset>
<legend>Authentication using token</legend>
<br/>
<label>token:</label>
<input type="text" name="token" size="100" />
<br/>
<label>session_id:</label>
<input type="text" name="session_id" size="70" />
<br/>
<label>redirect_to:</label>
<input type="text" name="redirect_to" size="70" />
<br/>
<label>profile:</label>
<input type="text" name="profile" size="40" />
<br/>
<br/>
<input type="submit" value="Log in"/>
</fieldset>
</form>
</body>
When the token is about to expire a new token needs to be obtained exactly the same way as in (Step 1).
The token then needs to be passed to the renew endpoint in EUI, combined with the session_id generated in the initial request. If you are able to extract/use the session cookie from the browser component it’s possible to use that when renewing the token, then there is no need to pass and use the session_id.
curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/renew"
-H "Content-Type: multipart/form-data"
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6InVzZXIiLCJ1c......"
-F "session_id=erp_users_session_id"
function start_user_session(session_id, token) {
monitor_session_token(session_id, token.access_token); // Start waiting for the token to expire
open_browser_window(session_id, token.access_token); // Open browser component with the token
}
function monitor_session_token(session_id, token) {
setTimeout(function(){
if(user_session_active(session_id)) {
renew_token(session_id);
} else {
// user has closed the EUI window
}
}, token.expires_in - 60*5);
}
function renew_token(session_id) {
token = fetch_token();
if(post_new_token_to_eui(session_id, token.access_token) == 200) {
monitor_session_token(session_id, token);
}
}
token = fetch_token(); // Fetch token from AX
session_id = generate_uuid(); // Generate an ID for future reference
start_user_sesion(session_id, token);
API to use: REST API
Maventa enables sending and receiving electronic order documents through PEPPOL network. The document types supported include orders, order responses, catalogues, catalogue responses and dispatch notes.
Partner and Maventa agree about the way the end customers (users of partner’s software) are invoiced for their transactions and use of Maventa services.
Billing is transaction based. All transactions are billed based on the partner vendor_api_key that is provided on the API calls or in some cases stored in the company details. Based on the vendor_api_key setting the transactions can be billed from the key owner (partner) or from the end customer directly.
Billing is partner specific meaning that same transaction is only billed once from a partner and you can refetch invoices to same partner’s other systems without additional cost. If a customer receives invoices into different partners’ products, i.e. uses multiple ERPs from different partners to receive invoices at the same time, each partner will be billed separately for the invoice they have received into their system.
All Maventa invoices are attached with a transaction report that contains all the transacations that are billed in the invoice.
The transaction report contains the following information of the transactions
Header | Value |
---|---|
BillingCompanyID | unique identifier of the invoiced company in Maventa billing system |
BillingCompanyName | name of the invoiced company in Maventa billing system |
BillingCompanyOrganizationIdentifier | business ID of the invoiced company in Maventa billing system |
TargetCompanyID | unique identifier of the company who has performed the transaction |
TargetCompanyName | name of the company who has performed the transaction |
TargetCompanyOrganizationIdentifier | business ID of the company who has performed the transaction |
MaventaProduct | name of the transaction |
DimensionItemSoftware | name of the software used to perform the transaction |
PrintPageCount | number of printed pages within the transaction (for print transactions only) |
ScanPageCount | number of scanned pages (for scanned transactions only) |
BatchItemCount | number of transactions (for all other transactions types than print and scan) |
ActionOriginTime | time when transaction was performed |
InvoiceNumber | description of transaction |
ProductUnitNetFullPrice | unit price of transaction |
LineNetSum | total line amount |
See example transaction report:
Note that the structure of this report is based on a real life example, but the data in the report is made-up.