Laravel USPS: USPS API 的现代封装

John Paul Medina 开发的 Laravel USPS 是一个功能齐全的 Laravel 包，它封装了 USPS API v3 —— 一个现代化的、通过 OAuth2 进行身份验证的 REST/JSON API。

该包涵盖 20 个 API 领域和 80 多个端点，包括地址验证、包裹追踪、发货标签、定价和承运商取件安排。在后台，它会自动处理 OAuth2 令牌管理，将令牌缓存大约 50 分钟，以减少不必要的身份验证请求。

安装

composer require johnpaulmedina/laravel-usps

发布配置文件：

php artisan vendor:publish --tag=usps-config

然后将你的 USPS OAuth2 凭据添加到 .env 文件中。你可以从 USPS 开发者门户获取这些凭据：

USPS_CLIENT_ID=your-client-id
USPS_CLIENT_SECRET=your-client-secret

验证地址

地址验证是最常见的用例之一。美国邮政服务（USPS）的门面（facade）提供了一个 validate() 方法，该方法接受一个地址字段的普通数组，并返回一个标准化、已更正的地址以及递送点验证（Delivery Point Validation，DPV）确认：

use Johnpaulmedina\Usps\Facades\Usps;
 
$result = Usps::validate([
    'Address' => '78 NW 37th St',
    'City'    => 'Miami',
    'State'   => 'FL',
    'Zip'     => '33127',
]);

如果操作成功，响应将包含更正后的地址以及额外的交货点验证（DPV）信息：

{
    "address": {
        "Address2": "78 NW 37TH ST",
        "City": "MIAMI",
        "State": "FL",
        "Zip5": "33127",
        "Zip4": "3178"
    },
    "additionalInfo": {
        "deliveryPoint": "00",
        "carrierRoute": "C000",
        "DPVConfirmation": "Y",
        "DPVCMRA": "N",
        "business": "N",
        "centralDeliveryPoint": "N",
        "vacant": "N"
    }
}

DPVConfirmation 用于确认地址是否为美国邮政服务（USPS）的实际可投递地点：Y 表示完全匹配，D 表示缺少次级单元（公寓/套房），S 表示次级单元不匹配，N 表示地址不是有效的投递点。

如果对提交的地址进行了更正，则响应中也会包含一个更正密钥。

输入规范化

所有输入在发送至 USPS API 之前都会自动进行规范化处理——州名（包括领地和军事代码）转换为两个字母的缩写，ZIP + 4 字符串拆分为各个组成部分，国家名称转换为 ISO alpha-2 代码，日期规范化为 ISO 8601 格式：

sps::validate([
    'Address' => '78 NW 37th St',
    'City'    => 'Miami',
    'State'   => 'Florida',      // converted to 'FL'
    'Zip'     => '33127-3178',   // split into Zip5: 33127, Zip4: 3178
]);

对于反向查找——即从邮政编码获取城市和州——可以使用 cityStateLookup() 函数：

$result = Usps::cityStateLookup('33127');

{
    "city": "MIAMI",
    "state": "FL",
    "zip": "33127"
}

包裹追踪

通过流畅的子客户端访问追踪功能。在 Facade 上调用 tracking() 以获取一个 Tracking 实例，然后使用一组追踪请求对象调用 track()。美国邮政服务（USPS）API 支持在单个请求中最多处理 35 个包裹：

$result = Usps::tracking()->track([
    ['trackingNumber' => '9400111899223456789012'],
    ['trackingNumber' => '9400111899223456789099'],
]);

回复中包含每批货物的当前状态、位置和配送信息：

{
    "trackingNumber": "9400111899223456789012",
    "status": "Delivered",
    "statusSummary": "Your item was delivered at 11:23 am on March 28, 2026 in MIAMI, FL 33127.",
    "trackSummary": {
        "event": "Delivered, Front Door/Porch",
        "eventDate": "March 28, 2026",
        "eventTime": "11:23 am",
        "eventCity": "MIAMI",
        "eventState": "FL",
        "eventZIPCode": "33127"
    }
}

如果你需要为某一货件注册电子邮件通知，则同一个 Tracking 实例中有一个 registerNotifications() 方法，该方法接受跟踪号和通知偏好设置。

Artisan 命令

该包附带了一系列便捷的 Artisan 命令，无需编写任何代码即可快速查找：

# Validate an address
php artisan usps:validate "78 NW 37TH ST" --state=FL --zip=33127
 
# Track a package
php artisan usps:track 9400111899223456789012
 
# Look up a ZIP code
php artisan usps:zip 33127

地址验证和跟踪只是该软件包涵盖的二十个 API 领域中的两个。你还可以生成国内和国际运输标签、计算运费、安排承运商取件、管理纠纷等——所有这些都可以通过同一个基于外观的界面完成。
你可以在 GitHub 上找到源代码，并在 johnpaulmedina.github.io/laravel-usps 上查看完整文档。