运费查询 API

只需一次 API 调用，即可实时获取 USPS、UPS、FedEx 及其他承运商的运费报价。

概述

运费查询端点：

POST https://api.atoship.com/v1/rates

返回各项配送选项，包含价格、时效和服务详情。

请求格式

基础请求：

{
  "from": {
    "zip": "10001",
    "country": "US"
  },
  "to": {
    "zip": "90210",
    "country": "US"
  },
  "package": {
    "weight": 16,
    "length": 10,
    "width": 8,
    "height": 4
  }
}

地址字段

From/To 对象：

字段	类型	是否必填	说明
name	string	否	联系人姓名
company	string	否	公司名称
street1	string	否	街道地址
street2	string	否	公寓/套房
city	string	否*	城市
state	string	否*	州/省代码
zip	string	是	邮政编码
country	string	是	国家代码
phone	string	否	电话号码

*部分承运商必填

包裹字段

Package 对象：

字段	类型	是否必填	说明
weight	number	是	重量（盎司 oz）
length	number	否	长度（英寸 in）
width	number	否	宽度（英寸 in）
height	number	否	高度（英寸 in）
type	string	否	包裹类型

包裹类型

可选类型：

package (default)
envelope
flat_rate_envelope
flat_rate_box_small
flat_rate_box_medium
flat_rate_box_large
regional_rate_box_a
regional_rate_box_b

响应格式

成功响应：

{
  "success": true,
  "rates": [
    {
      "id": "rate_abc123",
      "carrier": "USPS",
      "service": "Priority Mail",
      "price": 8.95,
      "currency": "USD",
      "delivery_days": 2,
      "delivery_date": "2024-01-17"
    },
    {
      "id": "rate_def456",
      "carrier": "UPS",
      "service": "Ground",
      "price": 12.50,
      "currency": "USD",
      "delivery_days": 5
    }
  ]
}

筛选承运商

指定承运商：

{
  "carriers": ["USPS", "UPS"],
  "from": { ... },
  "to": { ... },
  "package": { ... }
}

服务筛选

按服务筛选：

{
  "services": ["Priority Mail", "Ground"],
  "from": { ... },
  "to": { ... },
  "package": { ... }
}

多个包裹

多包裹请求：

{
  "from": { ... },
  "to": { ... },
  "packages": [
    { "weight": 16, "length": 10, "width": 8, "height": 4 },
    { "weight": 32, "length": 12, "width": 10, "height": 6 }
  ]
}

国际运费

报关信息：

{
  "from": {
    "zip": "10001",
    "country": "US"
  },
  "to": {
    "zip": "M5V 2H1",
    "country": "CA"
  },
  "package": { ... },
  "customs": {
    "contents_type": "merchandise",
    "value": 50.00,
    "currency": "USD"
  }
}

住宅地址 vs 商业地址

地址类型：

{
  "to": {
    "zip": "90210",
    "country": "US",
    "is_residential": true
  }
}

签收选项

签收确认：

{
  "options": {
    "signature": "adult",
    "saturday_delivery": false
  }
}

签收方式取值：

none（无需签收）
standard（普通签收）
adult（成人签收）
indirect（间接签收）

保价

添加保价：

{
  "options": {
    "insurance_amount": 100.00
  }
}

代码示例

完整请求：

const response = await fetch('https://api.atoship.com/v1/rates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: { zip: '10001', country: 'US' },
    to: { zip: '90210', country: 'US' },
    package: { weight: 16 }
  })
});

const { rates } = await response.json();
const cheapest = rates.sort((a, b) => a.price - b.price)[0];

错误处理

错误响应：

{
  "success": false,
  "error": {
    "code": "invalid_address",
    "message": "Destination zip code is invalid",
    "field": "to.zip"
  }
}

运费缓存

最佳实践：

报价有效期约 15 分钟
按发货地/收货地缓存
下单前重新获取报价
妥善处理价格变动

性能优化建议

优化请求：

提供尺寸信息以提升准确度
指定承运商以减少调用次数
批量报价可使用 webhook
缓存常用路线