Laravel USPS: сучасний wrapper для USPS API

Laravel USPS від John Paul Medina — повнофункціональний пакет для Laravel, що обгортає USPS API v3 — сучасний REST/JSON API з автентифікацією OAuth2.

Пакет охоплює 20 API domains і понад 80 endpoints, зокрема валідацію адрес, відстеження посилок, створення shipping labels, розрахунок тарифів і планування carrier pickup. Під капотом він автоматично керує OAuth2-токенами, кешуючи їх приблизно на 50 хвилин, щоб зменшити зайві запити авторизації.

# Installation

composer require johnpaulmedina/laravel-usps

Опублікуйте файл конфігурації:

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

Потім додайте свої USPS OAuth2 облікові дані в .env. Отримати їх можна в USPS Developer Portal:

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

# Address Validation

Валідація адрес — один із найпоширеніших сценаріїв. Фасад Usps надає метод validate(), який приймає простий масив полів адреси й повертає стандартизовану, виправлену адресу разом із підтвердженням DPV (Delivery Point Validation):

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

У разі успіху відповідь містить виправлену адресу й додаткову інформацію Delivery Point Validation (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 — адреса не є дійсним пунктом доставки.

Якщо до поданої адреси були внесені виправлення, у відповіді також з'явиться ключ corrections.

# Input Normalization

Усі вхідні дані автоматично нормалізуються перед відправленням у USPS API — назви штатів (включно з територіями та військовими кодами) конвертуються в дволітерні абревіатури, ZIP+4 розділяється на складові, назви країн — у ISO alpha-2, а дати приводяться до формату ISO 8601:

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

Для зворотного пошуку — отримати місто й штат за ZIP-кодом — є метод cityStateLookup():

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

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

# Package Tracking

Відстеження реалізоване через fluent sub-client. Викличте 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"
    }
}

Якщо потрібно підписати email-сповіщення для відправлення, той самий екземпляр Tracking має метод registerNotifications(), який приймає номер відстеження та налаштування повідомлень.

# Artisan Commands

Пакет постачається з кількома зручними 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

Валідація адрес і трекінг — лише дві з двадцяти domain-ів API, які підтримує пакет. Також можна генерувати domestic і international shipping labels, розраховувати тарифи, планувати carrier pickups, керувати dispute-ами та інше — усе через той самий фасадний інтерфейс.

Вихідний код на GitHub, а повна документація доступна на johnpaulmedina.github.io/laravel-usps.