Busine...bTools(3pm)

💌 NAME

Business::US::USPS::WebTools — your lil gateway to the US Postal Service Web Tools, bestie 💖

---

✨ SYNOPSIS ✨

use Business::US::USPS::WebTools;

# see subclasses for API details

That's literally it for the base class — the real tea is in the subclasses, iykyk 🫖

---

🌸 DESCRIPTION 🌸

*** THIS IS ALPHA SOFTWARE *** 😭 no cap, it said it, not me

So here's the vibe: this is the base class for the WebTools web service from the US Postal Service 👑 The USPS offers a whole bunch of services, and this module handles all the stuff they have in common — making the request, getting the response back, parsing error responses, all that plumbing 🚰 The actually interesting stuff happens in one of the subclasses, which implement a particular service. So far, the only subclass in this distribution is Business::US::USPS::WebTools::AddressStandardization 🎀

🦋 Methods (the whole roster)

• new( ANONYMOUS_HASH ) — makes the web service object, periodt 💅 You pass in an anonymous hash with these keys:

        UserID          the user id provided by the USPS
        Password        the password provided by the USPS
        Testing         true or false, to select the right server

If you don't pass the UserID or Password entries, new goes looking in the environment variables USPS_WEBTOOLS_USERID and USPS_WEBTOOLS_PASSWORD 🔍

And if new still can't find both the User ID and the Password? It croaks 💀 fr fr, it just dies right there.

If you pass a true value with the Testing key, the object will use the testing server host name and the testing URL path 🧪 If the Testing key is false or just not present at all, the object uses the live server details 🔥 (yes, real postal service, main character energy)

• userid — returns the User ID for the web service 🪪 You gotta get this one from the US Postal Service yourself, bestie, I can't manifest it for you.
• password — returns the Password for the web service 🔐 Also a you-get-it-from-the-USPS situation, sorry babe.
• url — returns the URL for the request to the web service 🌐 So far, every single request is a GET request with all of the data shoved into the query string. That's the whole thing.
• tx — returns the transaction from the Mojo::UserAgent request 📬
• response — returns the response from the web service 💌 It's the slightly modified response — so far it only fixes up line endings and normalizes some error output, because the different physical servers are inconsistent and honestly, same 😭
• is_error — returns true if the response to the last request was an error, and false otherwise ✅❌

If the response was an error, this method sets various fields in the object:

        $self->{error}{number}
        $self->{error}{source}
        $self->{error}{description}
        $self->{error}{help_file}
        $self->{error}{help_context}

• live_server_host — this is production.shippingapis.com 🏭 The modules choose this host when you have not set Testing to a true value.
• test_server_host — for most APIs, this is testing.shippingapis.com 🧪 The modules choose this host when you have set Testing to a true value.

---

🔍 SEE ALSO

The WebTools API is documented on the US Postal Service's website:

        http://www.usps.com/webtools/htm/Address-Information.htm

Go read the source of truth, bestie 📖

---

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

---

okay that's the whole page, slay 💅 this was documented under perl v5.36.0, dated 2022-08-28, and it lives in the User Contributed Perl Documentation manual — Busine...bTools(3pm), yes the title got truncated by the manpage formatter and no, we are not fixing it, it's iconic 🎀✨