帮助中心GitHub

atoship 是如何运作的

了解 atoship 运输 API 背后的核心概念, 掌握运费、面单、追踪、承运商与计费的来龙去脉。

运输流程

每一次发货都遵循这个简单的 3 步流程:获取运费、生成面单、追踪包裹。

1

获取运费

一次 API 调用即可比较 USPS、UPS 和 FedEx 的价格

提交包裹尺寸和收发件地址,即可实时获取各承运商的运费报价及预计送达时间。

2

生成面单

选定运费方案后生成运输面单

挑选最优运费并生成可直接打印的面单,费用将从您的钱包余额中扣除。

3

追踪包裹

实时更新,随时掌握派送状态

通过统一的追踪 API 和 webhook 通知,跨所有承运商追踪包裹动态。

核心资源

地址
/v1/addresses
运单的发件与收件地址。atoship 会校验并标准化地址,避免派送失败。
  • 地址校验确保可派送
  • 自动识别住宅地址与商业地址
  • 标准化格式(符合 USPS 规范)
  • 支持国际地址
运费
/v1/rates
来自多家承运商的实时运费。即刻比较 USPS、UPS 和 FedEx 的价格。
  • 一次调用即可多承运商比价
  • 已包含商业折扣价
  • 预计送达时间
  • 多种服务等级可选(Express、Ground 等)
面单
/v1/labels
带追踪号的运输面单。可生成 PDF、PNG 或 ZPL 格式的可打印面单。
  • 多种格式:PDF、PNG、ZPL(热敏)
  • 自动生成追踪号
  • 费用从钱包扣除
  • 30 天内可作废/退款
追踪
/v1/tracking
包裹派送状态更新。通过统一 API 跨所有承运商追踪运单。
  • 实时状态更新
  • 事件 webhook 通知
  • 签收确认
  • 异常提醒

承运商

USPS
carrier: "usps"
美国邮政 — 最适合轻小件包裹和住宅派送。
  • Priority Mail — 1-3 天
  • Priority Mail Express — 隔夜达
  • Ground Advantage — 2-5 天
  • First Class Mail — 信件与小件包裹
UPS
carrier: "ups"
联合包裹 — 商业运输和较重包裹的可靠之选。
  • Ground — 1-5 天
  • 2nd Day Air — 2 天
  • Next Day Air — 隔夜达
  • 3 Day Select — 3 天
FedEx
carrier: "fedex"
联邦快递 — 快递和国际派送的绝佳选择。
  • Ground — 1-5 天
  • Express Saver — 3 天
  • 2Day — 2 天
  • Home Delivery — 住宅派送

账户与计费

钱包
/v1/wallet/balance
用于购买运输面单的预付余额。可通过信用卡或银行转账充值。
  • 按量付费模式
  • 无月费、无最低消费
  • 支持自动充值
  • 控制台可查交易记录
退款
/v1/labels/{id}/void
作废未使用的面单并退回额度。多数面单可在 30 天内退款。
  • 作废未使用面单可全额退款
  • USPS:30 天内退款
  • UPS/FedEx:30 天内退款
  • 额度退回钱包

集成

电商渠道
Dashboard → Channels
连接您的网店,自动导入订单。支持与 Shopify、eBay、Amazon 等同步。
  • Shopify — 订单实时同步
  • eBay — 平台集成
  • Amazon — SP-API 集成
  • WooCommerce — WordPress 插件
Webhook
/v1/webhooks
实时接收追踪更新、面单生成等事件通知。
  • 追踪状态更新
  • 面单生成/作废事件
  • 签收确认
  • 自定义回调 URL

融会贯通

完整的 API 工作流
看看在一次典型集成中,这些概念是如何协同运作的
// 完整的运输流程
const API_KEY = 'your_api_key';
const BASE_URL = 'https://atoship.com/api/v1';

// 1. 从所有承运商获取运费
const ratesResponse = await fetch(`${BASE_URL}/rates`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: {
      name: "Your Store",
      street1: "123 Store Street",
      city: "San Francisco",
      state: "CA",
      zip: "94102"
    },
    to: {
      name: "John Customer",
      street1: "456 Customer Ave",
      city: "Los Angeles",
      state: "CA",
      zip: "90210"
    },
    parcel: {
      weight: 16,  // 盎司
      length: 12,
      width: 8,
      height: 6
    }
  })
});

const { rates } = await ratesResponse.json();
// rates = [{ id, carrier, service, rate, delivery_days }, ...]

// 2. 用最便宜的运费生成面单
const labelResponse = await fetch(`${BASE_URL}/labels`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rate_id: rates[0].id,
    label_format: 'PDF'
  })
});

const label = await labelResponse.json();
// label = { id, tracking_number, label_url, carrier, cost }

// 3. 追踪包裹
const trackingResponse = await fetch(
  `${BASE_URL}/tracking/${label.tracking_number}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const tracking = await trackingResponse.json();
// tracking = { status, events: [{ timestamp, description, location }] }

小贴士

在把这些调用集成进应用之前,先用 API Playground 交互式测试一下。

下一步

atoship © 2026