crimulus-dot-com

If you’re a web developer and happen to develop software for use in e-commerce, chances are, somewhere along the lines you’ll need or want to integrate with the big 4 shippers’ (UPS, USPS, FedEx, DHL) APIs.  You’ll find right off the bat that they all offer rather robust APIs, so your options are sufficient.

Then you’ll get to programming and realize that the documentation is pretty crappy, but specifically I want to address the idiosyncrasies of the USPS “test” environment.  Effectively, what USPS means when they say “test” is not a test of robustness of your application, but simply whether or not your application can build a sample request (an EXACT sample request), and send it to their server.  Yeah — it’s like asking a math teacher to write the numbers 1 to 30 on a sheet of paper (in order) before he/she can get hired.

The problem is, the USPS docs don’t tell you this, nor do they show you the sample request.  So, for others who are about to embark on a few hour journey finding these details on Google (or worse, emailing USPS directly …eeek) I’m going to sum up a few facts here.

The most laborious for me so far is the one I already mentioned above.  For a rate request, the docs show you a RateV3Request, but in testing you can only use a RateV2 request (which does not support package dimensions).  Also, you must use the zip codes 10022 and 20008 for origination and zip, as well as 10 lbs. 5 oz. for the weight, and “LARGE” for the size.  Everything else (LAUGH) you have leeway with.

If you don’t use these exact values, you’ll get responses like “Please enter a valid zip code for the sender” (which of course makes you think you wrote the XML incorrectly) or “The package size must be ‘Regular’, ‘Large’, or ‘Oversize.’” (even though you have “regular” quite clearly in the request.

The advice is to get to production as soon as possible, though why USPS would design things this way is beyond me, but them’s the cards, you gotta play ‘em.

I will add more here as I find them obstaclicious enough (yeah I just made up that word).

Amendment 1:  I should add that the issues about the documentation not mentioning the “canned” requests is only applicable to the PDF documentation.  It is stated quite clearly in the HTML versions.  Go figure …