ATRShip API

快速开始

1. 登录客户中心 →「API 对接」，生成一个测试密钥（atr_test_…）。测试密钥出的都是模拟面单，不扣钱。
2. 用测试密钥把报价、出单、取面单、取消都调通。
3. 换成正式密钥（atr_live_…）就是真实出单，按报价从余额扣费。

Base URL：https://atrship.com/api/v1

1. 运费试算

curl -X POST https://atrship.com/api/v1/rates \
  -H "Authorization: Bearer atr_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shipTo": { "name": "Jane Roe", "phone": "5125550100", "address1": "500 Congress Ave",
                "city": "Austin", "state": "TX", "postalCode": "78701", "country": "US" },
    "package": { "length": 10, "width": 8, "height": 4, "weight": 1.5, "unit": "in/lb" }
  }'

{
  "success": true, "code": "OK", "message": "ok",
  "data": [
    { "channel": "SB-1234", "name": "UniUni Express", "carrier": "uniuni", "available": true, "price": 3.82, "currency": "USD", "zone": "zone3" },
    { "channel": "SB-2345", "name": "USPS Ground Advantage", "carrier": "usps", "available": true, "price": 5.64, "currency": "USD", "zone": "zone3" }
  ]
}

2. 出单

curl -X POST https://atrship.com/api/v1/orders \
  -H "Authorization: Bearer atr_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceNo": "SO-1001",
    "channel": "SB-1234",
    "shipTo": { "name": "Jane Roe", "phone": "5125550100", "address1": "500 Congress Ave",
                "city": "Austin", "state": "TX", "postalCode": "78701", "country": "US" },
    "package": { "length": 10, "width": 8, "height": 4, "weight": 1.5, "unit": "in/lb" },
    "items": [ { "sku": "TS-BLK-M", "name": "Cotton T-shirt", "quantity": 1, "unitValue": 12 } ]
  }'

{
  "success": true, "code": "OK", "message": "ok",
  "data": {
    "created": true,
    "order": {
      "orderNo": "ATR261001A1B2C3D4", "referenceNo": "SO-1001", "status": "labeled",
      "channel": "SB-1234", "channelName": "UniUni Express", "carrier": "uniuni",
      "trackingNo": "UUS0123456789", "trackingUrl": "https://…", "price": 3.82, "currency": "USD",
      "labelReady": true, "labelUrl": "https://atrship.com/api/v1/orders/ATR261001A1B2C3D4/label", "test": true
    }
  }
}

面单一般几秒内出好；如果返回的 status 是 processing、labelReady 是 false，过几秒再查 /orders/{no}。同一个 referenceNo 重复提交（例如网络超时重试）会直接返回已有的单（created: false），不会重复出单扣费。

3. 下载面单

# PDF
curl -H "Authorization: Bearer atr_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -o label.pdf https://atrship.com/api/v1/orders/SO-1001/label
# base64 (JSON)
curl -H "Authorization: Bearer atr_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" "https://atrship.com/api/v1/orders/SO-1001/label?format=base64"

鉴权与密钥

• 每个请求在请求头带上密钥： Authorization: Bearer atr_live_… （也可以用 X-Api-Key: atr_live_…）
• 密钥只在生成时显示一次，我们只保存加密后的摘要；泄露了请马上在客户中心作废，再生成新的。
• 可以给密钥设置 IP 白名单，只允许你们服务器的 IP 调用。
• 频率限制：每个密钥每分钟 60 次，超过返回 429 和 Retry-After。
• 只支持 HTTPS。所有返回都是 { success, code, message, data } 格式；失败时 success 为 false，code 见下面的错误码。

{ "success": false, "code": "INSUFFICIENT_BALANCE", "message": "余额不足：当前余额 1.20，本单需要 3.82，请先充值" }

接口列表

字段说明

shipTo / shipFrom

name（或 firstName + lastName）、phone、address1、address2、city、state（美国填州二字码）、postalCode、country（二字码，默认 US）、company、email。shipFrom 不传时用账户的默认寄件地址。

package

length、width、height、weight，unit 为 in/lb（默认）、cm/kg 或 cm/g；signature：none（默认）、direct、indirect、adult。

items

sku、name（英文品名）、quantity、unitValue（单件申报价值 USD）。国际件还要 hsCode、originCountry、material。美国件不传 items 时按一件普通货物处理；传了 SKU 会按账户设置加印在面单上。

出单的其他字段

referenceNo（必填，你们的订单号，最长 50 位）、channel（必填）、expectedPrice（可选：报价时的价格，价格变了会返回 PRICE_CHANGED）、remark、addressConfirmed（地址核对提示有问题时确认无误继续出单）。

订单状态

错误码

ERP 对接说明（领星等）

• 物流商授权：在 ERP 里填我们的密钥（API Key / Token 一栏），接口地址填上面的 Base URL。
• 同步物流方式：调用 /channels，channel 是渠道代码，name 是显示名称。
• 下单获取面单：/orders 出单，referenceNo 填 ERP 的订单号或包裹号；面单用 /orders/{no}/label?format=base64。
• 获取运单号：出单返回里就有 trackingNo；如果还是空的，过几秒调 /orders/{no}。
• 取消 / 截单：/orders/{no}/cancel。
• ERP 厂商需要对接资料或测试账号，请联系我们： info@innotronia.com