# 卡派查价 — 第三方系统对接指南

本文档面向**宿主业务系统**（如美美与共）开发方，说明如何通过 HTTP API 接入实时卡派（LTL）询价。

> 接口速查见 [`API.md`](./API.md)。示例 JSON 见 [`host-candidates-req.example.json`](./host-candidates-req.example.json)。

---

## 1. 对接前准备

| 项 | 说明 |
|----|------|
| **Base URL** | 由我方提供，例如 `https://if.dev.51track.vip` |
| **推荐方式** | **方式 A**：两步宿主接口，免 Token，服务端同步返回报价 |
| **备用方式** | **方式 B**：Token + 三步接口 + 宿主自行轮询（后期启用鉴权时使用） |
| **协议** | HTTPS + JSON，UTF-8 |

**服务器开关（我方运维配置）：**

```env
HOST_PUBLIC_API_ENABLED=true
HOST_PUBLIC_DEFAULT_CUSTOMER_ID=CUST_001
```

---

## 2. 方式 A：两步接口（推荐，美美与共当前使用）

### 2.1 流程概览

```mermaid
sequenceDiagram
    participant 用户
    participant 宿主前端 as 宿主前端
    participant 查价 as 查价 API

    用户->>宿主前端: 填写地址 + 货物，点「获取报价」
    宿主前端->>查价: ① POST /api/host/quote/candidates
    查价-->>宿主前端: 候选列表 + host_session_id
    宿主前端->>用户: 展示候选，选择提货/派送地址
    用户->>宿主前端: 确认候选
    宿主前端->>查价: ② POST /api/host/quote/submit
    Note over 查价: 内部提交询价 + 轮询，10–420 秒
    查价-->>宿主前端: status=done + quotes
    宿主前端->>用户: 展示 final_total 等
```

| 调用次序 | 接口 | 宿主做什么 | 查价做什么 |
|----------|------|------------|------------|
| 第 1 次 | `POST /api/host/quote/candidates` | 传地址 + 货物 | 返回联想候选 + `host_session_id` |
| 第 2 次 | `POST /api/host/quote/submit` | 传会话 ID + 用户选的候选 | **内部轮询**，直接返回最终报价 |

**宿主无需：** Token、GET 轮询、`quote_id` 管理。

**宿主需要：** 地址候选选择 UI、报价结果 UI、第 2 步 Loading（约 10–30 秒，最长约 7 分钟）。

### 2.2 鉴权

方式 A **不需要**任何 Authorization 头，只需：

```http
Content-Type: application/json
```

### 2.3 第一步：联想地址 + 暂存货物

```http
POST /api/host/quote/candidates
Content-Type: application/json
```

**请求体：**

```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` | 是 | 货物信息（第一步传入后由服务端暂存，第二步无需重复传） |

**成功响应示例：**

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "host_session_id": "eb75548a-2c0b-4282-becd-ca3a0f5a3c15",
    "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
  }
}
```

**前端处理：**

- 用 `display_label` 展示给用户。
- 仅允许选择 `selectable: true` 的项；不可选项展示 `unavailable_reason`。
- 保存 `host_session_id`（30 分钟有效）和用户选中的**完整候选对象**。

### 2.4 第二步：确认候选并取报价（同步）

```http
POST /api/host/quote/submit
Content-Type: application/json
```

**请求体：**

```json
{
  "host_session_id": "eb75548a-2c0b-4282-becd-ca3a0f5a3c15",
  "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` | 是 | 第一步返回的 UUID |
| `pickup_candidate` | 是 | 第一步 `pickup_candidates` 中用户选中项（完整对象） |
| `delivery_candidate` | 是 | 第一步 `delivery_candidates` 中用户选中项（完整对象） |

**成功响应（节选）：**

```json
{
  "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）、`carrier`、`transit_days`。

**失败：** HTTP 200 时 `data.status` 可能为 `failed`，读 `error_message`；HTTP 504 表示服务端轮询超时。

### 2.5 美美与共前端职责

| 模块 | 说明 |
|------|------|
| 表单 | 收集地址（仓库代码需先转为 street/city/state/zip）和货物 |
| 地址候选 UI | 第 1 步后展示 `pickup_candidates` / `delivery_candidates` 供用户选择 |
| 报价结果 UI | 第 2 步后展示 `quotes` 列表 |
| Loading | 第 2 步显示「正在查询报价，约需 10–30 秒」，禁止重复提交 |
| 不需要 | Token、轮询、`quote_id` 管理 |

### 2.6 美美与共调用示例（JavaScript）

```javascript
// 第 1 步：联想
async function fetchCandidates(form) {
  const res = await fetch("https://if.dev.51track.vip/api/host/quote/candidates", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      pickup_address: form.pickup,
      delivery_address: form.delivery,
      cargo: form.cargo,
    }),
  });
  const json = await res.json();
  if (json.code !== 0) throw new Error(json.message);
  return json.data; // { host_session_id, pickup_candidates, delivery_candidates }
}

// 第 2 步：确认并取报价（一次请求，无需轮询）
async function submitQuote(hostSessionId, pickupCandidate, deliveryCandidate) {
  const res = await fetch("https://if.dev.51track.vip/api/host/quote/submit", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      host_session_id: hostSessionId,
      pickup_candidate: pickupCandidate,
      delivery_candidate: deliveryCandidate,
    }),
  });
  const json = await res.json();
  if (json.code !== 0) throw new Error(json.message);
  if (json.data.status === "failed") throw new Error(json.data.error_message ?? "询价失败");
  return json.data.quotes;
}
```

---

## 3. 统一响应格式

```json
{ "code": 0, "message": "ok", "data": { } }
```

| 字段 | 说明 |
|------|------|
| `code` | `0` 成功；非 0 为错误码 |
| `message` | 人类可读说明 |
| `data` | 业务数据 |

---

## 4. 货物类型与限制

**`cargo_type` 枚举：**

`general_freight` · `machinery` · `furniture` · `electronics` · `building_materials` · `auto_parts` · `food_nonperishable` · `apparel` · `other`

| 项 | 限制 |
|----|------|
| 托盘数 | 1 – 25 |
| 单托重量 | 0.01 – 9,999 lb |
| 单托尺寸（换算英寸后） | 长 ≤ 999，宽 ≤ 99，高 ≤ 99 |

---

## 5. 自测方法

### 5.1 第一步：联想（PowerShell）

> **注意：** Windows PowerShell 下 `curl.exe -d '{...}'` 容易因引号转义导致 JSON 无效，返回 `请求体格式无效`。**请用 JSON 文件或 Invoke-RestMethod。**

**推荐：JSON 文件**

```powershell
curl.exe -s -X POST "https://if.dev.51track.vip/api/host/quote/candidates" `
  -H "Content-Type: application/json" `
  --data-binary "@deploy/host-candidates-req.example.json"
```

**推荐：Invoke-RestMethod**

```powershell
$body = Get-Content "deploy/host-candidates-req.example.json" -Raw
Invoke-RestMethod -Uri "https://if.dev.51track.vip/api/host/quote/candidates" `
  -Method POST -ContentType "application/json" -Body $body
```

成功标志：`code: 0`，且 `data.host_session_id` 存在。

### 5.2 第二步：取报价

从第一步响应中各取一条 `selectable: true` 的候选，构造 body 调用：

```powershell
# 将 host_session_id、pickup_candidate、delivery_candidate 填入 body 后：
Invoke-RestMethod -Uri "https://if.dev.51track.vip/api/host/quote/submit" `
  -Method POST -ContentType "application/json" -Body $submitJson
```

成功标志：`data.status === "done"`，`data.quotes` 含 `final_total`。

### 5.3 Linux / macOS

```bash
curl -s -X POST "https://if.dev.51track.vip/api/host/quote/candidates" \
  -H "Content-Type: application/json" \
  --data-binary "@deploy/host-candidates-req.example.json"
```

---

## 6. 方式 B：Token 三步接口

后期启用鉴权时，将 `HOST_PUBLIC_API_ENABLED=false`，改用以下流程。**宿主须自行轮询。**

### 6.1 鉴权

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

### 6.2 流程

| 步骤 | 接口 | 说明 |
|------|------|------|
| 1 | `POST /api/addresses/mothership-candidates` | 仅地址，返回候选 |
| 2 | `POST /api/quotes` | 确认地址 + 货物，返回 `quote_id` + `processing` |
| 3 | `GET /api/quotes/{quote_id}` | 每 2 秒轮询，直到 `done` / `failed` |

第二步 body 须含 `customer_id`、`request_id`（UUID v4）、经 MotherShip 确认的地址字段（`mothership_option_id`、`selected_from_mothership: true` 等）及货物信息。

Token 由我方在 `HOST_SERVICE_TOKENS` 中配置后发放。

---

## 7. 错误码

### 方式 A 常见错误

| code | HTTP | 说明 | 处理 |
|------|------|------|------|
| `VALIDATION_FAILED` | 400 | 参数无效 | 检查字段；message 为「请求体格式无效」时检查 JSON 格式 |
| `FORBIDDEN` | 403 | 公开接口未启用 | 确认 `HOST_PUBLIC_API_ENABLED=true` |
| `SESSION_EXPIRED` | 404 | 会话过期 | 重新调用第一步 |
| `ADDRESS_SESSION_MISMATCH` | 400 | 候选与第一步不匹配 | 使用第一步返回的候选对象 |
| `ADDRESS_NOT_SELECTABLE` | 400 | 选了不可用地址 | 换 `selectable: true` 的候选 |
| `QUOTE_TIMEOUT` | 504 | 询价超时 | 稍后重试 |
| `RATE_LIMITED` | 429 | 限流 | 降低频率 |

### 通用错误

| code | HTTP | 说明 |
|------|------|------|
| `UNAUTHORIZED` | 401 | Token 无效（方式 B） |
| `INTERNAL_ERROR` | 5xx | 服务异常 |

询价业务失败时 HTTP 可能仍为 200，`data.status === "failed"`，见 `error_message`。

---

## 8. 安全与运维

1. 方式 A 当前免 Token，**仅建议在可信内网或已控域名下使用**；上线前改方式 B。
2. 方式 B 的 Token **仅放宿主服务端**，禁止写进浏览器或公开仓库。
3. 服务**未开放 CORS**；浏览器页请勿直接 `fetch` 查价域名，应通过宿主后端或同域代理。
4. 第二步网关/Nginx 须设 `proxy_read_timeout 420s;`。
5. 报价有效期见 `valid_until`，过期需重新询价。

---

## 9. 联系与支持

| 事项 | 说明 |
|------|------|
| 开通 / 环境确认 | 联系查价系统管理员 |
| 接口故障 | 提供 `host_session_id` 或 `quote_id`、发生时间 |
| 文档版本 | 2026-06-30 |