Wrapper for the DHL Parcel API endpoints
Project description
DHL Parcel API
Basic wrapper for the DHL Parcel API (v1).
Disclaimer
This wrapper does not include all API endpoints. I will extend this package as I go and as I need.
This package is in active development and is the reason why there is no stable version yet.
Getting started
Install
This package is published on PyPi: https://pypi.org/project/python-dhlparcel-api/
Install with pip
pip install python-dhlparcel-api
Import
Import the package and the DHLParcel_API.
from dhlparcel.api import DHLParcel_API
Create connection
You will need your user ID, user key and account number to create a connection. Find out how you can obtain these here: https://dhlparcel.github.io/api-gtw-docs/#12-services
api = DHLParcel_API(user_id, user_key, account_number)
Authentication
Authentication will happen automatically.
During a first request, the user_id
and user_key
will be used to obtain an access token and a request token. These tokens will be cached and used for other requests. Once an access token expires, a new one will automatically be retrieved by using the refresh token. If the access token and the refresh token has expired, or are not available inside the cache, the user_id
and user_key
will once again be used to obtain new tokens.
Retrieving data
You can retrieve data by using the .get(id)
or .list()
functions on a given endpoint. The .get()
function will return a single object and will contain all the returned fields as attributes. The .list()
function will return a list of objects. You can loop over a list by calling .items()
on it.
You can consult the API documentation to know what returned fields to expect.
from dhlparcel.api import DHLParcel_API
api = DHLParcel_API(user_id, user_key, account_number)
parcelshops = api.parcelshops.list('BE', zipCode='2000')
for shop in parcelshops.items():
print(shop.name)
Creating
Some endpoints allow you to create new objects, such as a label or a shipment.
These endpoints have the .create()
functions available.
Consider the following request needed to create a shipment:
{
"shipmentId": "15916857-2a31-4238-a45b-e7ba32e0e320",
"orderReference": "myReference",
"receiver": {
"name": {
"firstName": "John",
"lastName": "Doe",
"companyName": "ACME Corp.",
"additionalName": "Benelux"
},
"address": {
"countryCode": "NL",
"postalCode": "3542AD",
"city": "Utrecht",
"street": "Reactorweg",
"additionalAddressLine": "Street part 2 (not applicable for DHL Parcel Benelux)",
"number": "25",
"isBusiness": true,
"addition": "A"
},
"email": "mrparcel@dhlparcel.nl",
"phoneNumber": "0031612345678",
"vatNumber": "NL007096100B01",
"eoriNumber": "NL123456789",
"reference": "Customer reference"
},
"shipper": {
"name": {
"firstName": "John",
"lastName": "Doe",
"companyName": "ACME Corp.",
"additionalName": "Benelux"
},
"address": {
"countryCode": "NL",
"postalCode": "3542AD",
"city": "Utrecht",
"street": "Reactorweg",
"additionalAddressLine": "Street part 2 (not applicable for DHL Parcel Benelux)",
"number": "25",
"isBusiness": true,
"addition": "A"
},
"email": "mrparcel@dhlparcel.nl",
"phoneNumber": "0031612345678",
"vatNumber": "NL007096100B01",
"eoriNumber": "NL123456789"
},
"accountId": "01234567",
"options": [
{
"key": "PS",
"input": "8004-NL-132825"
}
],
"pieces": [
{
"parcelType": "SMALL",
"quantity": 1,
"weight": 1,
"dimensions": {
"length": 20,
"width": 25,
"height": 30
}
}
]
}
The top-level attributes: shipmentId
, orderReference
, receiver
, shipper
, options
, etc. are available as arguments to the function. These arguments contain either a list
or a dict
of data, depending on what is expected.
We can then create above shipment request as follows:
new_shipment = api.shipments.create(
shipmentId = "15916857-2a31-4238-a45b-e7ba32e0e320",
orderReference = "myReference",
receiver = {
"name": {
"firstName": "John",
"lastName": "Doe",
"companyName": "ACME Corp.",
"additionalName": "Benelux"
},
"address": {
"countryCode": "NL",
"postalCode": "3542AD",
"city": "Utrecht",
"street": "Reactorweg",
"additionalAddressLine": "Street part 2 (not applicable for DHL Parcel Benelux)",
"number": "25",
"isBusiness": true,
"addition": "A"
},
"email": "mrparcel@dhlparcel.nl",
"phoneNumber": "0031612345678",
"vatNumber": "NL007096100B01",
"eoriNumber": "NL123456789",
"reference": "Customer reference"
},
shipper = {
"name": {
"firstName": "John",
"lastName": "Doe",
"companyName": "ACME Corp.",
"additionalName": "Benelux"
},
"address": {
"countryCode": "NL",
"postalCode": "3542AD",
"city": "Utrecht",
"street": "Reactorweg",
"additionalAddressLine": "Street part 2 (not applicable for DHL Parcel Benelux)",
"number": "25",
"isBusiness": true,
"addition": "A"
},
"email": "mrparcel@dhlparcel.nl",
"phoneNumber": "0031612345678",
"vatNumber": "NL007096100B01",
"eoriNumber": "NL123456789"
},
accountId = "01234567",
options = [
{
"key": "PS",
"input": "8004-NL-132825"
}
],
pieces = [
{
"parcelType": "SMALL",
"quantity": 1,
"weight": 1,
"dimensions": {
"length": 20,
"width": 25,
"height": 30
}
}
]
)
The response will be put in the new_shipment
object.
Error handling
Basic error handling has been added. You can check if an error has occured during a call by checking the has_error
attribute on an object. If the has_error
has been set to True
, an Error
object will be attached to the error
attribute of the same object. The Error
object contains two attributes: returned_content
and status
. returned_content
can be empty as not all errors return something.
shipment = api.shipments.get(id)
if shipment.has_error:
print(shipment.error.status) # status code
print(shipment.error.returned_content) # returned content, if any. Can be empty.
Available endpoints & functions
Following endpoints are available:
- capabilities
- shipments
- labels
- parcel_types
- products
- pickup_availablity
- parcelshops
Following functions are available:
- get()
- list()
- create()
Use them as follows:
api.endpoint.function()
# example:
# api.products.get(id)
# api.products.list()
# api.parcelshops.list()
# api.parcelshops.get(id)
# api.shipments.create()
All functions are type-hinted and thus should tell you what each function for each endpoints expects. A function that retrieves only one object will always return a BaseModel
object with the returned fields from the response attached as attributes. A list will always return a ObjectListModel
, which you can iterate over using the .items()
function. This will return a list of BaseModel
objects.
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.
Source Distribution
Hashes for python-dhlparcel-api-0.0.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1da84ff8522f5132180ba1c16aaf71e0e376021b740d09941ae6513b68f0203b |
|
MD5 | 7fc32b405af6db8637d2dfb34089d4cc |
|
BLAKE2b-256 | 73901843a6aede4524709c49544a55afb5f8ab7bc95fbdab756a4ac97cb911fc |