# USPS Shipping API v1.1.0 - Platphorm News Network

> Production-ready USPS REST API v3 for e-commerce. Real-time domestic and international shipping rates with JA4+ fingerprinting, QuickBooks integration, and multi-language support.

## Service URLs

- **Primary**: https://shipments.platphormnews.com
- **VanAgain Alias**: https://vanagain-ship.platphormnews.com
- **MCP Hub**: https://mcp.platphormnews.com/api/docs
- **USPS Developer APIs**: https://developers.usps.com/apis
- **QuickBooks API**: https://developer.intuit.com/app/developer/qbo/docs/api

## About

Production USPS shipping API for e-commerce integration. Features include:
- Real-time domestic and international shipping rates
- Dimensional weight and oversized package calculations
- Customs form support (CN22/CN23) for 180+ countries
- JA4+ HTTP fingerprinting for security and tracing
- QuickBooks API integration ready
- Platphorm MCP protocol support
- Multi-language UI (English, Spanish, French, German, Japanese)
- Dark mode support
- Comprehensive JSON-LD structured data for SEO/AEO/GEO
- 80+ automated tests for reliability

## MCP Tools Available

This service is registered with Platphorm MCP Hub (mcp.platphormnews.com):

### calculate_shipping_rates
Calculate USPS shipping rates with dimensional weight support.

Input:
- destinationZip (required): 5-digit US ZIP code
- weight (required): Package weight in pounds (max 70)
- length, width, height (optional): Dimensions in inches
- mailClass (optional): ALL, USPS_GROUND_ADVANTAGE, PRIORITY_MAIL, PRIORITY_MAIL_EXPRESS

### track_shipment
Get tracking information for a USPS shipment.

Input:
- trackingNumber (required): USPS tracking number

### create_shipment
Create a shipment and generate labels (requires ShipRush API key).

Input:
- recipient: { name, address1, city, state, zip }
- packages: [{ weight, length, width, height }]
- service: USPS service type

## API Endpoints

### Core
- POST /api/v1/rates/calculate - Calculate shipping rates
- GET /api/v1/tracking/{trackingNumber} - Track shipment
- POST /api/v1/shipments - Create shipment

### Monitoring
- GET /api/health - Service health with USPS connection status
- GET /api/v1/audit - Request audit logs with JA4+ fingerprints
- GET /api/v1/tests - Run comprehensive test suite

### Documentation
- GET /api/docs - OpenAPI 3.0 specification

## Rate Calculation Example

```http
POST /api/v1/rates/calculate
Content-Type: application/json

{
  "destinationZip": "90210",
  "weight": 2.5,
  "length": 12,
  "width": 8,
  "height": 6
}
```

Response includes rates for all USPS services sorted by price.

## Query Parameters

- `?zip=90210` - Override destination ZIP (quick lookup)
- `?cartId=abc123` - Link to VanAgain cart for address resolution
- `?format=xml` - Return XML instead of JSON

## Security

### JA4+ Fingerprinting
All requests generate JA4+ HTTP fingerprints for:
- Bot detection and blocking
- Request correlation and tracing
- Audit logging

### Environment Separation
- Default: Staging USPS sandbox
- Production: Requires admin authentication header

## Mail Classes

| Class | Delivery | Best For |
|-------|----------|----------|
| USPS_GROUND_ADVANTAGE | 2-5 days | Economy shipping |
| PRIORITY_MAIL | 1-3 days | Standard shipping |
| PRIORITY_MAIL_EXPRESS | 1-2 days | Urgent orders |

## Dimensional Weight

For packages over 1 cubic foot, USPS uses dimensional weight:
- Formula: (L x W x H) / 166
- Effective weight = max(actual weight, dim weight)
- Rounded UP to nearest pound

## Integration Points

- USPS REST API v3 (OAuth 2.0)
- ShipRush (labels, multi-carrier)
- Platphorm MCP Hub (tool discovery)
- VanAgain WordPress/WooCommerce

## Environment Variables

Required:
- USPS_CLIENT_ID - USPS Developer Portal credentials
- USPS_CLIENT_SECRET

Optional:
- ORIGIN_ZIP (default: 98155 - Seattle warehouse)
- USPS_ENVIRONMENT (staging/production)
- SHIPRUSH_API_KEY
- ADMIN_PASSWORD

## Links

- **API Primary**: https://shipments.platphormnews.com
- **VanAgain Alias**: https://vanagain-ship.platphormnews.com
- **Platphorm MCP Docs**: https://mcp.platphormnews.com/api/docs
- **USPS Developer APIs**: https://developers.usps.com/apis
- **QuickBooks API**: https://developer.intuit.com/app/developer/qbo/docs/api
- **Platphorm News**: https://platphormnews.com
- **VanAgain Store**: https://vanagain.com

## Contact

Platphorm News Network
Michael@barbineworldwide.com
LinkedIn: https://www.linkedin.com/in/michaelbarbine
Twitter: https://twitter.com/bignerdlolz
GitHub: https://github.com/mbarbine