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+

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
    receiver,
    sender,
    [{"copies": 1}],  # Parcels
    agent=agent,  # Optional pickup point
    pdf_config=pdf_config,  # Optional custom PDF config
 )

See more documentation in smartship.carriers.posti module.

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:

"laser-a5"
"laser-2a5"
"laser-ste"
"thermo-se"
"thermo-225"

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")

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 response.data.

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.

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.

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:

py.test

To check the coding style, run:

flake8

To test all supported environments, run:

tox

Build the documentation with:

sphinx-build -b html docs docs/_build