3.9 KiB

Raw Permalink Blame History Unescape Escape

查价系统 API 调用文档（第三方精简版）

本文档面向第三方开发，只保留实际接入必需内容。

完整对接规范（推荐阅读）：同目录 api对接文档.md
覆盖 两官网 × 免账号/登录后 = 四条互斥路线、字段类型/约束/错误码/判定流程。

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

统一响应：{ "code": 0, "message": "ok", "data": { } }

1. 鉴权

每次请求都要带：

Authorization: Bearer <API Key>
X-Customer-Id: <Customer ID>
Content-Type: application/json

API Key 放服务端，不要写死在前端。

2. 四条路线（一票只走一条）

路线	条件	接口
`MS_GUEST`	MotherShip + 无账密	`POST /api/host/quote/candidates` → `POST /api/host/quote/submit`（同步，超时 ≥420s）
`MS_LOGGED_IN`	MotherShip + 有账密	地址联想可选 → `POST /api/quotes` → `GET /api/quotes/{id}`
`FLOCK_GUEST`	Flock + 无账密	`POST /api/flock/quotes` → 轮询
`FLOCK_LOGGED_IN`	Flock + 有账密	同上，且 `flock_input.form_mode = "logged_in_quick"`

判定要点：

先按业务选官网，并用该官网硬限校验参数（禁止混用 MotherShip / Flock 上限）。
再看该客户是否已绑定对应官网账密 → 有则登录后，无则免账号。
账密在管理端绑定，不要放进询价请求体。

硬限速查：

MotherShip：托盘 1–25；单托约 ≤9999 lb；登录后 Weight each ≤5000 lb；尺寸 L≤999、W/H≤99 in。
Flock 免账号：托盘 4–20；总重 ≤45000 lb；L≤636 / W≤102 / H≤108 in；仅邮编；须线性英尺。
Flock 登录后：件数 1–999；须 form_mode=logged_in_quick。

3. MS_GUEST（同步两步）

3.1 候选

POST /api/host/quote/candidates

保存 host_session_id；提货/派送各选 1 条 selectable: true；第二步回传完整候选对象。

3.2 提交

POST /api/host/quote/submit → 直接看 status / quotes[].final_total。

4. MS_LOGGED_IN（异步）

（推荐）POST /api/addresses/mothership-suggest（customer_id + query≥3 字）
POST /api/quotes：地址须含 selected_from_mothership: true、mothership_option_id 等确认字段；可带 cargo_lines / ready_date / mothership_details
轮询 GET /api/quotes/{quote_id} → quotes[]

5. Flock（异步）

POST /api/flock/quotes：

{
  "request_id": "<uuid>",
  "customer_id": "CUST_001",
  "flock_input": {
    "pickup_date": "07/22/2026",
    "pickup_zip": "90001",
    "delivery_zip": "75201",
    "pallet_count": 6,
    "total_weight": { "value": 12000, "unit": "lb" },
    "dimensions": { "length": 48, "width": 40, "height": 48, "unit": "in" }
  }
}

登录后追加："form_mode": "logged_in_quick"，并建议传 packaging / freight_class / description / location_type。

轮询成功读 data.flock.lines[].final_total_usd（不是 MotherShip 的 quotes）。

6. 轮询

GET /api/quotes/{quote_id}

processing → 继续；done / failed → 结束
MotherShip 窗口 ≥420s；Flock 建议 ≥210s

7. cURL

# MS_GUEST
curl -X POST "https://if.dev.51track.vip/api/host/quote/candidates" \
  -H "Authorization: Bearer <API Key>" \
  -H "X-Customer-Id: CUST_001" \
  -H "Content-Type: application/json" \
  --data-binary @ms-guest-candidates.json

# Flock
curl -X POST "https://if.dev.51track.vip/api/flock/quotes" \
  -H "Authorization: Bearer <API Key>" \
  -H "X-Customer-Id: CUST_001" \
  -H "Content-Type: application/json" \
  --data-binary @flock-guest.json

# 轮询
curl -X GET "https://if.dev.51track.vip/api/quotes/<quote_id>" \
  -H "Authorization: Bearer <API Key>" \
  -H "X-Customer-Id: CUST_001"

完整字段、错误码、判定细则见 api对接文档.md。

3.9 KiB Raw Permalink Blame History Unescape Escape