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 $array_of_hashes = $tracker->track( TrackID => $tracking_number );

               if( $tracker->is_error ) {
                       warn "Oh No! $tracker->{error}{description}\n";
                       }
               else {
                       foreach my $hash ( reverse $hash->{TrackDetail}->@* ) {
                               say '-' x 50;
                               say join "\n", map { "$_: $hash->{$_}" }
                                       qw(Event EventCity EventDate EventTime);
                               }
                       }

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( TrackID => VALUE )
           Although  the  USPS  API allows to make multiple queries in a single request, this method one queries
           only one.

           The "track" method takes the following keys, which come directly from the USPS web service interface:

                   TrackID   The tracking number

           It returns an anonymous array of hashes with the data from the response.  Each  hash  represents  one
           step  in the tracking and is blessed into Hash::AsObject. The array is in reverse chronological order
           (so the oldest detail is the last element). The first element is the latest status (and is mostly the
           same as TrackSummary from the API).

           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.

                   <TrackSummary>
                   <EventTime>8:34 pm</EventTime>
                   <EventDate>September 25, 2018</EventDate>
                   <Event>Departed</Event>
                   <EventCity>NEWARK</EventCity>
                   <EventState /><EventZIPCode />
                   <EventCountry>UNITED STATES</EventCountry>
                   <FirmName />
                   <Name />
                   <AuthorizedAgent>false</AuthorizedAgent>
                   <EventCode>AT</EventCode>
                   </TrackSummary>"

       test_server_host
           The testing API uses stg-production.shippingapis.com instead of the usual testing server.

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/ssimms/business-us-usps-webtools

AUTHOR

       brian d foy

MAINTAINER

       Steve Simms

COPYRIGHT AND LICENSE

       Copyright © 2020, Steve Simms. All rights reserved.

       This  program  is free software; you can redistribute it and/or modify it under the terms of the Artistic
       License 2.0.

perl v5.36.0                                       2022-08-28             Business::US::U...s::TrackConfirm(3pm)