The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Business-UPS-Tracking-1.09
River stage zero No dependents
++
/ Business::UPS::Tracking

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:

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.

  • method

  • depth

  • evaltext

  • sub_name

  • last_error

  • sub

  • is_require

  • 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

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

COPYRIGHT

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.