NAME
Business::UPS::Tracking - Interface to the UPS tracking webservice
SYNOPSIS
use Business::UPS::Tracking;
my $tracking = Business::UPS::Tracking->new(
AccessLicenseNumber => '1CFFED5A5E91B17',
UserId => 'myupsuser',
Password => 'secret',
);
eval {
my $response = $tracking->request(
TrackingNumber => '1Z12345E1392654435',
)->run();
foreach my $shipment ($response->shipment) {
say 'Service code is '.$shipment->ServiceCode;
foreach my $package ($shipment->Package) {
say 'Status is '.$package->CurrentStatus;
}
}
};
if (my $e = Exception::Class->caught) {
given ($e) {
when ($->isa('Business::UPS::Tracking::X::HTTP')) {
say 'HTTP ERROR:'.$e->fullmessage;
}
when ($->isa('Business::UPS::Tracking::X::UPS')) {
say 'UPS ERROR:'.$e->fullmessage.' ('.$e->code.')';
}
default {
say 'SOME ERROR:'.$e;
}
}
}
DESCRIPTION
Class structure
.-----------------------------------.
| Business::UPS::Tracking |
'-----------------------------------'
^
HAS ONE
|
.-----------------------------------.
| B::U::T::Request |
'-----------------------------------'
^
HAS ONE
|
.-----------------------------------.
| B::U::T::Response |
'-----------------------------------'
|
HAS MANY
v
.-----------------------------------.
| B::U::T::Shipment |
'-----------------------------------'
^ ^
ISA ISA
| |
.---------------------------------. .-----------------------------------.
| B::U::T::Shipment::Freight | | B::U::T::Shipment::Smallpackage |
|---------------------------------| |-----------------------------------|
| Freight shipment type | | Small package shipment type |
| Not yet implemented | '-----------------------------------'
'---------------------------------' |
HAS MANY
v
.-----------------------------------.
| B::U::T::Element::Package |
'-----------------------------------'
|
HAS MANY
v
.-----------------------------------.
| B::U::T::Element::Activity |
'-----------------------------------'
Exception Handling
If anythis goes wrong Business::UPS::Tracking throws an exception.
Exceptions are always Exception::Class objects which contain structured
information about the error. Please refer to the synopsis or to the
Exception::Class documentation for documentation how to catch and
rethrow exeptions.
The following exception classes are defined:
Business::UPS::Tracking::X
Basic exception class. All other exception classes inherit from this
class.
Business::UPS::Tracking::X::HTTP
HTTP error. The object provides additional parameters:
Business::UPS::Tracking::X::UPS
UPS error message.The object provides additional parameters:
Business::UPS::Tracking::X::XML
XML parser or schema error.
Business::UPS::Tracking::X::CLASS
Error originating from the wrong usage of a method/accessor/class. Most
commonly this will be thrown because of a failing type constraint.
Accessor / method naming
The naming of the methods and accessors tries to stick close to the
names used by the UPS webservice. All accessors containg uppercase
letters access xml data. Lowercase-only accessors and methods are used
for utility functions.
UPS license
In order to use this module you need to obtain a "Tracking WebService"
license key. See <http://www.ups.com/e_comm_access/gettools_index> for
more information.
METHODS
new
my $tracking = Business::UPS::Tracking->new(%params);
Create a "Business::UPS::Tracking" object. See ACCESSORS for available parameters.
access_request
UPS access request.
request
my $request = $tracking->request(%request_params);
Returns a Business::UPS::Tracking::Request object.
request_run
my $response = $tracking->request_run(%request_params);
Generates a Business::UPS::Tracking::Request object and imideately executes it, returning a Business::UPS::Tracking::Response object.
ACCESSORS
AccessLicenseNumber
UPS tracking service access license number
UserId
UPS account username
Password
UPS account password
config
Optionally you can retrieve all or some UPS webservice credentials from
a configuration file. This accessor holds the path to this file.
Defaults to "~/.ups_tracking"
Example configuration file:
<?xml version="1.0"?>
<UPS_tracing_webservice_config>
<AccessLicenseNumber>1CFFED5A5E91B17</AccessLicenseNumber>
<UserId>myupsuser</UserId>
<Password>secret</Password>
</UPS_tracing_webservice_config>
retry_http
Number of retries if http errors occur
Defaults to 0
url
UPS Tracking webservice url.
Defaults to https://wwwcie.ups.com/ups.app/xml/Track
_ua
LWP::UserAgent object.
Automatically generated
SUPPORT
Please report any bugs or feature requests to "bug-buisness-ups-tracking@rt.cpan.org", or through the web interface at <http://rt.cpan.org/Public/Bug/Report.html?Queue=Business::UPS::Tracking>. I will be notified, and then you'll automatically be notified of progress on your report as I make changes.
AUTHOR
Maroš Kollár
CPAN ID: MAROS
maros [at] k-1.com
http://www.k-1.com
ACKNOWLEDGEMENTS
This module was written for Revdev <http://www.revdev.at>, a nice litte software company I run with Koki and Domm (<http://search.cpan.org/~domm/>).
COPYRIGHT
Business::UPS::Tracking is Copyright (c) 2009 Maroš Kollár.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
Download the UPS "OnLine® Tools Tracking Developer Guide" and get a
developer key at
<http://www.ups.com/e_comm_access/gettools_index?loc=en_US>. Please
check the "Developer Guide" for more detailed documentation on the
various fields.
The WebService::UPS::TrackRequest provides an alternative simpler implementation.