pyDHL 0.3

DHL REST Webservice integration

pyDHL

Python module to work with DHL REST Webservice integration.

pyDHL as module

import pyDHL

By running it as a module pyDHL will expose the following resources.

Package

Inputs:

• weight (Mandatory): Package weight
• length (Mandatory): Package length
• width (Mandatory): Package width
• height (Mandatory): Package height
• price (Optional): Package price
• description (Optional): Package description
• reference (Optional): Package reference

from pyDHL import Package

package = Package(
        weight=<package_weight>,
        length=<package_length>,
        width=<package_width>,
        height=<package_height>
    )]

Person

A person is a combination of a Contact and Address information. This class is used for both sender and recipient of the the package.

Rate request just needs shipment's Address.

Address

Inputs:

• street_lines (Mandatory): Person's address first line
• city (Mandatory): Person's city
• postal_code (Mandatory): Person's postal code
• country (Mandatory): Person's country, Must oblige to the DHL's country codes.
• street_lines2 (Optional): Person's address second line. 'N/A' by default.
• street_lines3 (Optional): Person's address third line.

Contact

Inputs:

• name (Mandatory): Person's name
• phone (Mandatory): Person's phone
• email (Optional): Person's email. 'null' by default
• company (Optional): Person's company. name by default

Shipment

Mandatory inputs:

• packages: A list of Package
• sender and recipient: Persons (or Address in rate request)

In order to build a correct Shipment, please refer to the documentation. Some parameters are set by default and others such as SERVICE_TYPE are set following a set of conditions and properties of the Shipment itself.

Requests

All requests will have as input a valid Shipment object or a dict or dict-like structure.

In order to send requests to DHL Webservices you must first set credentials:

from pyDHL import requests

credentials = {
  'account':  # your account number
  'username':  # your username
  'password':  # your password
}

requests.set_credentials(credentials)

Optionally it is possible to set the 'sandbox' environment for testing purposes.

requests.set_sandbox([True|False])  # use DHL's sandbox endpoints

The result of every request is either the JSON response of the DHL endpoint or, if the requests was wrong, a JSON-like object if twith error and message keys describing the error.
Every requests will update the shipment object given by input if the request was successful.

Rate Request

Rate Request will return DHL’s product capabilities (products, services and estimated delivery time) and prices (where applicable) for a certain set of input data.

• Input: Shipment
• Output: JSON response. DHL Rate Request

from pyDHL.requests import rate

# create a valid shipment
response = rate(shipment)

Shipment Request

The key elements in the response of the Shipment Request will be a base64 encoded PDF label and the Shipment and Piece identification numbers, which you can use for tracking on the DHL web site.

• Input: Shipment
• Output: JSON response. DHL Shipment Request

from pyDHL.requests import shipment

# create a valid shipment
response = shipment(shipment)

Update Request

The updateShipment request allows for additional pieces to be added to a previously created shipment that has not been picked up by DHL Express/had a scan against it.

• Input: Shipment
• Output: JSON response. DHL Update Request

from pyDHL.requests import update

# create a valid shipment
response = update(shipment)

Tracking Request

The resulting response will provide tracking events at both the Shipment and/or Piece events corresponding to the DHL Waybill(s) submitted.

• Input: Shipment
• Output: JSON response. DHL Tracking Request

from pyDHL.requests import tracking

# create a valid shipment
response = tracking(shipment.id, level=[TRACKING_LAST|TRACKING_ALL])

pyDHL's Command Line interface

Use pyDHL as a command line program to set up a quick shipment

pyDHL <option> <shipment_file> [mode]

Options

Options flag gets mapped with each of the available requests:

• -r RATE, --rate RATE: Rate Request will return DHL’s product capabilities (products, services and estimated delivery time) and prices (where applicable) for a certain set of input data.

• -s SHIPMENT, --shipment SHIPMENT: The key elements in the response of the Shipment Request will be a base64 encoded PDF label and the Shipment and Piece identification numbers, which you can use for tracking on the DHL web site.

• -u UPDATE, --update UPDATE: The updateShipment request allows for additional pieces to be added to a previously created shipment that has not been picked up by DHL Express/had a scan against it.

• -t TRACK, --track TRACK: The resulting response will provide tracking events at both the Shipment and/or Piece events corresponding to the submitted DHL Waybill (Shipment id).

• -p PICKUP, --pickup PICKUP: The requestPickup request allows users to request standalone pickup requests for local and remote/import pickups.

• -o OUTPUT, --output OUTPUT: Output File

• --sandbox: Set sandbox mode

Shipment File

Following every option there is a shipment file. This is a file that contains all necessary data to build and send requests to DHL. There is an example in shipment.json.

Mode

By default pyDHL will use DHL endpoints that will execute real shipments and other actions. For testing purposes and development there is a "sandbox" mode that can be activated by adding -snd|--sandbox at the end of the command

Testing

In order to a successful testing, please edit tests/config.py file with valid DHL credentials for accessing HTTPS endpoints.

pyDHL uses pytest and coverage to execute tests and to check if everything was correctly executed.

coverage run -m pytest

Tests are separated between different kinds of shipments available:

• National: Shipments with origin and source in the same country.
• EU: Shipments coming from an country in Europe and with destination to a country in Europe.
• International: None of the cases above.