|
|
# MotherShip 查询接口调用文档
|
|
|
|
|
|
本文档只说明 **MotherShip / Axel** 查询报价接口如何调用，适合直接发给第三方开发人员使用。
|
|
|
|
|
|
Base URL：`https://if.dev.51track.vip`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 推荐接口
|
|
|
|
|
|
当前使用 **两步宿主接口**（须鉴权）：
|
|
|
|
|
|
1. `POST /api/host/quote/candidates`
|
|
|
2. `POST /api/host/quote/submit`
|
|
|
|
|
|
特点：
|
|
|
|
|
|
- 第一步返回联想地址候选
|
|
|
- 第二步服务端内部等待并轮询
|
|
|
- 调用方**不需要自己轮询**
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 鉴权（必传）
|
|
|
|
|
|
当前服务器已开启鉴权（`HOST_PUBLIC_API_ENABLED=false`），**每次请求**须携带以下请求头：
|
|
|
|
|
|
```http
|
|
|
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）：**
|
|
|
|
|
|
```http
|
|
|
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. 第一步：获取联想地址候选
|
|
|
|
|
|
### 接口
|
|
|
|
|
|
```http
|
|
|
POST /api/host/quote/candidates
|
|
|
```
|
|
|
|
|
|
### 请求头示例
|
|
|
|
|
|
```http
|
|
|
Authorization: Bearer demo-host-token
|
|
|
X-Customer-Id: CUST_001
|
|
|
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.weight.unit` | `kg` 或 `lb` |
|
|
|
| `cargo.dimensions.unit` | `cm` 或 `in` |
|
|
|
| `cargo.pallet_count` | 托盘数，1–25 |
|
|
|
| `cargo.cargo_type` | `general_freight` 等 |
|
|
|
|
|
|
### 成功响应示例
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 第一步调用后的处理
|
|
|
|
|
|
1. 保存 `data.host_session_id`（约 30 分钟有效）
|
|
|
2. 从 `pickup_candidates` 中选择 1 条 `selectable: true`
|
|
|
3. 从 `delivery_candidates` 中选择 1 条 `selectable: true`
|
|
|
4. 将选中的**完整候选对象**用于第二步请求
|
|
|
|
|
|
不要使用 `selectable: false` 的候选。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 第二步：提交候选并直接获取最终报价
|
|
|
|
|
|
### 接口
|
|
|
|
|
|
```http
|
|
|
POST /api/host/quote/submit
|
|
|
```
|
|
|
|
|
|
### 请求头
|
|
|
|
|
|
与第一步相同（须带 `Authorization` 与 `X-Customer-Id`）。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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` 让你继续轮询；服务端会自己处理轮询
|
|
|
|
|
|
### 成功响应示例
|
|
|
|
|
|
```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） |
|
|
|
| `quotes[].carrier` | 承运商 |
|
|
|
| `quotes[].transit_days` | 时效 |
|
|
|
| `valid_until` | 报价有效期 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 调用步骤总结
|
|
|
|
|
|
### 业务步骤
|
|
|
|
|
|
1. 带鉴权头调 `POST /api/host/quote/candidates`
|
|
|
2. 取得 `host_session_id`
|
|
|
3. 让用户在候选地址中各选一条可用地址
|
|
|
4. 带鉴权头调 `POST /api/host/quote/submit`
|
|
|
5. 直接拿最终报价并展示
|
|
|
|
|
|
### 第三方系统需要做的事
|
|
|
|
|
|
- 在服务端保存 Token，**不要**暴露在前端
|
|
|
- 每次请求携带 `Authorization` + `X-Customer-Id: CUST_001`
|
|
|
- 第一步展示候选地址选择 UI
|
|
|
- 第二步显示 Loading（建议超时 ≥ 420 秒）
|
|
|
- 第二步返回后展示报价
|
|
|
|
|
|
### 第三方系统不需要做的事
|
|
|
|
|
|
- 不需要 `GET /api/quotes/{id}` 轮询
|
|
|
- 不需要自己做 kg/cm 到 lb/in 的换算
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 单位说明
|
|
|
|
|
|
接口支持：
|
|
|
|
|
|
- 重量：`kg` / `lb`
|
|
|
- 尺寸：`cm` / `in`
|
|
|
|
|
|
例如：
|
|
|
|
|
|
```json
|
|
|
"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 示例（第一步）
|
|
|
|
|
|
```bash
|
|
|
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 一致
|
