DHL API Integration

[espero]

Hello,

I'm working on a project, where I have to integrate DHL services (e.g. shipment request) into a web application and I was wondering if anyone has experience with this? I'm new to Perl, any advice/suggestion would be greatly appreciated. Thank you in advance for your help.

[hippo]

I'm new to Perl, any advice/suggestion would be greatly appreciated.

Welcome to the Monastery and to the wonderful world of Perl. The obvious suggestion is to begin by browsing the Getting Started with Perl category within the Tutorials section.

I have to integrate DHL services (e.g. shipment request) into a web application and I was wondering if anyone has experience with this?

I have no experience with DHL specifically. A quick search on https://metacpan.org/ brings up Net::Async::Webservice::DHL which sounds like it might be ideal but as I haven't used it this isn't a recommendation. It does use an event loop so maybe not the easiest module to use for a beginner in all honesty. Perhaps some other monk has experience with it and can comment further.

OTOH there are lots of general web service client modules on CPAN so you might want to start with one of those if Net::Async::Webservice::DHL proves too complex/unwieldy/out-of-date.

Good luck with your project.

[espero]

Hello,

Thank you very much for your prompt response and help and for welcoming me. I had a look at Net::Async::Webservice::DHL but as you suggested it appears to be out of date (based on the release date) and the distribution is up for adoption. I will take a look at the general web service clients.

[Marshall]

I am not sure what you are doing. More explanation would be very helpful - who is going to use your app and what are they going to do with it? I would start with DHL, not CPAN. Find out what interfaces and services DHL provides and then figure how to talk to what they prefer. Search for "DHL integration API". I found this: DHL Parcel API. I don't have any experience with DHL specifically, but there will be, with high probability, some kind of automated way to talk to DHL and they will encourage that! Figure out what you need to do as the first step. Then we can talk about how to get Perl to do what you need to do.

update: also perhaps DHL Developer Portal. Anyway, I would start with figuring out what DHL can and cannot do and matching that up with what you need to do and what you don't need to do. It sounds likely that some CPAN code could be useful although that may not be the case. I would run some of the examples shown in my first link and see what makes sense to you - in any event you will have to learn what JSON means and learn some of the buzzwords.

This is an intimidating first project in any language.

[espero]

Hello,

Thank you very much for your detailed reply and help. The links are very useful. Basically I'm trying to automate a shipping process. Currently simple address labels are printed from an existing web application for each order which needs to be shipped. After this, each shipment is entered manually on DHL's portal to request a shipment, book a collection etc. When the simple address label is printed I would like to send the data automatically to DHL, request the shipment, book the collection and print out the DHL label. Ideally I would like to display the shipment details on a validation screen before the shipment request is sent to DHL. I'm able to connect to DHL's API test service via the Postman application. I have a Postman JSON collection file which contains sample requests for all of the DHL services and I was able to get a response form the server. If you could advise how to write some of these sample requests in Perl as a first step that would be greatly appreciated.

Thank you again for your help.

Update: I also have the WSDL files for the API services such as address validation, request pickup etc. I was wondering if I could use these with a module such as XML::Compile::WSDL11?

Update2: I also have the open API specifications in YAML format. I was wondering if I could use this with YAML::XS?

[Marshall]

Hi espero,

Thanks for more info that put your application into context. I don't know what the Postman application is, nor have I made any serious study of the DHL JSON API. However, my understanding is that they have a test URL, where you can "practice" sending requests without actually triggering a shipment. It also appears to me that you just need a very small subset of the DHL API's capabilities. It also appears that there is really only one "user" for your application which will be a custom deal for your company (no need to bullet proof a complete turnkey application for some unknown person).

I recommend starting simple. Program #1: Get the address (and perhaps package weight? or whatever else you need) from your existing order system and print that to the screen. Program #2: Take output of prog #1 and format it into the JSON format needed by DHL, send it as a shipment request and see what you get back (perhaps at first just print their JSON response to the screen). Get the "good machine" case working. Then intentionally booger the address like maybe no postal code or whatever you can ad hock dream up - see how "well behaved" the DHL I/F is in actual practice with "bad" input. You will need to handle all error possibilities from the DHL spec, but at first just hack around and discover things by playing...The purpose being to gain experience with Perl and looking at JSON.

The DHL CPAN module mentioned earlier is likely to be a lot more trouble than it is worth to you. When I briefly looked at it, one of its main purposes was to process what are called Asynchronous Requests. Basically this allows you to have multiple outstanding requests at a time. If you do that, you can cram more requests per second into DHL at the cost of an order of magnitude of complexity. Do not do that. Send a single request, wait until DHL has processed that request and replied with "the answer". Then do the next request, etc. You do not describe a "high volume" application.

I don't think the YAML spec will be of much use either. That is basically a general data description language which does not tell you exactly the JSON format that DHL expects for that data. This "I have a Postman JSON collection file which contains sample requests for all of the DHL services and I was able to get a response form the server." sounds a lot more promising.

You will need to do the homework on what parts of the DHL API you need to implement (and I suspect this subset is tiny).

The Monks can help with refining your Perl code. This is best done by starting to write some code yourself. Then when you get into trouble or just want coding advice, post a runnable code example on SOPW. It doesn't have to be completely working - but should be enough so that a Monk can just click on it and run it themselves to replicate your error condition. "use warnings;" and "use strict;" and get rid of all syntax errors. And of sourse should have the dummy credentials and test URL that you are using.

This is a big "first Perl project". Start with one simple piece at a time. I would look at Perl JSON module, encoding and decoding a Perl data structure into JSON. If you have it JSON::XS is faster. XS typically means a completely compatible version written in C so that it runs faster. However, in your case, the data structures that you need to send and receive are "small" and this probably makes no significant difference.

Update: Now that I think about it, you say you have some properly formatted JSON examples. Start by using the JSON module to translate one of your examples into a Perl data structure. You can use Perl Data Dumper to see what kind of thing you have. Then write your own Perl code to access the created Perl structure and print each element yourself. To send JSON to DHL, you will have to reverse the process, create Perl Data Structure, then encode it.

Update2: So I guess basic workflow is like this:
1. get a shipment request with address, etc. from your existing web system.
2. translate that data into a Perl data structure containing all of the elements that DHL will need for a valid shipping request.
3. encode that Perl Data Structure into JSON
4. send JSON formatted request to DHL
5. see what DHL has to say about that request (decode their JSON formatted response).

As first steps, (1) figure out how to get the "triggering event" from the existing system. (2) work on sending and receiving the JSON formatted info between your app and DHL.

If you are successful with this first part, requirements will expand to potentially "solving global hunger level". Don't start with the idea of "solving world hunger". Start with making your shipping process incrementally better.