DHL REST Webservice integration
Project description
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 weightlength
(Mandatory): Package lengthwidth
(Mandatory): Package widthheight
(Mandatory): Package heightprice
(Optional): Package pricedescription
(Optional): Package descriptionreference
(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 linecity
(Mandatory): Person's citypostal_code
(Mandatory): Person's postal codecountry
(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 namephone
(Mandatory): Person's phoneemail
(Optional): Person's email.'null'
by defaultcompany
(Optional): Person's company.name
by default
Shipment
Mandatory inputs:
packages
: A list of Packagesender
andrecipient
: 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.