Laravel USPS 约翰·保罗·梅迪纳 是一个功能齐全的 Laravel 包，封装了 USPS API v3——一个现代化的 OAuth2 认证 REST/JSON API。
该软件包涵盖 20 个 API 域和 80 多个端点，包括地址验证、包裹跟踪、运单标签、定价和承运商取件安排。其底层可自动处理 OAuth2 令牌管理，并将令牌缓存约 50 分钟，以减少不必要的身份验证请求。
安装
作曲家
要求
johnpaulmedina/laravel-usps发布配置文件：
php
工匠
供应商：发布
--tag=usps-config然后添加您的 USPS OAuth2 凭据
.env
您可以从美国邮政服务开发者门户网站获取这些信息：
USPS_CLIENT_ID
=您的客户IDUSPS_CLIENT_SECRET
=您的客户端密钥地址验证
地址验证是最常见的应用场景之一。
Usps
立面暴露了
validate()
该方法接受一个地址字段的普通数组，并返回一个标准化的、更正后的地址以及 DPV（投递点验证）确认信息：
使用
Johnpaulmedina\Usps\Facades\Usps
;$结果
=
美国邮政
::
证实
（[
'地址'
=>
'西北第37街78号'
,
'城市'
=>
'迈阿密'
,
'状态'
=>
'在'
,
'拉链'
=>
'33127'
,]);成功后，响应中将包含更正后的地址以及其他投递点验证 (DPV) 信息：
{
“地址”
：{
“地址2”
:
“西北第37街78号”
,
“城市”
:
“迈阿密”
,
“状态”
:
“FL”
,
“Zip5”
:
33127
,
“Zip4”
:
3178}，
"附加信息"
：{
“交付点”
:
"00"
,
“运营商路线”
:
“C000”
,
“DPVC确认”
:
“和”
,
“DPVCMRA”
:
“N”
,
“商业”
:
“N”
,
“中央交付点”
:
“N”
,
“空缺”
:
“N”}}DPVConfirmation
确认该地址是否为美国邮政服务 (USPS) 可投递的真实地址：
Y
完整比赛，
D
如果缺少附属单元（公寓/套房），
S
如果辅助单元不匹配，并且
N
如果地址不是有效的收货地址。
如果提交的地址有误，
corrections
密钥也会出现在响应中。
输入归一化
所有输入在发送到 USPS API 之前都会自动规范化——州名（包括领土和军事代码）转换为双字母缩写，ZIP+4 字符串拆分为其组成部分，国家/地区名称转换为 ISO alpha-2 代码，日期规范化为 ISO 8601 格式：
美国邮政
::
证实
（[
'地址'
=>
'西北第37街78号'
,
'城市'
=>
'迈阿密'
,
'状态'
=>
'佛罗里达'
,
// 已转换为 'FL'
'拉链'
=>
'33127-3178'
,
// 拆分为 Zip5：33127，Zip4：3178]);对于反向查找——即根据邮政编码获取城市和州——有以下几种方法：
cityStateLookup()
:
$结果
=
美国邮政
::
城市州查找
（
'33127'
（英文）：{
“城市”
:
“迈阿密”
,
“状态”
:
“FL”
,
“拉链”
:
33127}包裹追踪
跟踪功能通过 Fluent 子客户端访问。调用
tracking()
在立面上获得
Tracking
实例，然后调用
track()
包含一系列跟踪请求对象。USPS API 在单个请求中最多支持 35 个货件：
$结果
=
美国邮政
::
追踪
（）
->
追踪
（[[
'追踪号码'
=>
'9400111899223456789012'
]，[
'追踪号码'
=>
'9400111899223456789099'
]，]);回复内容包括每批货物的当前状态、位置和配送信息：
{
“追踪号码”
:
"9400111899223456789012"
,
“地位”
:
“发表”
,
状态摘要
:
“您的物品已于 2026 年 3 月 28 日上午 11:23 送达佛罗里达州迈阿密 33127。”
,
“trackSummary”
：{
“事件”
:
“送货上门/送至门廊”
,
“eventDate”
:
2026年3月28日
,
“事件时间”
:
上午 11:23
,
“eventCity”
:
“迈阿密”
,
“eventState”
:
“FL”
,
“eventZIPCode”
:
33127}}如果您需要注册货运电子邮件提醒，同样适用。
Tracking
实例具有
registerNotifications()
该方法接受跟踪号码和通知偏好设置。
工匠指令
该软件包附带了一些便捷的 Artisan 命令，无需编写任何代码即可快速查找：
# 验证地址php
工匠
usps：验证
“西北第37街78号”
--state=FL
--zip=33127# 追踪包裹php
工匠
usps:track
9400111899223456789012查找邮政编码php
工匠
usps:zip
33127地址验证和跟踪只是该软件包涵盖的二十个 API 领域中的两个。您还可以生成国内和国际货运标签、计算运费、安排承运商取件、管理纠纷等等——所有操作均可通过同一个基于外观的界面完成。
您可以在以下位置找到来源： GitHub 完整文档请见此处。 johnpaulmedina.github.io/laravel-usps 。
