NAME

       Business::US::USPS::WebTools::TrackConfirm - track a shipment using the USPS Web Tools

SYNOPSIS

               use Business::US::USPS::WebTools::TrackConfirm;

               my $tracker = Business::US::USPS::WebTools::TrackConfirm->new( {
                       UserID   => $ENV{USPS_WEBTOOLS_USERID},
                       Password => $ENV{USPS_WEBTOOLS_PASSWORD},
                       Testing  => 1,
                       } );

               my $hash = $tracker->track(
                       );

               if( $tracker->is_error )
                       {
                       warn "Oh No! $tracker->{error}{description}\n";
                       }
               else
                       {
                       print join "\n", map { "$_: $hash->{$_}" }
                               qw(FirmName Address1 Address2 City State Zip5 Zip4);
                       }

DESCRIPTION

       *** THIS IS ALPHA SOFTWARE ***

       This module implements the Track & Confirm web service from the US Postal Service. It is a
       subclass of Business::US::USPS::WebTools.

       track( KEY, VALUE, ... )
           The "track" method takes the following keys, which come directly from the USPS web
           service interface:

                   TrackID   The tracking number

           It returns an anonymous hash with the data from the response. Although the USPS API
           allows one to make multiple queries in a single request, this method one queries one.

           If you want to see if something went wrong, check:

                   $tracker->is_error;

           See the "is_error" documentation in Business::US::USPS::WebTools for more details on
           error information.

       tracking_number_regex
           Returns the regex that checks a tracking number. I have it in its own method so you
           can easily override it if I got it wrong.

           The USPS shows the valid forms at

                   https://tools.usps.com/go/TrackConfirmAction!input.action

                   USPS Tracking®                        9400 1000 0000 0000 0000 00
                   Priority Mail®                        9205 5000 0000 0000 0000 00
                   Certified Mail®                       9407 3000 0000 0000 0000 00
                   Collect on Delivery                       9303 3000 0000 0000 0000 00
                   Global Express Guaranteed®                82 000 000 00
                   Priority Mail Express International™  EC 000 000 000 US
                   Priority Mail Express™                9270 1000 0000 0000 0000 00
                                                     EA 000 000 000 US
                   Priority Mail International®          CP 000 000 000 US
                   Registered Mail™                      9208 8000 0000 0000 0000 00
                   Signature Confirmation™               9202 1000 0000 0000 0000 00

       is_valid_tracking_number( ID )
           Returns a normalized version of the tracking number if ID looks like a tracking
           number, based on the regex from "tracking_number_regex".  Returns false otherwise.

           Normalizing ID merely removes all whitespace. Sometimes the USPS shows the numbers
           with whitespace.

       service_type( ID )
           Returns the service type, based on the examples shown by the USPS and shown in
           "tracking_number_regex". I know this is wrong because I have tracking numbers that
           don't have the same leading characters for Priority Mail International.

TO DO

SEE ALSO

       Business::US::USPS::WebTools

       The WebTools API is documented on the US Postal Service's website:

       https://www.usps.com/business/web-tools-apis/track-and-confirm-api.htm

SOURCE AVAILABILITY

       This source is in GitHub:

               https://github.com/briandfoy/business-us-usps-webtools

AUTHOR

       brian d foy, "<bdfoy@cpan.org>"

COPYRIGHT AND LICENSE

       Copyright © 2006-2016, brian d foy <bdfoy@cpan.org>. All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

perl v5.26.2                                2018-0Business::US::USPS::WebTools::TrackConfirm(3pm)