|
|
# 查价系统 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)。
|
