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

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

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

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

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

---

## 1. 鉴权

每次请求都要带：

```http
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"` |

判定要点：

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

硬限速查：

- 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（异步）

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

---

## 5. Flock（异步）

`POST /api/flock/quotes`：

```json
{
  "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

```bash
# 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`](./api对接文档.md)。