By Lance Robinson - Technical Evangelist, /n software.
Requirements: /n software USPS Integrator

Introduction

USPS Integrator is a toolkit that enables software developers to quickly and easily incorporate USPS shipping capabilities into their software applications and websites.  The toolkit includes updates for the 2007 United States Postal Service rate changes.  IBiz USPS Integrator includes the following components:

Shipping Label Generation:

• ConfirmationLabels component: Used to generate delivery or signature confirmation labels for all domestic mail services (Priority Mail, First Class, Parcel Post, etc). Currently USPS only offers electronically generated Priority Mail labels with either signature or delivery confirmation, however there is no extra cost for delivery confirmation (electronic option rate).
• CustomsLabels component: Generates the customs forms needed for international shipments where you have a pre-paid label (ie, acquired from Pitney-Bowes), when shipping surface (sea) mail, or when shipping to APO/FPO addresses.  Labels will be complete with addresses, barcodes, and customs declarations.            
• InternationalLabels component (formerly the GlobalExpressLabels component): Generates shipping labels and customs forms needed for international shipments via International Priority, Express, and First Class mail.
• ExpressLabels component: Generates a USPS Express Mail shipping label and optionally a customer online record.
• ReturnLabels component: Generates a printable electronic merchandise return label ("No postage necessary if mailed in the United States").

Rate Retrieval:

• DomesticRates component: Used to retrieve dimensional rate information that USPS started implementing in May 2007 for all US mail. The component provides online automated access to rates based on weight, size, class, and origin/destination for Express Mail, First-Class Mail, and Priority Mail, as well as single-piece rates for package services Parcel Post, Bound Printed Matter, Library Mail, and Media Mail.
• InternationalRates component: Used to retrieve new International shipping rate information for the new International shipping services USPS started implementing in May 2007.

Shipment Delivery Estimation, Tracking, and Scheduling, and Address Verification:

• AddressInfo component: Used to verify and standardize a customer address, lookup zip codes and city/states.
• CarrierPickup component: Used to submit an electronic pickup request (a mail carrier will pickup your package at your door when s/he arrives for regular delivery).
• ShippingTime component: Provides estimated shipping times between two zip codes.
• TrackAndConfirm component: Checks delivery status of any package sent via a trackable service. This includes Express Mail, Delivery Confirmation, Signature confirmation, and all International shipments.

Getting Started

Registration with USPS

Before you can use these components to communicate with the US Postal Service, you must register with USPS for access to their WebTools APIs. Online registration is free and provides developers with a unique username that must be used when accessing shipping services. To register for your free username visit: http://www.uspswebtools.com/registration/ .

Connecting to USPS

After you register your account with USPS, you'll have access to their test servers, which support only "canned" tests, meaning that the test servers will only accept certain request data.  This test data is included in the USPS demos.  After you are ready to go live, you'll need to contact the USPS Internet Customer Care Center and request access to the live production server, where you'll be able to use real input data.  Note:  if you plan to use delivery/signature confirmation (ConfirmationLabels) or merchandise return service (ReturnLabels), you'll also need to contact the USPS National Customer Support Center ((800) 279-2651) to certify your actual printed labels, they will need to know you are an Internet customer using their Webtools services.

For a list of test and live urls, see the section at the end of this tutorial entitled "A Note on Server URLs".

Your typical online retailer needs to ship items to his customers, and this simple task involves several steps:

1. Get the customer's shipping address (and optionally verify it with USPS).
2. Allow the customer to choose what type of shipping to use, and show the cost and delivery time of each choice.
3. Print a shipping label for the package.
4. Provide the customer with a shipment tracking number.
5. Schedule a mail carrier to pick up the package.
6. Give the package to the carrier.

Now here is how we can implement each of these tasks.

1.  Get the customer's shipping address (and optionally verify it with USPS).

After you get the customers shipping address, you may choose to verify that address with USPS.  Address verification is not required, and most merchants do not need this feature.  If you want to implement address verification, doing so will require special permission from USPS, and USPS will have to specifically activate the address information feature on your account.

The AddressInfo component allows you to verify a complete address (LookupAddress() method), lookup a zip code of a city/state(LookupZip() method), and lookup the city/state of a zip code (LookupCityState() method).  Here is an example of using the LookupAddress method to verify ("standardize") an address:

  AddressInfo1.Server = "https://production.shippingapis.com/ShippingAPI.dll";
  AddressInfo1.UserId = yourusername;  
  AddressInfo1.AddressLine2 = "6406 Ivy Lane";
  AddressInfo1.City = "Greenbelt";
  AddressInfo1.State = "MD";
  AddressInfo1.LookupAddress();

Here is the address I want to verify...	Now the address is verified and standardized.

2.  Allow the customer to choose what type of shipping to use, show them the cost and estimated delivery time of each choice.

Now that you have a shipping address from the customer, you can retrieve the cost of delivery and an estimated time of delivery using the DomesticRates (or InternationalRates for international shipments) and ShippingTime components.

To determine the postage rate to ship a regular sized package from my zip code (27502) to the sample address used in the earlier example (20770), I can use the following code:

  DomesticRates1.Server = "http://production.shippingapis.com/ShippingAPI.dll";
  DomesticRates1.UserId = username;  
  DomesticRates1.FromZipCode = "27502";
  DomesticRates1.ToZipCode = "20770";
  DomesticRates1.PackagePounds = "1";
  DomesticRates1.PackageOunces = '4";
  DomesticRates1.PackageSize = psRegular; //0
  DomesticRates1.ServiceType = svcAll; //7, show all service type costs
  DomesticRates1.PackageLength = 8
  DomesticRates1.PackageWidth = 6
  DomesticRates1.PackageHeight = 6
  DomesticRates1.CalculatePostage();

Note that package length, width, and height are required for large packages, but it is okay to send them for all package sizes

Again, here I would use the InternationalRates component if I were shipping internationally.  Note the setting of the PackageSize and ServiceType properties.  Rates depend on location (from and to), size and dimensions, weight, container (envelope, box, etc), and service type.  (Package length width and height are not required for the psRegular package size, but it is okay to send them. They are required for all other package sizes). Available service types are Priority Mail, First Class, Parcel Post, Bound Printed Matter, Media Mail, Library Mail, or Express Mail.  The ServiceType property has an "all" setting that will tell the component to retrieve rates for all available service types.

Package sizes are defined by USPS as follows:

• Regular, which is defined as:
  Priority Mail: less than one cubic foot in size
  All other service types: length plus girth is 84 inches or less
• Large, which is defined as:
  Priority Mail: greater than one cubic foot in size
  All other service types: length plus girth is between 85 and 108 inches.
• Oversize, which is defined as having a length plus girth of between 109-130 inches.

To compute the shipping time, use the ShippingTime component and simply provide the from zip, the destination zip, and the service type:

  ShippingTime1.Server = "http://production.shippingapis.com/ShippingAPI.dll";
  ShippingTime1.UserId = username;  
  ShippingTime1.ServiceType = stPriority; //0, priority mail
  ShippingTime1.GetShippingTime("27502", "20770");

3.  Print a shipping label for the package.

Use one of the Labels components to generate a shipping label for your package.  The components will generate labels in TIF, JPG, PDF, or GIF formats for your printing convenience.  The Labels components consist of:

• ExpressLabels - use this to generate shipping labels for Express Mail.
• ConfirmationLabels - use this to generate shipping labels for other mail domestic service types.
• CustomsLabels - use this to generate shipping labels for APO/FPO packages.
• InternationalLabels - use this to generate shipping labels for international mail services.
• ReturnLabels - use this to generate an electronic merchandise return label, for use by the customer to return packages to the merchant without postage.

For shipping inside the US, ExpressLabels and ConfirmationLabels are the most commonly used.  For this example I'll use the ConfirmationLabels component which can generate shipping labels for Priority Mail, First Class Mail, Parcel Post, Bound Printer Matter, Media Mail, and Library Mail.

  ConfirmationLabels1.UserId = username;  
  ConfirmationLabels1.Server = "https://secure.shippingapis.com/ShippingAPI.dll";
  ConfirmationLabels1.Config ("Certify=true");
  ConfirmationLabels1.FromName = "John Smith";
  ConfirmationLabels1.FromAddress2 = "475 L'Enfant Plaza, SW";
  ConfirmationLabels1.FromCity = "Washington";
  ConfirmationLabels1.FromState = "DC";
  ConfirmationLabels1.FromZipCode = "20260";
  ConfirmationLabels1.ToName = "Jane Smith";
  ConfirmationLabels1.ToAddress2 = "8 Wildwood Drive";
  ConfirmationLabels1.ToCity = "Old Lyme";
  ConfirmationLabels1.ToState = "CT";
  ConfirmationLabels1.WeightInOunces = 2;
  ConfirmationLabels1.ServiceType = stPriority; //0, Priority Mail
  ConfirmationLabels1.ImageType = stTif; //1, TIF file
  ConfirmationLabels1.ShippingLabelFile = "delivery_confirm.tif";
  ConfirmationLabels1.GetDeliveryConfirmationLabel();
  //I could also use the GetSignatureConfirmationLabel() method to generate a 
  //label that will require a signature upon delivery

After the call to GetDeliveryConfirmationLabel, you'll have a file called delivery_confirm.tif that you can print, that looks something like the one pictured at right.  Affix this label to your package along with postage and it is ready to go. 

To see an example of a label generated by GetSignatureConfirmationLabel(), click here.

4.  Provide the customer with a shipment tracking number.

The Labels component that you use in step 3 will provide you with a tracking number automatically.  The ConfirmationLabels, ExpressLabels, InternationalLabels, and ReturnLabels components all have a TrackingNumber property where this information is provided.  The CustomsLabels (which again should only be used for APO/FPO deliveries or pre-paid labels) component contains a BarcodeNumber property used for tracking.

With this tracking number you can use the TrackAndConfirm component of USPS to retrieve information about the status of the shipment.  Certainly as far as the customer is concerned, they can just be directed to visit the USPS website and do their shipment tracking there.  But the TrackAndConfirm component would be particularly useful to the merchant for automatically confirming delivery of all packages sent.  Here is an example using the test server and a working test tracking number:

  //test server
  TrackAndConfirm1.Server = "http://testing.shippingapis.com/ShippingAPITest.dll";
  TrackAndConfirm1.UserId = username;  
  TrackAndConfirm1.GetDetailedTrackingInfo("EJ958083578US");
  //here I could also use the GetTrackingInfo() method,
  //which gets a textual description

5.  Schedule a mail carrier to pick up the package.

Now that the order process is complete, its time (hopefully) to actually ship the product to the customer.  To do this, you can walk down to the post office with the package, or you can save yourself some time and automatically schedule a mail carrier to come and pick up the package from your door.  To do this, use the CarrierPickup component to submit the package details and schedule a pickup.

First, check for the soonest available pickup date:

  //This is the test server. Please note that the test requests are pre-scripted
  //so modified requests may be rejected by the test server
  CarrierPickup1.Server = "https://secure.shippingapis.com/ShippingAPITest.dll";
  CarrierPickup1.UserId = username;  
  CarrierPickup1.FirmName = "ABC Corp.";
  CarrierPickup1.SuiteOrApartment = "Suite 777";
  CarrierPickup1.Address = "1390 Market Street";
  CarrierPickup1.City = "Houston";
  CarrierPickup1.State = "TX";
  CarrierPickup1.ZipCode = "77058";
  CarrierPickup1.Zip4 = "1234";
  CarrierPickup1.PickupAvailability();

After calling the PickupAvailability method, the DayOfWeek and Date properties of the component will be populated with the date of the soonest available pickup date.  If carrier pickup services are not supported for the merchant address, you'll have to visit the post office in person.

Now you can call the SchedulePickup method to go ahead and schedule a carrier pickup.  To do this, simply call the SchedulePickup() method.  You'll be required to first set some properties about the person requesting pickup and the package itself.  The example below will work with the test server (note: this is the USPS "canned" test data so if you change it the test will no longer work).

  //This is the test server. Please note that the test requests are pre-scripted
  //so modified requests may be rejected by the test server
  CarrierPickup1.Server = "https://secure.shippingapis.com/ShippingAPITest.dll";
  CarrierPickup1.UserId = username;  
  CarrierPickup1.FirmName = "ABC Corp.";
  CarrierPickup1.SuiteOrApartment = "Suite 777";
  CarrierPickup1.Address = "1390 Market Street";
  CarrierPickup1.City = "Houston";
  CarrierPickup1.State = "TX";
  CarrierPickup1.ZipCode = "77058";
  CarrierPickup1.Zip4 = "1234";
  CarrierPickup1.FirstName = "John";
  CarrierPickup1.LastName = "Doe";
  CarrierPickup1.PhoneNumber = "(555) 555-1234";
  CarrierPickup1.PhoneExtension = "201";
  //the number of packages being picked up for Express Mail
  CarrierPickup1.CountExpress = 1;
  //the number of packages being picked up for Priority Mail
  CarrierPickup1.CountPriority = 1;   
  //the number of packages being picked up for International Mail

  CarrierPickup1.CountInternational = 1;
  CarrierPickup1.CountOther = 1; //other packages
  CarrierPickup1.EstimatedWeight = "14"; //pounds
  CarrierPickup1.PackageLocation = plOther; //9, other
  CarrierPickup1.SpecialInstructions = "Packages are behind the screen door.";
  CarrierPickup1.SchedulePickup();

In the above example, all of the data is required as specified in order to work with the test server.  Once you have a live account and are ready to schedule a real pickup, change the Server URL to the production URL and specify only those properties that are required or that you need.  For a list of required pickup scheduling properties please see the USPS documentation of the SchedulePickup method.

The CarrierPickup component also gives you the means to inquire as to the status of a pickup, change a previously scheduled pickup, or cancel a previously scheduled pickup.

6.  Give the package to the carrier.

This is the easy part and requires no explanation.  All done, happy shipping!

Conclusions

This article demonstrates the ease of use of the USPS Integrator.  In this tutorial I've gone over some of the most commonly used components and uses, however if there are any questions you have that I've not covered here please do not hesitate to contact me via the link at the top or bottom of this tutorial.

A Note on Server URLs:

• AddressInfo, ShippingTime, TrackandConfirm, and the Rates component use the following servers:
  
  live: http://production.shippingapis.com/ShippingAPI.dll

• CarrierPickup
  
  live: https://secure.shippingapis.com/ShippingAPI.dll
  test: https://secure.shippingapis.com/ShippingAPITest.dll

• All of the Labels components use the following servers:
  
  live: https://secure.shippingapis.com/ShippingAPI.dll
  test: same url, but with a special "test mode" flag.  You can set this test mode flag using the USPS Integrator using the config setting "Certify=True" (ie, DomesticRates1.Config("Certify=True");).

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.