Business::UPS::Tracking - Interface to the UPS tracking webservice

  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;
      }        
    }
  }

                   .-----------------------------------.
                   |     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     |
                                     '-----------------------------------'

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:

Basic exception class. All other exception classes inherit from this class.

HTTP error. The object provides additional parameters:

* http_response : HTTP::Response object

* request : Business::UPS::Tracking::Request object

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

XML parser or schema error.

Error originating from the wrong usage of a method/accessor/class. Most commonly this will be thrown because of a failing type constraint.

* method

* depth

* evaltext

* sub_name

* last_error

* sub

* is_require

* has_args

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.

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.

 my $tracking = Business::UPS::Tracking->new(%params);

Create a Business::UPS::Tracking object. See ACCESSORS for available parameters.

UPS access request.

 my $request = $tracking->request(%request_params);

Returns a Business::UPS::Tracking::Request object.

 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.

UPS tracking service access license number

UPS account username

UPS account password

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>

Number of retries if http errors occur

Defaults to 0

UPS Tracking webservice url.

Defaults to https://wwwcie.ups.com/ups.app/xml/Track

LWP::UserAgent object.

Automatically generated

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.

    Maroš Kollár
    CPAN ID: MAROS
    maros [at] k-1.com
    http://www.k-1.com

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/).

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.

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.