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 allways Exception::Class object which contain stuctured
    information about the error. Please refer to the synopsis or
    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.

   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.

    *   method =item * depth =item * evaltext =item * sub_name =item *
        last_error =item * sub =item * is_require =item * has_args

  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

  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.