Metadata-Version: 1.2
Name: smartship
Version: 1.1.2
Summary: Posti SmartShip API
Home-page: https://github.com/andersinno/smartship
Author: Anders Innovations
Author-email: support@anders.fi
Maintainer: Anders Innovations
Maintainer-email: support@anders.fi
License: MIT
Download-URL: https://github.com/andersinno/smartship/releases
Description: 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
        
Keywords: smartship,posti
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Libraries :: Python Modules
