SmartShip API

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

TODO

• Docs
• Implement remaining attributes in Shipment as per schema
• Add logging where necessary

Compatibility

• Python 2.7+ or Python 3.4+

Usage

Creating shipments

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

Carriers

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.

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:

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

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

Client

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

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

Agents

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.

Locations

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.

Development

Requirements

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

Tests

To test in the current virtual environment, run:

py.test

To check the coding style, run:

flake8

To test all supported environments, run:

tox

Building documentation

Build the documentation with:

sphinx-build -b html docs docs/_build