smartship 2.0.0
Posti SmartShip API
License: MIT
Keywords: smartship,posti

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:

.. code:: python

    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:

.. code:: python

    {
    "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
<https://www.unifaunonline.com/>`_.

.. code:: python

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

Sending shipments
'''''''''''''''''

Send a shipment as follows:

.. code:: python

    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:

.. code:: python

    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:

.. code:: python

    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.

.. code:: python

    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
<https://smartship.unifaun.com/rs-docs/>`_ 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