8.8 KiB

Raw Blame History Unescape Escape

MotherShip 查询接口调用文档

本文档只说明 MotherShip / Axel 查询报价接口如何调用，适合直接发给第三方开发人员使用。

Base URL：https://if.dev.51track.vip

1. 推荐接口

当前使用 两步宿主接口（须鉴权）：

POST /api/host/quote/candidates
POST /api/host/quote/submit

特点：

第一步返回联想地址候选
第二步服务端内部等待并轮询
调用方不需要自己轮询

2. 鉴权（必传）

当前服务器已开启鉴权（HOST_PUBLIC_API_ENABLED=false），每次请求须携带以下请求头：

Authorization: Bearer <Service Token>
X-Customer-Id: CUST_001
Content-Type: application/json

字段	值	说明
`Authorization`	`Bearer <Service Token>`	我方单独发放的 API Token
`X-Customer-Id`	`CUST_001`	固定客户 ID，须与 Token 绑定一致

示例（联调 Token）：

Authorization: Bearer demo-host-token
X-Customer-Id: CUST_001
Content-Type: application/json

生产环境 Token 由我方另行发放，格式同上；请勿将 Token 写入前端页面或公开仓库。

鉴权错误

HTTP	message	说明
401	缺少 Authorization 头	未带 `Authorization: Bearer ...`
401	Service Token 无效	Token 拼写错误或不在白名单
401	令牌无效或已过期	误用了管理员 JWT，应使用 Service Token

Apifox 环境变量建议

变量	示例值
`baseUrl`	`https://if.dev.51track.vip`
`token`	`demo-host-token`（联调）或我方发放的生产 Token
`customerId`	`CUST_001`

在「Auth」或「Headers」中配置：

Authorization：Bearer {{token}}
X-Customer-Id：{{customerId}}
Content-Type：application/json

3. 第一步：获取联想地址候选

接口

POST /api/host/quote/candidates

请求头示例

Authorization: Bearer demo-host-token
X-Customer-Id: CUST_001
Content-Type: application/json

请求体

{
  "pickup_address": {
    "street": "1234 Warehouse Blvd",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001"
  },
  "delivery_address": {
    "street": "5678 Distribution Dr",
    "city": "Dallas",
    "state": "TX",
    "zip": "75201"
  },
  "cargo": {
    "weight": { "value": 500, "unit": "kg" },
    "dimensions": { "length": 120, "width": 100, "height": 150, "unit": "cm" },
    "pallet_count": 2,
    "cargo_type": "general_freight"
  }
}

字段说明

字段	说明
`pickup_address`	提货草稿地址
`delivery_address`	派送草稿地址
`street/city/state`	必填，`state` 为美国州二字码
`zip`	可选，建议传
`cargo.weight.unit`	`kg` 或 `lb`
`cargo.dimensions.unit`	`cm` 或 `in`
`cargo.pallet_count`	托盘数，1–25
`cargo.cargo_type`	`general_freight` 等

成功响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "host_session_id": "2dd352e6-9a1d-4563-8f13-ebff18aabdb9",
    "pickup_candidates": [
      {
        "option_id": "Eisx...",
        "display_label": "1234 Warehouse Street, Los Angeles, CA, USA",
        "formatted_address": "1234 Warehouse Street, Los Angeles, CA, USA",
        "street": "1234 Warehouse Street",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "selectable": true
      }
    ],
    "delivery_candidates": [
      {
        "option_id": "EihE...",
        "display_label": "Distribution Dr, Wilmer, Dallas, TX, USA",
        "formatted_address": "Distribution Dr, Wilmer, Dallas, TX, USA",
        "street": "5678 Distribution Dr, Wilmer",
        "city": "Dallas",
        "state": "TX",
        "zip": "75201",
        "selectable": true
      }
    ],
    "requires_selection": true
  }
}

第一步调用后的处理

保存 data.host_session_id（约 30 分钟有效）
从 pickup_candidates 中选择 1 条 selectable: true
从 delivery_candidates 中选择 1 条 selectable: true
将选中的完整候选对象用于第二步请求

不要使用 selectable: false 的候选。

4. 第二步：提交候选并直接获取最终报价

接口

POST /api/host/quote/submit

请求头

与第一步相同（须带 Authorization 与 X-Customer-Id）。

请求体

{
  "host_session_id": "2dd352e6-9a1d-4563-8f13-ebff18aabdb9",
  "pickup_candidate": {
    "option_id": "Eisx...",
    "display_label": "1234 Warehouse Street, Los Angeles, CA, USA",
    "formatted_address": "1234 Warehouse Street, Los Angeles, CA, USA",
    "street": "1234 Warehouse Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "selectable": true
  },
  "delivery_candidate": {
    "option_id": "EihE...",
    "display_label": "Distribution Dr, Wilmer, Dallas, TX, USA",
    "formatted_address": "Distribution Dr, Wilmer, Dallas, TX, USA",
    "street": "5678 Distribution Dr, Wilmer",
    "city": "Dallas",
    "state": "TX",
    "zip": "75201",
    "selectable": true
  }
}

注意

host_session_id 必须来自第一步返回值
pickup_candidate / delivery_candidate 必须是第一步候选列表中的完整对象
第二步会等待 10–30 秒，最长约 420 秒
第二步不会返回 processing 让你继续轮询；服务端会自己处理轮询

成功响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "quote_id": "QTE_20260630_0003",
    "status": "done",
    "currency": "USD",
    "valid_until": "2026-06-30T10:30:00.000Z",
    "quotes": [
      {
        "service_level": "standard",
        "rate_option": "lowest",
        "carrier": "Frontline Freight",
        "transit_days": "Est. 5 business days",
        "final_total": 337.06
      }
    ]
  }
}

应展示给用户的字段

字段	说明
`quotes[].final_total`	最终展示价（USD）
`quotes[].carrier`	承运商
`quotes[].transit_days`	时效
`valid_until`	报价有效期

5. 调用步骤总结

业务步骤

带鉴权头调 POST /api/host/quote/candidates
取得 host_session_id
让用户在候选地址中各选一条可用地址
带鉴权头调 POST /api/host/quote/submit
直接拿最终报价并展示

第三方系统需要做的事

在服务端保存 Token，不要暴露在前端
每次请求携带 Authorization + X-Customer-Id: CUST_001
第一步展示候选地址选择 UI
第二步显示 Loading（建议超时 ≥ 420 秒）
第二步返回后展示报价

第三方系统不需要做的事

不需要 GET /api/quotes/{id} 轮询
不需要自己做 kg/cm 到 lb/in 的换算

6. 单位说明

接口支持：

重量：kg / lb
尺寸：cm / in

例如：

"weight": { "value": 500, "unit": "kg" },
"dimensions": { "length": 120, "width": 100, "height": 150, "unit": "cm" }

服务端会自动换算为 MotherShip 需要的英制单位。

7. Apifox 测试方法

环境变量

变量	值
`baseUrl`	https://if.dev.51track.vip
`token`	`demo-host-token`
`customerId`	`CUST_001`

第一步

方法：POST
URL：{{baseUrl}}/api/host/quote/candidates
Headers：
- Authorization：Bearer {{token}}
- X-Customer-Id：{{customerId}}
- Content-Type：application/json
Body：JSON（可参考 deploy/host-candidates-req.example.json）

第二步

方法：POST
URL：{{baseUrl}}/api/host/quote/submit
Headers：与第一步相同
Body：填入第一步返回的 host_session_id 和选中的完整候选对象

Apifox 请求超时建议：420000 ms（420 秒）

cURL 示例（第一步）

curl -X POST "https://if.dev.51track.vip/api/host/quote/candidates" \
  -H "Authorization: Bearer demo-host-token" \
  -H "X-Customer-Id: CUST_001" \
  -H "Content-Type: application/json" \
  --data-binary @deploy/host-candidates-req.example.json

8. 常见错误

code	HTTP	说明	处理方式
`UNAUTHORIZED`	401	缺少或无效 Token	检查 `Authorization`、`X-Customer-Id`
`VALIDATION_FAILED`	400	参数不合法	检查 JSON、字段名、单位值
`SESSION_EXPIRED`	404	会话过期	重新调第一步
`ADDRESS_SESSION_MISMATCH`	400	第二步候选与第一步不一致	使用第一步返回的完整候选对象
`ADDRESS_NOT_SELECTABLE`	400	选了不可用候选	改用 `selectable: true` 的候选
`QUOTE_TIMEOUT`	504	服务端等待超时	稍后重试
`RATE_LIMITED`	429	请求过于频繁	降低调用频率

9. 联系与支持

Token 失效或需单独开通生产 Token，请联系我方运维
X-Customer-Id 当前固定为 CUST_001，须与发放的 Token 一致

8.8 KiB Raw Blame History Unescape Escape

MotherShip 查询接口调用文档

1. 推荐接口

2. 鉴权（必传）

鉴权错误

Apifox 环境变量建议

3. 第一步：获取联想地址候选

接口

请求头示例

请求体

字段说明

成功响应示例

第一步调用后的处理

4. 第二步：提交候选并直接获取最终报价

接口

请求头

请求体

注意

成功响应示例

应展示给用户的字段

5. 调用步骤总结

业务步骤

第三方系统需要做的事

第三方系统不需要做的事

6. 单位说明

7. Apifox 测试方法

环境变量

第一步

第二步

cURL 示例（第一步）

8. 常见错误

9. 联系与支持

8.8 KiB

Raw Blame History Unescape Escape