# 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](http://search.cpan.org/perldoc?Exception::Class) objects which contain structured information
about the error. Please refer to the synopsis or to the [Exception::Class](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?HTTP::Response) object

- * request : [Business::UPS::Tracking::Request](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?XML::LibXML::Node) object containing the whole error response.

- * request : [Business::UPS::Tracking::Request](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?ACCESSORS) for available
parameters.

## access_request

UPS access request.

## request

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

Returns a [Business::UPS::Tracking::Request](http://search.cpan.org/perldoc?Business::UPS::Tracking::Request) object. 

## request_run

 my $response = $tracking->request_run(%request_params);

Generates a [Business::UPS::Tracking::Request](http://search.cpan.org/perldoc?Business::UPS::Tracking::Request) object and imideately 
executes it, returning a [Business::UPS::Tracking::Response](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?WebService::UPS::TrackRequest) provides an alternative simpler 
implementation.