add readme
This commit is contained in:
89
README.md
Normal file
89
README.md
Normal file
@@ -0,0 +1,89 @@
|
|||||||
|
# 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](https://developer.usps.com/).
|
||||||
|
|
||||||
|
## 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](https://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.
|
||||||
Reference in New Issue
Block a user