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 交互式测试一下。