Posti & Smartposti API

Globe Pickup Points integrates with Posti (Finland) and Smartposti (Estonia, Latvia and Lithuania) through the OmaPosti Pro API v2. With this integration, you can:

• Export orders to Posti directly from Shopify
• Print shipping labels within Shopify, in 10 × 15 cm or another Posti label size, or as A5 labels two to an A4 sheet
• Ship to Posti pickup points and parcel lockers in Finland and to Smartposti points in Estonia, Latvia and Lithuania
• Ship to the customer’s address in Finland, Estonia, Latvia and Lithuania by Home Parcel or Express Parcel
• Track parcels on Posti’s and Smartposti’s tracking pages

Beta

The Posti and Smartposti integration is in beta. It is new in Globe: if a label does not come out right, use Contact support on the integration’s page in Globe, or write to help@appfleece.com.

---

Enabling Posti & Smartposti API integration

You need:

• A Posti logistics contract. Its number usually has six digits and starts with 6. OmaPosti Pro shows it under User settings, My organizations, Customer numbers & contracts.
• An application account user in the Posti developer portal (developer.posti.com), with the API role shippingapi and your logistics contract number. Globe uses its client ID and secret.
• The API Manager role in OmaPosti Pro, to log in to the developer portal. Ask Posti for it if you do not have it.

1. In your Shopify admin, open Globe Pickup Points and navigate to Shipping labels. Click Add carrier and select Posti (Smartposti).

2. Enter the Client ID and Client secret of your application account user from the developer portal (Application account users).

3. Enter your Logistics contract number. The API user must have the same number.

4. Select Orders without a pickup point (AUTO): what the AUTO product does when the customer chose no pickup point.

   • Home Parcel 2104 to the address (the default)
   • Postal Parcel 2103 to the point nearest the address

   Orders with a Posti or Smartposti point always go to that point.

5. Select the Label size. Posti makes the label in this size when it is created:

   • Label printer, 10 × 15 cm (the default)
   • Label printer, 107 × 165 mm
   • Label printer, 107 × 225 mm
   • Label printer, 107 × 251 mm
   • A5, office printer

   A service without the chosen size gets an A5 label. Labels created earlier keep their size.

6. Select the Sender country, the country you ship from: Finland, Estonia, Latvia or Lithuania.

7. Fill in the sender address as it appears on the label:

   • Sender company name and Sender name: fill in the company, the name or both. With both, the name goes to Posti as the contact person.
   • Sender street, Sender ZIP and Sender city. The postcode has 5 digits, or 4 in Latvia; a country prefix such as FI- is removed.
   • Sender phone and Sender email are optional.

8. Optionally, click Show advanced settings and set a Default weight (kg), used when an order has no weight.

9. Configure fulfillment and tagging options as needed:

   • Automatically fulfill orders: Never, Yes, send order shipped email with the tracking number or Yes, do not send order shipped email. When enabled, the order is fulfilled after export with the Posti parcel number, Posti as the carrier and a link to the tracking page.
   • Automatically tag orders with tracking number adds the parcel number as an order tag.
   • Custom tag after export adds your own tag after every successful export.

10. Map your Shopify shipping methods for Finland, Estonia, Latvia and Lithuania to a Posti product. The mapping is optional. You can change the product for each order when you create the label.

---

Products

Product in Globe	Delivery
Posti (pickup point or parcel locker if selected, otherwise as set for orders without a point)	To the Posti or Smartposti point the customer picked in checkout, by Postal Parcel (PO2103). Without a point, as Orders without a pickup point (AUTO) says: Home Parcel (PO2104) to the address, or Postal Parcel to the point nearest the address. Also used when no product is set.
Posti Postal Parcel 2103 / Smartposti parcel locker (selected point, else the one nearest the address)	Postal Parcel (PO2103) to the point the customer picked. Without a point, Posti takes the parcel to the point nearest the customer’s address.
Posti Home Parcel 2104 (address)	Home Parcel (PO2104) to the customer’s address, also when the order has a pickup point.
Posti Express Parcel 2102 (address, business delivery)	Express Parcel (PO2102) to the customer’s address, also when the order has a pickup point.

Postal Parcel PO2103 is also the service for Smartposti points in Estonia, Latvia and Lithuania.

Globe sends parcels to Finland, Estonia, Latvia and Lithuania. An order to another country is not exported. Orders to Åland are refused too: create those labels in OmaPosti Pro.

Every product takes parcels up to 25 kg and needs the customer’s mobile number for Posti’s arrival notice.

---

Exporting and printing labels

You can export orders to Posti and print shipping labels directly from Shopify, either in bulk or individually. For the label workflow itself, see Creating shipping labels.

OmaPosti Pro API v2 has no test environment: every label Globe creates is a real Posti shipment. Globe does not order a pickup from Posti.

Before the first order of a batch, Globe logs in to Posti and checks that your credentials may create shipments. If they may not, no order of the batch is sent.

Exporting an order creates one Posti shipment with one parcel. Posti returns the label with the shipment and assigns the parcel number, which is the tracking number. The Shopify order name is sent as the shipment reference, up to 35 characters.

The customer’s name, street, postcode, city and mobile number are required, also for a point parcel. Postcodes have 5 digits in Finland, Estonia and Lithuania and 4 in Latvia. Globe shortens names to 105 characters and the street and city to 50. The customer’s e-mail address is sent when the order has one.

The parcel weight comes from the order. If the order has no weight, the Default weight (kg) is used. If neither is set, the parcel is sent without a weight. Posti takes parcels up to 25 kg.

Parcels are tracked on the page of the destination country:

Destination	Tracking link
Finland	https://www.posti.fi/en/tracking/<parcel number>
Estonia	https://www.smartposti.ee/en/tracking/<parcel number>
Latvia	https://www.smartposti.lv/en/tracking/<parcel number>
Lithuania	https://www.smartposti.lt/en/tracking/<parcel number>

If Globe cannot tell whether Posti created a shipment, for example because Posti did not answer in time, the error asks you to check OmaPosti Pro (pro.posti.fi) before you create the label again. After a time-out or a broken connection, Globe also stops before the next order of the batch. The orders it did not send can be exported again safely.

The OmaPosti Pro API has no cancel call, so Globe does not cancel Posti shipments. Creating the label for the same order again creates a second shipment.

The integration does not sync delivery statuses back to Shopify.

---

Pickup points

Globe sends the point’s id from Posti’s Pickup Point API, for example 023243210, to Posti. The customer selects the point at checkout; to offer Posti points, see Adding pickup point carriers. Posti prints the point’s address on the label under the customer’s name. The customer’s own address and phone stay on the shipment.

Globe accepts points of the Posti pickup point network in Finland, Estonia, Latvia and Lithuania: Posti pickup points and parcel lockers in Finland and Smartposti points in the Baltics. The Posti point list also has points in Åland and Bring points in Sweden and Denmark. Globe does not create Posti labels for them.

An order with a point from another carrier’s network is not exported with the AUTO or Postal Parcel product. It is never shipped to the customer’s address instead. Choose a Posti point with the Modify pickup point action, or use Posti Home Parcel 2104 (address).

Home Parcel and Express Parcel go to the customer’s address and ignore a point on the order.

---

Label printing

Posti labels can be printed in the following formats:

Format	Labels
Label size from the Posti settings	Each label in the Label size that was set when it was created
A4, two A5 labels per page (A5 label size)	Two A5 labels per A4 sheet, at their own size. Labels of another size print as they are

With A4, two A5 labels per page (A5 label size), you can select the starting position on the sheet (positions 1–2) to reuse a half-used sheet.

Labels for several orders are combined into one PDF. Posti’s label link works for one hour only, so Globe stores the label when it creates the shipment and prints from that copy; you can print a label again at any time. If Globe has no stored label for one of the selected parcels, it prints none of them and names the parcel. Print that label in OmaPosti Pro.

---

Troubleshooting

Issue	Resolution
Posti settings are incomplete: …	The message lists the missing settings. Fill them in the carrier settings. A Latvian Sender ZIP has 4 digits, the others 5.
Posti did not accept the client ID and secret	Check the Client ID and Client secret. They are the credentials of your application account user in the Posti developer portal (developer.posti.com).
Your Posti credentials cannot create shipments: they lack the API role "shippingapi"	In the Posti developer portal, open Application account users and give the user the API role shippingapi and your logistics contract number, or create a new user with both.
Posti refused access to the shipping API (HTTP …)	Check that the API user has the API role shippingapi and the same Logistics contract number as the settings.
Posti login failed (HTTP …) or Globe could not reach the Posti login	Nothing was created. Try again in a minute.
… is not a Posti or Smartposti point or Wrong carrier for this order	Choose a Posti point with the Modify pickup point action, or use Posti Home Parcel 2104 (address).
the Posti point "…" has no point id on the order	Choose the point again with the Modify pickup point action, or use Home Parcel.
Globe sends Posti parcels to points in Finland, Estonia, Latvia and Lithuania, and "…" is in …	The point is in Åland, Sweden or Denmark. Choose a point in Finland or the Baltics with the Modify pickup point action, or ship the order with another carrier.
Globe sends Posti parcels within Finland, Estonia, Latvia and Lithuania, and the shipping address is in …	Ship the order with another carrier.
Globe does not send Posti parcels to Åland …	Create this label in OmaPosti Pro.
unknown Posti product "…"	Choose one of the Posti products in the label panel or in the shipping-method mapping.
Order … has no phone number or Recipient phone number is missing	Add the customer’s mobile number to the order, with the country code. Posti needs it for every product.
Posti cannot use the receiver's phone number …	Correct the phone on the order, with the country code, for example +358 40 123 4567, and create the label again.
the shipping address has no name or company	Add the customer’s name to the shipping address.
the shipping address has no …	Add the missing street, postcode, city or country in Shopify. Postcodes have 5 digits, or 4 in Latvia.
Order … weighs … kg. Posti takes parcels up to 25 kg	If the weight is wrong, correct Shipment weight (kg) in the label panel. Otherwise ship the order with another carrier.
… has no cash on delivery	Set the COD amount in the label panel to 0 if the order is already paid.
Posti did not accept order …: …	The message gives Posti’s reason. Correct the order or the settings and create the label again.
Globe could not connect to Posti (…), so nothing was created for order …	Nothing was created. Try again in a minute.
Posti did not answer in time …, The connection to Posti broke off … or Posti did not confirm the shipment for order …	The shipment may exist. Check OmaPosti Pro (pro.posti.fi) before you create the label again.
Posti accepted a shipment for order … but Globe could not read its parcel number	Do not create the label again. Find the shipment in OmaPosti Pro and print its label there.
Posti created parcel … but sent no label Globe could print or … but Globe could not save it	Do not create the label again. Print the label for that parcel in OmaPosti Pro.
Globe stopped before sending order … to Posti	Nothing was created for this order. Create its label again once the cause named in the message is fixed.
No stored Posti label for parcel …	Print the label in OmaPosti Pro (pro.posti.fi).
Error printing Posti labels	Try again. If it fails again, use Contact support on the integration’s page.