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.

User account opening

To use the Mass printing API, you need a dedicated user account. Create one by calling the registration endpoint with your existing sw_api_key and company_uuid from Maventa:

• Production: https://payslip.maventa.com/register
• Staging: 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 letters

To send a letter to Mass printing service there are currently two supported methods:

1. New JSON-based API (recommended) - https://payslip.maventa.com/input_json
2. Legacy IPOSTXML-based method (deprecated - will be removed in future) - https://payslip.maventa.com/input_public

JSON API (recommended)

The POST /input_json endpoint allows authenticated users to send PDF files for print delivery services. This endpoint accepts multipart form data containing a PDF file and associated metadata for both recipient and sender information.

Authentication for JSON API

The endpoint supports multiple authentication methods for backwards compatibility:

Method 1: Bearer token authentication (recommended)

Header Required:

• Authorization: Bearer {user_api_key}
• X-Client-Id: company_uuid

Method 2: Legacy API key authentication (deprecated)

Headers Required:

• HTTP_USER_API_KEY: user_api_key
• HTTP_COMPANY_UUID: company_uuid

Method 3: Legacy username/password authentication (deprecated)

Headers Required:

• HTTP_USERNAME: Your username
• HTTP_USERPW: Your password

Sending with JSON API

• Method: POST
• Content-type: multipart/form-data
• URL: /input_json

Required parameters

Recipient information (required)

Optional parameters

Optional sender information (required for digital post send)

Optional recipient information (used for digital post lookups for better matching)

Printing options

Licensing parameters

Response codes and values for sending

Success response for sending

• Status code: 201 Created
• Body: UUIDof newly created printable letter

Error responses for sending

Example requests for sending

Using Bearer Token Authentication (Recommended)

curl -X POST "https://payslip-stage.maventa.com/input_json" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Client-Id: your_company_uuid_here" \
  -F "pdf=@document.pdf" \
  -F "hash=a1b2c3d4e5f6789..." \
  -F "version=MyERP 1.25" \
  -F "sw_api_key=your_sw_api_key_here" \
  -F "recipient[name]=Essi Esimerkki" \
  -F "recipient[address]=Kotikatu 123" \
  -F "recipient[post_code]=00100" \
  -F "recipient[post_office]=Helsinki" \
  -F "recipient[country]=FI" \
  -F "sender[name]=Tulostaja Oy Ab" \
  -F "sender[sender_id]=00371234567890" \
  -F "duplex=true" \
  -F "color_print=false" \
  -F "letter_class=economy"

GET /file_status/:id API Endpoint

The /file_status/:id endpoint allows authenticated users to check the processing status of a specific payslip using its UUID. The endpoint supports the same authentication methods as the /input_json endpoint described above.

• Method: GET
• URL: /file_status/{payslip_uuid}

Response codes and values for status call

Success response for status call

• Status code: 200 OK
• Body: Status string indicating current processing state

Possible status values for status call

Error response for status call

Example requests for status call

curl -X GET "https://payslip-stage.maventa.com/file_status/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Client-Id: your_company_uuid_here"

IPOSTXML-based API (deprecated)

Authentication for IPOSTXML-based API

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

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

POST parameters for IPOSTXML-based API

Response for sending with IPOSTXML-based API

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 ratio)
• 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>

Checking the status of sent packages for IPOSTXML-based API

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

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: 2-bit colours (black and white only), not grayscale.
• Colour print: Black text should be in black, not 4-colour
• Colour print: All colours 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.

Storage time

Once Maventa receives final confirmation from the print service provider, the file is completely removed from Maventa’s servers. 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 is often minimal. Regional delivery schedules can have more impact on delivery timing than the letter class itself. Priority may still benefit B2B invoicing, but for consumer invoices, the recipient’s local delivery schedule is usually the deciding 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, the invoice will be redirected to the receiver’s OmaPosti account instead of being delivered as a physical letter. To determine if a receiver has an OmaPosti account, a combination of consumer’s 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.

For the OmaPosti route to function, the necessary information must be provided as an API parameter (or in the IPOSTXML document). This includes the sender’s OVT code and the receiver’s name and address.

Kivra delivery

Kivra is a digital mailbox service where consumers choose to receive their letters and documents electronically. When a recipient has a Kivra account, they have actively opted in to digital delivery. Delivering to Kivra reduces printing and postage costs while reaching recipients in their preferred channel.

How it works

Before a letter is handed over to the print provider, Maventa performs an automatic lookup against the Kivra consumer registry using the recipient’s information. If a match is found, the letter is delivered to the recipient’s Kivra inbox instead of being printed and mailed. If no match is found, delivery falls through to the normal print route — no changes needed on your end.

Kivra has a maximum PDF size limit of 15 MB. If the letter exceeds this limit, it falls through to the normal print route automatically.

The lookup is performed using the following recipient data (in priority order):

1. Social security number (SSN)
2. Email address
3. Full name + street address + postal code + post office
4. Full name + phone number

Unlike OmaPosti, Kivra does not require the sender’s OVT code. The Kivra sender account (tenant) is based on the company’s business ID (BID), so no OVT information needs to be included in the API call for Kivra delivery.

Automatic sender setup

Each company can have only one sender account (tenant) in Kivra. The tenant represents the company as a recognised sender, and its name is what recipients see in their Kivra inbox.

If a tenant does not already exist for the company, Maventa automatically creates one when the company’s first letter is delivered via Kivra — no action is required. Maventa sets the tenant name based on the company’s official name from the YTJ registry at the time the company was created in Maventa.

If another service provider has already created a tenant for the company in Kivra, that existing tenant and its name are used. To update the tenant name, contact Kivra directly.

Custom letter subject

You can customise the letter subject that the recipient sees in their Kivra inbox using the letter_subject parameter. By default, the subject is “Kirje lähettäjältä [company name]”.

Opting out of Kivra delivery

To force physical delivery for a specific letter — for example, when a guaranteed paper trail is required — set the prevent_digital_post parameter to true in the API call. This opts out of both Kivra and OmaPosti delivery for that letter.

Billing

Kivra deliveries are billed as consumer invoices. The billing action name is EINVOICE_KIVRA_FI.

User account closing

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