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