USPS 国际物流 API 文档

RESTful API · JSON 格式 · 仅支持美国本土 USPS 线路

概览

本平台提供美国本土 USPS 面单创建、订单管理、运单追踪、账户余额与 USDT 充值能力。当前仅支持 US（美国本土） 区域，承运商为 USPS。

Base URL: https://usps.qd.je
Content-Type: application/json
认证方式: Bearer Token（JWT） 或 HMAC-SHA256 签名（API Key + Secret Key）

认证方式

两种认证方式：
1. Bearer Token（JWT） —— 登录后获取，适用于网页端与快速测试，有效期 24 小时。
2. HMAC-SHA256 签名 —— 适用于服务端对接，更安全，推荐用于正式集成。

登录 公开

POST /api/auth/login 获取 JWT Token

请求

curl -X POST https://usps.qd.je/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your_username","password":"your_password"}'

成功响应

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "user": {
      "id": 1,
      "username": "your_username",
      "role": "user",
      "displayName": "客户名称"
    }
  }
}

之后在请求头中携带：Authorization: Bearer <token>

POST/api/auth/sms/send发送短信验证码公开

请求

curl -X POST https://usps.qd.je/api/auth/sms/send \
  -H "Content-Type: application/json" \
  -d '{"phone":"18778090403"}'

成功响应

{
  "success": true,
  "message": "验证码已发送"
}

验证码有效期 5 分钟，同一手机号 60 秒内只能发送一次。

POST/api/auth/register注册（短信验证）公开

请求

curl -X POST https://usps.qd.je/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "18778090403",
  "code": "123456",
  "username": "newuser",
  "password": "123456",
  "displayName": "客户A"
}'

成功响应

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "user": {
      "id": 3,
      "username": "newuser",
      "role": "user",
      "displayName": "客户A",
      "phone": "18778090403"
    }
  }
}

注册成功后直接返回 Token，可立即登录使用。同一手机号/用户名不可重复注册。

HMAC-SHA256 签名 用于服务端对接

先登录并调用 POST /api/auth/api-keys 生成 API Key 与 Secret Key（Secret Key 仅创建时返回一次，请妥善保存）。

StringToSign = HTTP_METHOD + "\n" + 完整请求路径(含查询串) + "\n" + 毫秒时间戳 + "\n" + 请求体
Signature = HMAC-SHA256(SecretKey, StringToSign) → 小写十六进制

请求头：
  X-API-Key: 你的 API Key
  X-Timestamp: Date.now()（毫秒时间戳）
  X-Signature: 计算出的十六进制签名
签名要求：

账号与 API 密钥

GET/api/auth/me当前登录用户信息登录
curl https://usps.qd.je/api/auth/me -H "Authorization: Bearer <token>"
POST/api/auth/change-password修改密码登录
curl -X POST https://usps.qd.je/api/auth/change-password \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"oldPassword":"旧密码","newPassword":"新密码(至少6位)"}'
POST/api/auth/api-keys生成 API Key + Secret Key登录
curl -X POST https://usps.qd.je/api/auth/api-keys \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"label":"production-server"}'

响应

{
  "success": true,
  "data": {
    "apiKey": "sk-a1b2c3d4...",
    "secretKey": "f8e7d6c5...",
    "label": "production-server",
    "message": "请立即保存 Secret Key，之后不再显示。"
  }
}
GET/api/auth/api-keysAPI Key 列表登录

返回当前用户的 API Key 列表（不包含 Secret Key）。管理员可查看全部。

DELETE/api/auth/api-keys/:id撤销 API Key登录

停用指定 API Key。

GET/api/auth/users用户列表管理员

仅管理员可调用。

POST/api/auth/users创建用户管理员
curl -X POST https://usps.qd.je/api/auth/users \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"username":"newuser","password":"123456","role":"user","displayName":"客户A"}'

订单

承运商取值：usps。区域取值：us。

创建订单 登录

POST/api/orders/create创建面单并自动扣费

请求

curl -X POST https://usps.qd.je/api/orders/create \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{
  "provider": "usps",
  "region": "us",
  "sender": {
    "name": "Warehouse Manager",
    "phone": "+1-732-123-4567",
    "address": "600 Blair Rd",
    "city": "Carteret",
    "state": "NJ",
    "country": "US",
    "zipCode": "07008"
  },
  "receiver": {
    "name": "John Doe",
    "phone": "+1-212-555-0000",
    "address": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zipCode": "10001"
  },
  "parcels": [
    { "weight": 1.0, "length": 30, "width": 20, "height": 15, "packagingType": "02" }
  ],
  "serviceCode": "GROUND_ADVANTAGE",
  "reference": "ORDER-001"
}'

成功响应

{
  "success": true,
  "data": {
    "orderId": "SO20260813...",
    "trackingNumber": "9400...",
    "provider": "usps",
    "region": "us",
    "serviceCode": "GROUND_ADVANTAGE",
    "serviceName": "Ground Advantage",
    "chargeAmount": 15,
    "chargeCurrency": "USD",
    "balance": 985,
    "currency": "USD",
    "labelData": "base64...",
    "labelFormat": "GIF"
  }
}

订单列表 登录

GET/api/orders分页查询订单

可选查询参数：status（created/cancelled）、date、provider、region、username（管理员）、limit（默认 200）。普通用户只能看自己的订单。

curl "https://usps.qd.je/api/orders?limit=50" -H "Authorization: Bearer <token>"

订单详情 登录

GET/api/orders/:orderId查询单个订单
curl https://usps.qd.je/api/orders/SO20260813... -H "Authorization: Bearer <token>"

取消订单 登录

POST/api/orders/:orderId/cancel取消并退回费用
curl -X POST https://usps.qd.je/api/orders/SO20260813.../cancel \
  -H "Authorization: Bearer <token>"

获取面单 登录

GET/api/orders/:orderId/label返回 base64 面单

返回 JSON，含 labelData（base64）与 labelFormat（GIF/PDF）。

GET/api/orders/:orderId/label-image直接下载/预览面单图片

返回图片（GIF）或 PDF 二进制流，可直接在浏览器打开。

运费查询 登录

POST/api/orders/rate查询运费
curl -X POST https://usps.qd.je/api/orders/rate \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"provider":"usps","region":"us","sender":{...},"receiver":{...},"parcels":[...],"serviceCode":"GROUND_ADVANTAGE"}'

承运商列表 登录

GET/api/orders/meta/providers区域与承运商
{
  "success": true,
  "data": {
    "us": {
      "name": "USA",
      "currency": "USD",
      "providers": [
        { "id": "usps", "name": "USPS", "services": [...] }
      ]
    }
  }
}

运单追踪 登录

GET/api/tracking/:trackingNumber通用追踪
curl "https://usps.qd.je/api/tracking/940011189922..." -H "Authorization: Bearer <token>"
GET/api/tracking/usps/:trackingNumberUSPS 追踪
curl "https://usps.qd.je/api/tracking/usps/940011189922..." -H "Authorization: Bearer <token>"

账户与余额

GET/api/recharge/balance/:userId查询余额登录

普通用户只能查询本人，管理员可查询任意用户。返回余额、币种、可下单数量、用户统计。

GET/api/recharge/records充值/扣款记录登录

普通用户只看本人记录，管理员看全部。

GET/api/recharge/prices价格配置列表登录

返回各服务代码的价格。

POST/api/recharge/recharge管理员充值管理员
curl -X POST https://usps.qd.je/api/recharge/recharge \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"userId":2,"amount":100,"currency":"USD"}'
POST/api/recharge/deduct管理员扣款管理员
curl -X POST https://usps.qd.je/api/recharge/deduct \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"userId":2,"amount":10,"currency":"USD","reason":"手动扣款"}'
POST/api/recharge/prices设置价格管理员
curl -X POST https://usps.qd.je/api/recharge/prices \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"serviceCode":"GROUND_ADVANTAGE","serviceName":"Ground Advantage","zone":"default","price":15,"currency":"USD"}'
DELETE/api/recharge/prices/:id删除价格管理员

仅管理员可调用。

GET/api/recharge/customers客户列表管理员

返回所有用户（含余额、订单统计、可下单数量）。

USDT 充值

说明：无汇率换算。用户提交要充值的 USDT 金额，系统生成收款地址与二维码；用户转账到账后系统自动检测并确认到账、增加余额。
GET/api/usdt/info收款地址/网络公开

返回 USDT 收款地址与网络（TRC20）。

POST/api/usdt/deposit创建充值单登录
curl -X POST https://usps.qd.je/api/usdt/deposit \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"usdtAmount":100}'
POST/api/usdt/submit提交交易哈希登录
curl -X POST https://usps.qd.je/api/usdt/submit \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"depositId":"DEP...","txid":"链上交易哈希"}'
GET/api/usdt/deposits充值记录登录

可选 status（pending/submitted/confirmed/rejected）、limit。普通用户只看本人，管理员看全部。

POST/api/usdt/confirm确认到账管理员
curl -X POST https://usps.qd.je/api/usdt/confirm \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"depositId":"DEP..."}'
POST/api/usdt/reject拒绝充值管理员
curl -X POST https://usps.qd.je/api/usdt/reject \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"depositId":"DEP...","remark":"原因"}'
GET/api/usdt/inbound链上入账记录管理员

查看系统自动检测到的链上转账记录。

POST/api/usdt/scan立即触发链上扫描管理员

手动触发一次 TronGrid 链上扫描。

日志

GET/api/logs操作日志登录

可选 date、action、username、limit。普通用户只看本人。

GET/api/logs/stats今日统计登录

返回今日订单数、今日费用等。

错误码

状态码含义
200成功
400参数错误 / 余额不足 / 状态不允许
401未认证或 Token 无效（登录失败、签名错误）
403无权限（非管理员 / 非本人数据）
404资源不存在
500服务器内部错误

所有接口统一返回 { "success": true|false, "data": ..., "message": "..." } 结构。