Mass Printing Service

The Maventa Mass Printing Service, also referred to as Payslip, allows sending PDF files as physical letters through the Finnish printing service. While originally designed for distributing payslips, it can be used for sending any type of letters, provided the printing service rules are followed. This service is available only for Finnish companies.

Note: Invoices intended for print should always be sent via the standard invoice delivery channels, not through this service.

User account opening

To use the Mass printing API, you need a dedicated user account. This account can be created with an API call to https://payslip.maventa.com/register, using your existing vendor_api_key and company_uuid from Maventa. Testing endpoint https://payslip-stage.maventa.com/register.

Request for registering

Response for registering

The response code will always be a HTTP 200 and the response body is one of the following:

Sending

To send a letter to Mass printing service call the API endpoint https://payslip.maventa.com/input_public.

Headers for sending

You need to give authentication using HTTP headers. You can give either:

• USERNAME and USERPW with which you registered your Mass printing API account
• COMPANY-UUID and USER-API-KEY of your Maventa account

POST parameters for sending

Response for sending

The response code will be a HTTP 200 and the response body is one of the following or “401 Unauthorized” if authentication fails:

Zip file content

PDFs

• One zip file can contain multiple PDF files but only one letter per PDF file. One letter can have multiple pages.
• Each PDF must be accompanied with iPost-XML metadata file (iPost LetterBundle format version 0.4). Note! information given in IPost-XML overrides the API parameters. You can download a zip file containing iPost-XML v0.4 implementation guidelines
• One iPost-XML should only have reference to one PDF letter (iPost-XML to PDF 1-1 ration)
• Page count on the iPost-XML (pages element) must match to the actual page count of the PDF
• We prefer that one zip file contains only one letter (one PDF file) + iPost-XML metadata file
• When multiple IPost-XMLs in one ZIP file, all IPost-XMLs must have the same printing options (letter class, colour..)
• Always use unique hash for each zip file. zipHash and hash values can be the same since one ZIP file can contain multiple PDF files
• Zip file max size is 1 GB

<?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="Your company Oy" contact="" contactPerson="Support" email="support@support.com" phoneNumber="010-5058474" ovtID="003712345678">
        <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>

Technical restrictions of the PDF

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.

• Keep the top and right margins empty
• Do not send any invoice image or attachment with black/dark background
• No transparencies
• All fonts must be embedded (subset or complete)
• All images must be in 250-300dpi. Higher resolution produces little or no quality gain. Lower resolution gives poor quality.
• Text should be stored as text (not bitmap)
• Recommended size per page is 1024kB, smaller the better
• Black / White print: 2bit colors (black and white only), not grayscale.
• Color print: Black text should be in black, not like 4 color
• Color print: All colors must be CMYK
• PDF page size needs to be A4 (210 x 297 millimeters)

Instructions for letter layout

Your PDF letter needs to follow these PDF layout rules by Posti. Addition to Posti as the mail distributor, there is also Jakeluyhtiö Suomi Oy (JYS) which have few additions to the Posti rules. Difference is the tracking barcodes they print on the invoice image, see the JYS rules merged with the Posti ones.

Receiver information should be marked as clearly as possible to make sure machine readability.

Envelope size

The Finnish printing service uses two envelope sizes:

• For invoices of up to 9 sheets, a smaller C5 envelope is used.
• For invoices exceeding 9 sheets, a larger and more expensive C4 envelope is used.

Since all invoices are printed double-sided, an invoice must have more than 18 pages before it exceeds 9 sheets and requires the C4 envelope.

Note: If the sender’s own invoice image is used without coversheet the cover sheet added by Maventa is counted as one page.

Checking the status of sent packages

To check the status of the sent package, use https://payslip.maventa.com/file_status.

Headers for checking the file status

You need to give authentication using HTTP headers. You can give either:

• USERNAME and USERPW with which you registered your Mass printing API account
• COMPANY-UUID and USER-API-KEY of your Maventa account

GET parameter for checking the file status

Response for checking the file status

Storage time

Once the file is successfully sent and we have gotten the final confirmation back from the print service provider, the file is completely remove from Maventa. We recommend storing the files on the ERP side for at least a few months after the sending in case there are some support cases related to the sent letters.

Delivery schedule

Letters that are sent to Maventa before 24:00 will get printed, processed and enveloped overnight and handed over to the mail distributor the following morning. Production does not take place during the weekends and holidays.

Delivery depends on the selected letter class. For Finnish companies sending domestic letters, there are two options: Priority and Economy.

For Finnish domestic letters, the practical difference between Priority and Economy classes is nowadays often minimal due to regional delivery schedules. these can have more impact on when the recipient receives the invoice than the selected letter class. Priority may still provide benefits for business-to-business invoices, but for consumer invoices, the recipient’s delivery schedule is usually the main factor.

For international letters, only priority is available.

OmaPosti delivery

OmaPosti is an application that allows customers to receive their letters electronically instead of in paper form. When a receiver has an active OmaPosti account and has not opted out of receiving digital letters from a specific sender (based on the sender’s ovtID given in the IPOSTXML), the invoice will be redirected to the receiver’s OmaPosti account instead of being delivered as a paper document. To determine if a receiver has an OmaPosti account, a combination of their name and postal address is used for identification.

It is also possible for the sender to exclude the letter from being sent through the OmaPosti route by setting the prevent_digital_post parameter to true in the sending API call.

Please note that in order for the OmaPosti route to function, the necessary information must be specified in the IPOSTXML document. This includes the sender’s OVT code (ovtID) and the receiver’s name and address information.

User account closing

If you wish to close the service please contact Maventa support.