Skip to main content

Posti SmartShip API

Project description

Python library to interact with the Posti SmartShip / Unifaun Online API.


  • Docs

  • Implement remaining attributes in Shipment as per schema

  • Add logging where necessary


  • Python 2.7+ or Python 3.4+


Creating shipments

This API supports the Smartship Shipments api for creating shipments and then downloading the generated PDF’s.


There are methods for certain carriers like Posti to cover more common use cases. To create a shipment for the Posti carrier, for example:

from smartship.carriers.posti import create_shipment
receiver = {
    "name": "Anders Innovations",
    "city": "Helsinki",
    "country": "FI",
    "address1": "Iso Roobertinkatu 20-22",
    "zipcode": "00120"
sender = {
    "quickId": "1",
agent = {
    "quickId": "2",
shipment = create_shipment(
    "12345",  # Posti customer number
    "PO2102",  # Service ID
    [{"copies": 1}],  # Parcels
    agent=agent,  # Optional pickup point
    pdf_config=pdf_config,  # Optional custom PDF config

See more documentation in smartship.carriers.posti module.

PDF Config

If you want to pass a custom pdf_config, it should have the following structure:

"target1Media": "laser-a5",
"target1YOffset": 0,
"target1XOffset": 0

With "target1Media" being one of the following options:


You can customize the offset with "target1YOffset" and "target1XOffset" parameters.


To send shipments and use other API resources, you need a client. Initialize the client as follows with username and secret tokens. Create your API tokens in the Unifaun Online portal.

from smartship import Client
client = Client("username", "secret")

Sending shipments

Send a shipment as follows:

response = client.send_shipment(shipment)

Response will be a special ShipmentResponse wrapping a HttpResponse object with response code and JSON content in

Status codes:

  • 201 - Shipment was created OK

  • 422 - Validation error with the data. Raises a ShipmentResponseError.

For errors see error.response.json() for details from Unifaun Online API.

Shipment address PDF slips

Once you have the response retrieve associated PDF data as follows:

data = response.get_pdfs(client)  # Client needed in case of additional fetching
pdf_data = data[0][0]  # Simplest case with a single shipment with a single parcel


Retrieve a list of agents (pickup points) as follows:

agents = client.get_agents("FI", "ITELLASP", "Iso Roobertinkatu 20-22", "00120")

Response will be an Agents object that can be iterated over for individual agent data.


As the above agents method is a paid service we also provide an interface to the Posti location service API.

from smartship.carriers.posti import get_locations
locations = get_locations(country_code="FI", zipcode="00120")

Response will be a Locations object that can be iterated over for individual location data.

Advanced usage

See full Smartship API documentation for a full list of attributes that shipments can be given. All of these are supported when using smartship.shipments.Shipment directly. Import the relevant objects from smartship.objects and pass them to the Shipment object.



Install the requirements to a virtual environment with:

pip install -U setuptools pip  # These should be up to date
pip install -r requirements-dev.txt


To test in the current virtual environment, run:


To check the coding style, run:


To test all supported environments, run:


Building documentation

Build the documentation with:

sphinx-build -b html docs docs/_build

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

smartship-2.0.0.tar.gz (17.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page