Package: python-dhlparcel-api
DHL Parcel APIBasic wrapper for the DHL Parcel API (v1).DisclaimerThis wrapper doesnotinclude all API endpoints. I will extend this package as I go and as I need.This package is inactive developmentand is the reason why there is no stable version yet.Getting startedInstallThis package is published on PyPi:https://pypi.org/project/python-dhlparcel-api/Install with pippipinstallpython-dhlparcel-apiImportImport the package and the DHLParcel_API.fromdhlparcel.apiimportDHLParcel_APICreate connectionYou 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-servicesapi=DHLParcel_API(user_id,user_key,account_number)AuthenticationAuthentication will happen automatically.During a first request, theuser_idanduser_keywill 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, theuser_idanduser_keywill once again be used to obtain new tokens.Retrieving dataYou 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.fromdhlparcel.apiimportDHLParcel_APIapi=DHLParcel_API(user_id,user_key,account_number)parcelshops=api.parcelshops.list('BE',zipCode='2000')forshopinparcelshops.items():print(shop.name)CreatingSome 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 asargumentsto the function. These arguments contain either alistor adictof 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 thenew_shipmentobject.Error handlingBasic error handling has been added. You can check if an error has occured during a call by checking thehas_errorattribute on an object. If thehas_errorhas been set toTrue, anErrorobject will be attached to theerrorattribute of the same object. TheErrorobject contains two attributes:returned_contentandstatus.returned_contentcan be empty as not all errors return something.shipment=api.shipments.get(id)ifshipment.has_error:print(shipment.error.status)# status codeprint(shipment.error.returned_content)# returned content, if any. Can be empty.Available endpoints & functionsFollowing endpoints are available:capabilitiesshipmentslabelsparcel_typesproductspickup_availablityparcelshopsFollowing 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 aBaseModelobject with the returned fields from the response attached as attributes. A list will always return aObjectListModel, which you can iterate over using the.items()function. This will return a list ofBaseModelobjects.