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->full_message;
}
when ($_->isa('Business::UPS::Tracking::X::UPS')) {
say 'UPS ERROR:'.$e->full_message.' ('.$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:
http_response : HTTP::Response object
request : Business::UPS::Tracking::Request object
Business::UPS::Tracking::X::UPS
UPS error message.The object provides additional parameters:
code : UPS error code
severity : Error severity 'hard' or 'soft'
context : XML::LibXML::Node object containing the whole error response.
request : Business::UPS::Tracking::Request object
Business::UPS::Tracking::X::XML
XML parser or schema error.
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_tracking_webservice_config>
<AccessLicenseNumber>1CFFED5A5E91B17</AccessLicenseNumber>
<UserId>myupsuser</UserId>
<Password>secret</Password>
</UPS_tracking_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.
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.
AUTHOR
Maroš Kollár
CPAN ID: MAROS
maros [at] k-1.com
http://www.k-1.comCOPYRIGHT
Business::UPS::Tracking is Copyright (c) 2012 Maroš Kollár - http://www.k-1.com
LICENCE
This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.