NAME

Webservice::Shipment - Get common shipping information from supported carriers

SYNOPSIS

use strict;
use warnings;

use Webservice::Shipment;

my $ship = Webservice::Shipment->new(defaults => {date_format => '%m/%d/%y'});
$ship->add_carrier(UPS => {
  api_key  => 'MYAPIKEY_12345',
  username => 'some_user',
  password => 'passw0rd',
});
$ship->add_carrier(USPS => {
  username => 'my_username',
  password => 'p@ssword',
});

use Data::Dumper;

print Dumper $ship->track('9400105901096094290500'); # usps
print Dumper $ship->track('1Z584056NW00605000'); # ups

# non-blocking with callback
$ship->track('1Z584056NW00605000', sub {
  my ($carrier, $err, $info) = @_;
  warn $err if $err;
  print Dumper $info
});

__END__
# sample output

{
  'status' => {
    'description' => 'DELIVERED',
    'date' => '12/24/14',
    'delivered' => 1,
  },
  'destination' => {
    'address1' => '',
    'address2' => '',
    'city' => 'BEVERLY HILLS',
    'state' => 'CA',
    'country' => '',
    'postal_code' => '90210',
  },
  'weight' => '0.70 LBS',
  'service' => 'UPS NEXT DAY AIR',
  'human_url' => 'http://wwwapps.ups.com/WebTracking/track?trackNums=1Z584056NW00605000&track.x=Track',
}

DESCRIPTION

Webservice::Shipment is a central module for obtaining shipping information from supported carriers. It is very lightweight, built on the Mojolicious toolkit. The fact that it is built on Mojolicious does not restrict its utility in non-Mojolicious apps.

Webservice::Shipment::Carrier subclasses request information from that carrier's api and extract information from it. The information is then returned in a standardized format for ease of use. Futher, Webservice::Shipment itself tries to deduce which carrier to use based on the id number. This makes it very easy to use, but also implies that it will only ever report common information. More detailed API interfaces already exist and are mentioned below.

Note that this is a very early release and will likely have bugs that need to be worked out. It should be used for informative puposes only. Please do not rely on this for mission critical code until this message is removed.

ATTTRIBUTES

Webservice::Shipment inherits all of the attributes from Mojo::Base and implements the following new ones.

carriers

An array refence of added Webservice::Shipment::Carrier objects. You probably want to use "add_carrier" instead.

defaults

A hash reference of default values to be merged with per-carrier constructor arguments when using "add_carrier". This defaults can be overridden by passing in an explicity parameter of the same name to "add_carrier". This is especially useful for date_format parameters and possibly for username and/or password if those are consistent between carriers.

METHODS

Webservice::Shipment inherits all of the methods from Mojo::Base and implements the following new ones.

add_carrier

$ship = $ship->add_carrier(UPS => { username => '...', password => '...', api_key => '...', ... });
$ship = $ship->add_carrier($carrier_object);

Adds an instance of Webservice::Shipment::Carrier to "carriers". If passed an object, the object is verified to be a subclass of that module and added. Otherwise, the first argument is assumed to be a class name, first attempted relative to Webservice::Shipment::Carrier then as absolute. If the class can be loaded, its parentage is checked as before and then an instace is created, using an optional hash as constructor arguments. If provided, those arguments should conform to the documented constructor arguments for that class.

If these conditions fail, and no carrier is added, the method throws an exception.

delegate

$ship->delegate('method_name', $id, @addl_args);

Attempts to call method_name on an carrier instance in "carriers" which corresponds to the given $id. This is done via the "detect" method. In the above example if the detected instance was $carrier it would then be called as:

$carrier->method_name($id, @addl_args);

Clearly this only is only useful for carrier methods that take an id as a leading argument. If no carrier is detected, an exception is thrown.

This method is used to implement AUTOLOAD for this class. This allows the very simple usage:

$ship->add_carrier($c1)->add_carrier($c2);
$info = $ship->track($id);

detect

$carrier = $ship->detect($id);

Returns the first carrier in "carriers" that validates the given id as something that it can handle, via "validate" in Webservice::Shipment::Carrier. Returns undef if no carrier matches.

SEE ALSO

Shipment

Parcel::Track

Net::Async::Webservice::UPS

Business::Shipping

SPECIAL THANKS

Pharmetika Software, http://pharmetika.com

AUTHOR

Joel Berger, <joel.a.berger@gmail.com>

CONTRIBUTORS

Ryan Perry

COPYRIGHT AND LICENSE

Copyright (C) 2015 by "AUTHOR" and "CONTRIBUTORS".

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