PrestashopModules/usps_api_bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
89111d6e1e737ec230e4117576068567672c1f6b
usps_api_bridge/README.md
O K eb8c9fe18b add readme
2025-12-07 12:44:55 +02:00

4.8 KiB
Raw Blame History

USPS API Bridge (OAuth2) for PrestaShop

Overview

This module acts as a "Sidecar" or "Bridge" for the legacy ZH USPS Labels (zh_uspslabels) module.

The Problem: The legacy module relies on the deprecated USPS Web Tools API (XML/User+Pass), which is being retired in favor of the new USPS Connect API (JSON/OAuth2). The original developer is unresponsive.

The Solution: This module installs a PrestaShop Override that intercepts rate calculation requests destined for the old module. It routes them through this bridge, authenticates via OAuth2, queries the new USPS v3 API, and returns the rates to the cart seamlessly. It leaves the complex EasyPost logic (Label generation, Manifests) untouched.

Prerequisites

  • PrestaShop Version: 1.7.x or 8.x.
  • Legacy Module: zh_uspslabels must be installed and active. Do not uninstall it; this bridge relies on its database tables (ps_uspsl_box, ps_uspsl_method) and packing logic.
  • USPS Account: A registered account on the USPS Developer Portal.

Installation

  1. Upload:

    • Zip the usps_api_bridge folder.
    • Upload via Module Manager in the Back Office.
    • Alternatively: FTP the folder to /modules/usps_api_bridge/.

  2. Install:

    • Click Install.
    • CRITICAL: Upon installation, the module attempts to copy a file to /override/modules/zh_uspslabels/zh_uspslabels.php. Ensure your file permissions allow this.

  3. Clear Cache:

    • Go to Advanced Parameters > Performance and click Clear Cache.
    • Manual Step: If the bridge does not seem to work, manually delete /var/cache/prod/class_index.php (or /cache/class_index.php on older PS versions) to force PrestaShop to register the new override.

Configuration

Go to Module Manager > USPS API Bridge > Configure.

1. Credentials

You cannot use your old Web Tools username (e.g., 123XY...). You must generate new OAuth keys:

  1. Log in to developer.usps.com.
  2. Go to Apps -> Add App.
  3. Important: In the API Products list, ensure you select:
    • Prices (Domestic)
    • International Prices
    • OAuth 2.0
  4. Copy the Consumer Key (Client ID) and Consumer Secret.
  5. Paste them into the module configuration.

2. Deployment Settings

  • Live Mode:
    • No: Uses https://apis-tem.usps.com (Test Environment).
    • Yes: Uses https://apis.usps.com (Production).
    • Note: Your USPS App must be approved for Production access for Live Mode to work.
  • Debug Allowed IPs:
    • Highly Recommended for Testing: Enter your IP address here (comma-separated for multiple).
    • If set, ONLY visitors from these IPs will use the new API logic. Real customers will continue using the old module logic (until the USPS cutoff date).
    • Leave empty to go live for everyone.
  • Enable Logging: Logs all API requests/responses to Advanced Parameters > Logs.

Architecture & Logic flow

  1. The Interceptor:

    • The module overrides Zh_UspsLabels::getPackageShippingCost.
    • It checks if usps_api_bridge is active and if the user's IP is allowed.
    • If matched, it stops the legacy CarrierHelper -> RateService execution chain (which uses the broken XML API).

  2. The Bridge:

    • It retrieves the active Boxes and Methods from the old module's database tables.
    • It re-uses the old module's BoxPacker logic to determine how many packages are needed.
    • It maps the legacy Service Codes (e.g., USA_1) to new USPS Enums (e.g., PRIORITY_MAIL).
    • It authenticates via /oauth2/v3/token (caching the token for 1 hour).
    • It sends a JSON payload to /rates/v3/calculate.

  3. EasyPost:

    • Logic regarding Label Printing, Tracking, and Manifests handled by EasyPost is not touched. This traffic flows through the original module files as normal.

Troubleshooting

"API Connection Failed" in Config

If you click "Test Connection" in the legacy module and it fails:

  • Ensure the Bridge module is active.
  • Ensure your IP is in the "Debug Allowed IPs" list.
  • The Bridge intercepts the test click; check the PrestaShop Logs for the specific error message from the new API.

Rates are $0.00 or Not Showing

  1. Enable Logging in the bridge module.
  2. Check Advanced Parameters > Logs.
  3. Common Errors:
    • 401 Unauthorized: Your Client ID/Secret is wrong, or you selected the wrong environment (Live vs Test).
    • 400 Bad Request: Usually due to invalid Zip Codes (USPS v3 requires 5-digit Zips for domestic) or invalid Enum mappings.

Uninstalling

If you uninstall this module, the Override is removed, and the shop reverts entirely to the legacy XML API code.