NAME

Net::Async::Webservice::DHL - DHL API client, non-blocking

VERSION

version 1.2.2

SYNOPSIS

use IO::Async::Loop;
use Net::Async::Webservice::DHL;
use Data::Printer;

my $loop = IO::Async::Loop->new;

my $dhl = Net::Async::Webservice::DHL->new({
  config_file => $ENV{HOME}.'/.naws_dhl.conf',
  loop => $loop,
});

$dhl->get_capability({
  from => $address_a,
  to => $address_b,
  is_dutiable => 0,
  currency_code => 'GBP',
  shipment_value => 100,
})->then(sub {
  my ($response) = @_;
  p $response;
  return Future->wrap();
});

$loop->run;

Alternatively:

use Net::Async::Webservice::DHL;
use Data::Printer;

my $ups = Net::Async::Webservice::DHL->new({
  config_file => $ENV{HOME}.'/.naws_dhl.conf',
  user_agent => LWP::UserAgent->new,
});

my $response = $dhl->get_capability({
  from => $address_a,
  to => $address_b,
  is_dutiable => 0,
  currency_code => 'GBP',
  shipment_value => 100,
})->get;

p $response;

DESCRIPTION

This class implements some of the methods of the DHL XML-PI API, using Net::Async::HTTP as a user agent by default (you can still pass something like LWP::UserAgent and it will work). All methods that perform API calls return Futures (if using a synchronous user agent, all the Futures will be returned already completed).

ATTRIBUTES

live_mode

Boolean, defaults to false. When set to true, the live API endpoint will be used, otherwise the test one will. Flipping this attribute will reset "base_url", so you generally don't want to touch this if you're using some custom API endpoint.

base_url

A URI object, coercible from a string. The base URL to use to send API requests to. Defaults to the standard DHL endpoints:

• https://xmlpi-ea.dhl.com/XMLShippingServlet for live

• https://xmlpitest-ea.dhl.com/XMLShippingServlet for testing

See also "live_mode".

username

password

Strings, required. Authentication credentials.

user_agent

A user agent object, looking either like Net::Async::HTTP (has do_request and POST) or like LWP::UserAgent (has request and post). You can pass the loop constructor parameter to get a default Net::Async::HTTP instance.

METHODS

new

Async:

my $dhl = Net::Async::Webservice::DHL->new({
   loop => $loop,
   config_file => $file_name,
});

Sync:

my $dhl = Net::Async::Webservice::DHL->new({
   user_agent => LWP::UserAgent->new,
   config_file => $file_name,
});

In addition to passing all the various attributes values, you can use a few shortcuts.

loop

a IO::Async::Loop; a locally-constructed Net::Async::HTTP will be registered to it and set as "user_agent"

config_file

a path name; will be parsed with Config::Any, and the values used as if they had been passed in to the constructor

get_capability

$dhl->get_capability({
  from => $address_a,
  to => $address_b,
  is_dutiable => 0,
  currency_code => 'GBP',
  shipment_value => 100,
}) ==> ($hashref)

from and to are instances of Net::Async::Webservice::DHL::Address, is_dutiable is a boolean.

Optional parameters:

date

the date/time for the booking, defaults to now; it will converted to UTC time zone

product_code

a DHL product code

message_reference

a string, to uniquely identify individual messages

Performs a GetCapability request. Lots of values in the request are not filled in, this should be used essentially to check for address validity and little more. I'm not sure how to read the response, either.

The Future returned will yield a hashref containing the "interesting" bits of the XML response (as judged by XML::Compile::Schema), or fail with an exception.

route_request

$dhl->route_request({
  region_code => $dhl_region_code,
  routing_type => 'O', # or 'D'
  address => $address,
  origin_country_code => $country_code,
}) ==> ($hashref)

address is an instance of Net::Async::Webservice::DHL::Address. type is O for origin routing, or D for destination routing. origin_country_code is the "country code of origin" according to the DHL spec.

Optional parameters:

message_reference

a string, to uniquely identify individual messages

Performs a RouteRequest request.

The Future returned will yield a hashref containing the "interesting" bits of the XML response (as judged by XML::Compile::Schema), or fail with an exception.

xml_request

$dhl->xml_request({
  request_method => $string,
  data => \%request_data,
}) ==> ($parsed_response);

This method is mostly internal, you shouldn't need to call it.

It builds a request XML document by passing the given data to an XML::Compile writer built on the DHL schema.

It then posts (possibly asynchronously) this to the "base_url" (see the "post" method). If the request is successful, it parses the body with a XML::Compile reader, either the one for the response or the one for ErrorResponse, depending on the document element. If it's a valid response, the Future is completed with the hashref returned by the reader. If it's ErrorResponse, teh Future is failed with a Net::Async::Webservice::DHL::Exception::DHLError contaning the response status.

post

$dhl->post($body) ==> ($decoded_content)

Posts the given $body to the "base_url". If the request is successful, it completes the returned future with the decoded content of the response, otherwise it fails the future with a Net::Async::Webservice::Common::Exception::HTTPError instance.

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Net-a-porter.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.