.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Business::US::USPS::WebTools::TrackConfirm 3pm"
.TH Business::US::USPS::WebTools::TrackConfirm 3pm "2021-05-20" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Business::US::USPS::WebTools::TrackConfirm \- track a shipment using the USPS Web Tools
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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}\en";
\&                }
\&        else {
\&                foreach my $hash ( reverse $hash\->{TrackDetail}\->@* ) {
\&                        say \*(Aq\-\*(Aq x 50;
\&                        say join "\en", map { "$_: $hash\->{$_}" }
\&                                qw(Event EventCity EventDate EventTime);
\&                        }
\&                }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
*** \s-1THIS IS ALPHA SOFTWARE\s0 ***
.PP
This module implements the Track & Confirm web service from the
\&\s-1US\s0 Postal Service. It is a subclass of Business::US::USPS::WebTools.
.IP "track( TrackID => \s-1VALUE\s0 )" 4
.IX Item "track( TrackID => VALUE )"
Although the \s-1USPS API\s0 allows to make multiple queries in a single
request, this method one queries only one.
.Sp
The \f(CW\*(C`track\*(C'\fR method takes the following keys, which come directly from
the \s-1USPS\s0 web service interface:
.Sp
.Vb 1
\&        TrackID   The tracking number
.Ve
.Sp
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 \s-1API\s0).
.Sp
If you want to see if something went wrong, check:
.Sp
.Vb 1
\&        $tracker\->is_error;
.Ve
.Sp
See the \f(CW\*(C`is_error\*(C'\fR documentation in Business::US::USPS::WebTools
for more details on error information.
.IP "tracking_number_regex" 4
.IX Item "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.
.Sp
The \s-1USPS\s0 shows the valid forms at
.Sp
.Vb 1
\&        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
.Ve
.IP "is_valid_tracking_number( \s-1ID\s0 )" 4
.IX Item "is_valid_tracking_number( ID )"
Returns a normalized version of the tracking number if \s-1ID\s0 looks like a
tracking number, based on the regex from \f(CW\*(C`tracking_number_regex\*(C'\fR.
Returns false otherwise.
.Sp
Normalizing \s-1ID\s0 merely removes all whitespace. Sometimes the \s-1USPS\s0 shows
the numbers with whitespace.
.IP "service_type( \s-1ID\s0 )" 4
.IX Item "service_type( ID )"
Returns the service type, based on the examples shown by the \s-1USPS\s0 and
shown in \f(CW\*(C`tracking_number_regex\*(C'\fR. I know this is wrong because I have
tracking numbers that don't have the same leading characters for
Priority Mail International.
.Sp
.Vb 12
\&        <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>"
.Ve
.IP "test_server_host" 4
.IX Item "test_server_host"
The testing \s-1API\s0 uses stg\-production.shippingapis.com instead of the
usual testing server.
.SH "TO DO"
.IX Header "TO DO"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Business::US::USPS::WebTools
.PP
The WebTools \s-1API\s0 is documented on the \s-1US\s0 Postal Service's website:
.PP
.Vb 1
\&        https://www.usps.com/business/web\-tools\-apis/track\-and\-confirm\-api.htm
.Ve
.SH "SOURCE AVAILABILITY"
.IX Header "SOURCE AVAILABILITY"
This source is in GitHub:
.PP
.Vb 1
\&        https://github.com/ssimms/business\-us\-usps\-webtools
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
brian d foy
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Steve Simms
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright © 2020, Steve Simms. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the Artistic License 2.0.