REST API

API 文档

使用我们强大的 REST API 将运输标签集成到您的应用程序中。实时获取费率、创建标签并以编程方式追踪货物。

身份验证

所有 API 请求都需要使用您的 API 密钥和密钥进行身份验证。在每个请求中包含以下标头：

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

安全提示

请妥善保管您的 API 密钥。切勿在客户端代码或公共仓库中暴露它。

请求示例

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

账户余额

查看您的加密货币钱包余额和交易历史。API 使用您的加密钱包（BTC、LTC、LTCT）进行支付。

GET

/api/v1/account/balance

获取加密钱包余额和交易

查询参数

参数	类型	必需	描述
includeTransactions	`boolean`	可选	包含交易历史
currency	`string`	可选	按货币筛选交易（BTC、LTC、LTCT）
limit	`number`	可选	交易数量（默认：20，最大：100）

请求示例

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

响应

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

充值

要为钱包充值，请访问我的钱包页面并使用 BTC、LTC 或 LTCT（测试网）存款。

地址验证

验证并标准化配送地址以确保可送达性。

POST

/api/v1/shipping/verify-address

验证并修正配送地址

请求体

参数	类型	必需	描述
address	`Address`	必需	要验证的地址
strict	`boolean`	可选	启用严格验证模式

请求示例

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

响应

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

运费费率

从多个承运商获取实时运费费率，包括 USPS、UPS、FedEx 和 DHL。

POST

/api/v1/shipping/rates

计算包裹的运费费率

请求体

参数	类型	必需	描述
fromAddress	`Address`	必需	发件人地址对象
toAddress	`Address`	必需	收件人地址对象
packageDetails	`Package`	必需	包裹尺寸和重量
carriers	`string[]`	可选	按特定承运商筛选（USPS、UPS、FEDEX、DHL）
customsInfo	`CustomsInfo`	可选	国际货运必需

地址对象

参数	类型	必需	描述
name	`string`	必需	全名
company	`string`	可选	公司名称
street1	`string`	必需	地址第 1 行
street2	`string`	可选	地址第 2 行
city	`string`	必需	城市
state	`string`	必需	州/省代码
zip	`string`	必需	邮政编码
country	`string`	必需	国家代码（US、CA 等）
phone	`string`	可选	电话号码
email	`string`	可选	电子邮件地址

包裹对象

参数	类型	必需	描述
length	`number`	必需	长度（英寸）
width	`number`	必需	宽度（英寸）
height	`number`	必需	高度（英寸）
weight	`number`	必需	重量（盎司）

CustomsInfo 对象

国际货运

国际运输时必需（当 fromAddress.country 与 toAddress.country 不同时）。

参数	类型	必需	描述
contents_type	`string`	必需	内容类型：documents、gift、merchandise、returned_goods、sample、dangerous_goods、humanitarian_donation、other
contents_explanation	`string`	可选	当 contents_type 为 'other' 时必需
customs_certify	`boolean`	必需	必须为 true - 证明申报的准确性
customs_signer	`string`	必需	签署海关申报单的人员姓名
eel_pfc	`string`	必需	出口豁免代码（价值低于 $2,500 的货物使用 'NOEEI 30.37(a)'）
non_delivery_option	`string`	必需	无法投递时的处理方式：'return' 或 'abandon'
restriction_type	`string`	必需	限制类型：'none'、'other'、'quarantine' 或 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	可选	当 restriction_type 不是 'none' 时必需
customs_items	`CustomsItem[]`	必需	运输物品数组（1-100 个物品）

CustomsItem 对象

参数	类型	必需	描述
description	`string`	必需	物品的详细描述
quantity	`number`	必需	物品数量（最小：1）
value	`number`	必需	美元价值（必须大于 0）
weight	`number`	必需	重量（盎司，必须大于 0）
origin_country	`string`	必需	2 字母国家代码（例如 'US'、'CN'）
hs_tariff_number	`string`	必需	6-10 位 HS 关税代码

请求示例

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

响应

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

国际运输示例

对于国际货运，请包含带有物品申报的 customsInfo 对象：

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

创建订单

创建和管理运输订单。订单包含一个或多个运输标签项目。

GET

/api/v1/orders

列出所有订单

POST

/api/v1/orders

创建新订单

GET

/api/v1/orders/{id}

获取订单详情

列出订单 - 查询参数

参数	类型	必需	描述
limit	`number`	可选	结果数量（默认：50，最大：100）
offset	`number`	可选	分页偏移量

创建订单 - 请求体

参数	类型	必需	描述
items	`OrderItem[]`	必需	订单项目数组
email	`string`	可选	客户邮箱
externalReference	`string`	可选	您的参考 ID

OrderItem 对象

简化 API

只需要 shipmentId 和 rateId。地址、包裹详情和海关信息会自动从货运中提取。

参数	类型	必需	描述
shipmentId	`string`	必需	来自费率端点的货运 ID
rateId	`string`	必需	来自费率端点的费率 ID

示例：创建订单

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

响应

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

购买标签

为订单中的所有物品购买运输标签。标签使用您的加密钱包余额（BTC、LTC 或 LTCT）购买。

POST

/api/v1/labels/purchase

为订单购买运输标签

请求体

加密货币支付

API 将按当前汇率将标签成本从美元转换为加密货币。您必须有足够的余额（包括 10% 的价格波动缓冲）。

参数	类型	必需	描述
orderId	`string`	必需	要购买标签的订单 ID
currency	`string`	可选	支付使用的加密货币（BTC、LTC、LTCT）。如未指定，将自动选择第一个余额充足的货币。

请求示例

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

响应

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 余额不足

如果您的钱包余额太低，API 将返回 402 状态并显示所需的加密货币金额。

余额不足响应

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

物流追踪

使用已购买标签的追踪码追踪货物。

GET

/api/v1/tracking/{code}

获取追踪信息

路径参数

参数	类型	必需	描述
code	`string`	必需	追踪码

请求示例

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

响应

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

在发生事件（如标签创建或追踪更新）时接收实时通知。

GET

/api/v1/webhooks

列出已注册的 webhooks

POST

/api/v1/webhooks

注册新 webhook

GET

/api/v1/webhooks/{id}

获取 webhook 详情

DELETE

/api/v1/webhooks/{id}

删除 webhook

可用事件

label.created

标签成功购买时

label.failed

标签生成失败时

注册 Webhook - 请求体

参数	类型	必需	描述
webhookUrl	`string`	必需	接收 webhook 事件的 URL
events	`string[]`	必需	要订阅的事件类型数组

示例：注册 Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

响应

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Webhook 签名验证

每个 webhook 都包含用于验证的签名标头。使用 HMAC-SHA256 验证签名：

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook 载荷示例

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

REST API

API 文档

使用我们强大的 REST API 将运输标签集成到您的应用程序中。实时获取费率、创建标签并以编程方式追踪货物。

身份验证

所有 API 请求都需要使用您的 API 密钥和密钥进行身份验证。在每个请求中包含以下标头：

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

安全提示

请妥善保管您的 API 密钥。切勿在客户端代码或公共仓库中暴露它。

请求示例

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

账户余额

查看您的加密货币钱包余额和交易历史。API 使用您的加密钱包（BTC、LTC、LTCT）进行支付。

GET

/api/v1/account/balance

获取加密钱包余额和交易

查询参数

参数	类型	必需	描述
includeTransactions	`boolean`	可选	包含交易历史
currency	`string`	可选	按货币筛选交易（BTC、LTC、LTCT）
limit	`number`	可选	交易数量（默认：20，最大：100）

请求示例

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

响应

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

充值

要为钱包充值，请访问我的钱包页面并使用 BTC、LTC 或 LTCT（测试网）存款。

地址验证

验证并标准化配送地址以确保可送达性。

POST

/api/v1/shipping/verify-address

验证并修正配送地址

请求体

参数	类型	必需	描述
address	`Address`	必需	要验证的地址
strict	`boolean`	可选	启用严格验证模式

请求示例

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

响应

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

运费费率

从多个承运商获取实时运费费率，包括 USPS、UPS、FedEx 和 DHL。

POST

/api/v1/shipping/rates

计算包裹的运费费率

请求体

参数	类型	必需	描述
fromAddress	`Address`	必需	发件人地址对象
toAddress	`Address`	必需	收件人地址对象
packageDetails	`Package`	必需	包裹尺寸和重量
carriers	`string[]`	可选	按特定承运商筛选（USPS、UPS、FEDEX、DHL）
customsInfo	`CustomsInfo`	可选	国际货运必需

地址对象

参数	类型	必需	描述
name	`string`	必需	全名
company	`string`	可选	公司名称
street1	`string`	必需	地址第 1 行
street2	`string`	可选	地址第 2 行
city	`string`	必需	城市
state	`string`	必需	州/省代码
zip	`string`	必需	邮政编码
country	`string`	必需	国家代码（US、CA 等）
phone	`string`	可选	电话号码
email	`string`	可选	电子邮件地址

包裹对象

参数	类型	必需	描述
length	`number`	必需	长度（英寸）
width	`number`	必需	宽度（英寸）
height	`number`	必需	高度（英寸）
weight	`number`	必需	重量（盎司）

CustomsInfo 对象

国际货运

国际运输时必需（当 fromAddress.country 与 toAddress.country 不同时）。

参数	类型	必需	描述
contents_type	`string`	必需	内容类型：documents、gift、merchandise、returned_goods、sample、dangerous_goods、humanitarian_donation、other
contents_explanation	`string`	可选	当 contents_type 为 'other' 时必需
customs_certify	`boolean`	必需	必须为 true - 证明申报的准确性
customs_signer	`string`	必需	签署海关申报单的人员姓名
eel_pfc	`string`	必需	出口豁免代码（价值低于 $2,500 的货物使用 'NOEEI 30.37(a)'）
non_delivery_option	`string`	必需	无法投递时的处理方式：'return' 或 'abandon'
restriction_type	`string`	必需	限制类型：'none'、'other'、'quarantine' 或 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	可选	当 restriction_type 不是 'none' 时必需
customs_items	`CustomsItem[]`	必需	运输物品数组（1-100 个物品）

CustomsItem 对象

参数	类型	必需	描述
description	`string`	必需	物品的详细描述
quantity	`number`	必需	物品数量（最小：1）
value	`number`	必需	美元价值（必须大于 0）
weight	`number`	必需	重量（盎司，必须大于 0）
origin_country	`string`	必需	2 字母国家代码（例如 'US'、'CN'）
hs_tariff_number	`string`	必需	6-10 位 HS 关税代码

请求示例

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

响应

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

国际运输示例

对于国际货运，请包含带有物品申报的 customsInfo 对象：

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

创建订单

创建和管理运输订单。订单包含一个或多个运输标签项目。

GET

/api/v1/orders

列出所有订单

POST

/api/v1/orders

创建新订单

GET

/api/v1/orders/{id}

获取订单详情

列出订单 - 查询参数

参数	类型	必需	描述
limit	`number`	可选	结果数量（默认：50，最大：100）
offset	`number`	可选	分页偏移量

创建订单 - 请求体

参数	类型	必需	描述
items	`OrderItem[]`	必需	订单项目数组
email	`string`	可选	客户邮箱
externalReference	`string`	可选	您的参考 ID

OrderItem 对象

简化 API

只需要 shipmentId 和 rateId。地址、包裹详情和海关信息会自动从货运中提取。

参数	类型	必需	描述
shipmentId	`string`	必需	来自费率端点的货运 ID
rateId	`string`	必需	来自费率端点的费率 ID

示例：创建订单

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

响应

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

购买标签

为订单中的所有物品购买运输标签。标签使用您的加密钱包余额（BTC、LTC 或 LTCT）购买。

POST

/api/v1/labels/purchase

为订单购买运输标签

请求体

加密货币支付

API 将按当前汇率将标签成本从美元转换为加密货币。您必须有足够的余额（包括 10% 的价格波动缓冲）。

参数	类型	必需	描述
orderId	`string`	必需	要购买标签的订单 ID
currency	`string`	可选	支付使用的加密货币（BTC、LTC、LTCT）。如未指定，将自动选择第一个余额充足的货币。

请求示例

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

响应

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 余额不足

如果您的钱包余额太低，API 将返回 402 状态并显示所需的加密货币金额。

余额不足响应

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

物流追踪

使用已购买标签的追踪码追踪货物。

GET

/api/v1/tracking/{code}

获取追踪信息

路径参数

参数	类型	必需	描述
code	`string`	必需	追踪码

请求示例

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

响应

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

在发生事件（如标签创建或追踪更新）时接收实时通知。

GET

/api/v1/webhooks

列出已注册的 webhooks

POST

/api/v1/webhooks

注册新 webhook

GET

/api/v1/webhooks/{id}

获取 webhook 详情

DELETE

/api/v1/webhooks/{id}

删除 webhook

可用事件

label.created

标签成功购买时

label.failed

标签生成失败时

注册 Webhook - 请求体

参数	类型	必需	描述
webhookUrl	`string`	必需	接收 webhook 事件的 URL
events	`string[]`	必需	要订阅的事件类型数组

示例：注册 Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

响应

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Webhook 签名验证

每个 webhook 都包含用于验证的签名标头。使用 HMAC-SHA256 验证签名：

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook 载荷示例

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

API 文档

身份验证

请求示例

账户余额

查询参数

请求示例

响应

地址验证

请求体

请求示例

响应

运费费率

请求体

地址对象

包裹对象

CustomsInfo 对象

CustomsItem 对象

请求示例

响应

国际运输示例

创建订单

列出订单 - 查询参数

创建订单 - 请求体

OrderItem 对象

示例：创建订单

响应

购买标签

请求体

请求示例

响应

余额不足响应

物流追踪

路径参数

请求示例

响应

Webhooks

可用事件

注册 Webhook - 请求体

示例：注册 Webhook

响应

Webhook 签名验证

Webhook 载荷示例

购物车

您的购物车是空的

API 文档

身份验证

请求示例

账户余额

查询参数

请求示例

响应

地址验证

请求体

请求示例

响应

运费费率

请求体

地址对象

包裹对象

CustomsInfo 对象

CustomsItem 对象

请求示例

响应

国际运输示例

创建订单

列出订单 - 查询参数

创建订单 - 请求体

OrderItem 对象

示例：创建订单

响应

购买标签

请求体

请求示例

响应

余额不足响应

物流追踪

路径参数

请求示例

响应

Webhooks