Posti SmartShip API
Project description
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
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
Built Distribution
Hashes for smartship-1.1.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e0753fa2ca56d47a33fc226942c9e2591595570246620f4e912db412f58b7ee0 |
|
MD5 | 404bc76a8e8502e25ee5d18d25656848 |
|
BLAKE2b-256 | 0e0ddbf0390486afd809ac3d0d9e05a3c6ba3f1f343b4d40e14ef7db775f5b9e |