|
|
# MotherShip 查询接口调用文档
|
|
|
|
|
|
> **第三方正式对接请优先阅读**：同目录 [`api对接文档.md`](./api对接文档.md)（v1.1，**四路线**：MotherShip/Flock × 免账号/登录后）。
|
|
|
> 本文档保留 MotherShip 宿主两步 + 管理端接口细项，适合内部运维对照；Flock / 登录后字段以对接文档为准。
|
|
|
|
|
|
本文档说明 **MotherShip / Axel** 查询报价相关接口（偏免账号宿主两步），适合内部运维对照使用。
|
|
|
|
|
|
Base URL：`https://if.dev.51track.vip`
|
|
|
|
|
|
统一响应格式：
|
|
|
|
|
|
```json
|
|
|
{ "code": 0, "message": "ok", "data": { } }
|
|
|
```
|
|
|
|
|
|
`code !== 0` 为业务/鉴权错误。询价业务失败时 HTTP 可能仍为 `200`，此时看 `data.status === "failed"`。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 推荐接口（第三方宿主）
|
|
|
|
|
|
当前推荐使用 **两步宿主接口**（须鉴权）：
|
|
|
|
|
|
1. `POST /api/host/quote/candidates`
|
|
|
2. `POST /api/host/quote/submit`
|
|
|
|
|
|
特点：
|
|
|
|
|
|
- 第一步返回提货 / 派送地址候选
|
|
|
- 第二步服务端内部等待询价并同步返回最终报价
|
|
|
- 调用方**不需要**自己轮询 `GET /api/quotes/{id}`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 鉴权（必传）
|
|
|
|
|
|
当前服务器已关闭公开免 Token 模式（`HOST_PUBLIC_API_ENABLED=false`），**每次请求**须携带：
|
|
|
|
|
|
```http
|
|
|
Authorization: Bearer <API Key 或 Service Token>
|
|
|
X-Customer-Id: <Customer ID>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
| 字段 | 说明 |
|
|
|
|------|------|
|
|
|
| `Authorization` | `Bearer` + 我方发放的凭证 |
|
|
|
| `X-Customer-Id` | 客户 ID，必须与凭证绑定一致 |
|
|
|
| `Content-Type` | 固定 `application/json` |
|
|
|
|
|
|
### 2.1 凭证来源（二选一）
|
|
|
|
|
|
| 类型 | 形态 | 来源 |
|
|
|
|------|------|------|
|
|
|
| **客户 API Key（推荐给第三方）** | 通常以 `chj_` 开头 | 管理端「客户管理」新建客户 / 轮换 Key 后发放 |
|
|
|
| Service Token | 自定义字符串，如 `demo-host-token` | 服务器 `.env` 的 `HOST_SERVICE_TOKENS`（联调/内网） |
|
|
|
|
|
|
第三方正式对接请使用管理端发放的 **API Key**，不要把 Key 写进前端页面或公开仓库。
|
|
|
|
|
|
### 2.2 请求头示例
|
|
|
|
|
|
```http
|
|
|
Authorization: Bearer chj_xxxxxxxxxxxxxxxxxxxxx
|
|
|
X-Customer-Id: CUST_003
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
联调可用 env Token（若服务器已配置）：
|
|
|
|
|
|
```http
|
|
|
Authorization: Bearer demo-host-token
|
|
|
X-Customer-Id: CUST_001
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
### 2.3 鉴权错误
|
|
|
|
|
|
| HTTP | message | 说明 |
|
|
|
|------|---------|------|
|
|
|
| 401 | 缺少 Authorization 头 | 未带 Bearer |
|
|
|
| 401 | Service Token 无效 | Key/Token 错误或已轮换失效 |
|
|
|
| 403 | customer_id 与令牌租户不匹配 | `X-Customer-Id` 与 Key 绑定不一致 |
|
|
|
| 401 | 令牌无效或已过期 | 误用了管理员 JWT，应使用 API Key / Service Token |
|
|
|
|
|
|
### 2.4 Apifox 环境变量
|
|
|
|
|
|
| 变量 | 示例值 |
|
|
|
|------|--------|
|
|
|
| `baseUrl` | `https://if.dev.51track.vip` |
|
|
|
| `token` | 管理端发放的 `chj_...` 或联调 `demo-host-token` |
|
|
|
| `customerId` | 与 Token 绑定的客户 ID，如 `CUST_001` |
|
|
|
|
|
|
Headers：
|
|
|
|
|
|
- `Authorization`：`Bearer {{token}}`
|
|
|
- `X-Customer-Id`：`{{customerId}}`
|
|
|
- `Content-Type`：`application/json`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 第一步：获取联想地址候选
|
|
|
|
|
|
### 接口
|
|
|
|
|
|
```http
|
|
|
POST /api/host/quote/candidates
|
|
|
```
|
|
|
|
|
|
### 请求头
|
|
|
|
|
|
```http
|
|
|
Authorization: Bearer <API Key>
|
|
|
X-Customer-Id: <Customer ID>
|
|
|
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` | 否 | 建议传，格式 `12345` 或 `12345-6789` |
|
|
|
| `cargo.weight.value` | 是 | 单托重量 |
|
|
|
| `cargo.weight.unit` | 是 | `lb`、`kg` 或 `t`/`tonne`（公制吨；禁止 `ton`/`tons`） |
|
|
|
| `cargo.dimensions.*` | 是 | 单托长宽高 |
|
|
|
| `cargo.dimensions.unit` | 是 | `in`、`cm` 或 `m` |
|
|
|
| `cargo.pallet_count` | 是 | 托盘数，1–25 |
|
|
|
| `cargo.cargo_type` | 是 | 见下方枚举 |
|
|
|
|
|
|
**货物类型 `cargo_type`：**
|
|
|
|
|
|
`general_freight` · `machinery` · `furniture` · `electronics` · `building_materials` · `auto_parts` · `food_nonperishable` · `apparel` · `other`
|
|
|
|
|
|
服务端会自动把 `lb`/`kg`/`t`、`in`/`cm`/`m` 换算为 MotherShip 需要的英制单位（小数进一）。
|
|
|
|
|
|
### 成功响应示例
|
|
|
|
|
|
```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. 第二步提交时传回选中的**完整候选对象**（不要只传 `option_id`）
|
|
|
|
|
|
不要使用 `selectable: false` 的候选（可能带 `unavailable_reason`）。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 第二步：提交候选并获取最终报价
|
|
|
|
|
|
### 接口
|
|
|
|
|
|
```http
|
|
|
POST /api/host/quote/submit
|
|
|
```
|
|
|
|
|
|
### 请求头
|
|
|
|
|
|
与第一步相同。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```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` 必须来自第一步
|
|
|
- 候选对象必须是第一步列表中的完整对象（`option_id` 须匹配）
|
|
|
- HTTP 连接可能保持 **10–420 秒**；客户端 / Nginx 超时建议 ≥ **420 秒**
|
|
|
- **不会**返回 `processing` 让你继续轮询；服务端内部完成等待
|
|
|
|
|
|
### 成功响应示例
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "ok",
|
|
|
"data": {
|
|
|
"quote_id": "QTE_20260630_0003",
|
|
|
"request_id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx",
|
|
|
"status": "done",
|
|
|
"currency": "USD",
|
|
|
"valid_until": "2026-06-30T10:30:00.000Z",
|
|
|
"source_type": "rpa",
|
|
|
"quotes": [
|
|
|
{
|
|
|
"service_level": "standard",
|
|
|
"rate_option": "lowest",
|
|
|
"carrier": "Frontline Freight",
|
|
|
"transit_days": "Est. 5 business days",
|
|
|
"final_total": 337.06
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 说明 |
|
|
|
|------|------|
|
|
|
| `status` | `done` 成功；`failed` 失败（看 `error_message`） |
|
|
|
| `quotes[].final_total` | **对客户展示价（USD，含加价）** |
|
|
|
| `quotes[].carrier` | 承运商 |
|
|
|
| `quotes[].transit_days` | 时效 |
|
|
|
| `valid_until` | 报价有效期 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 调用步骤总结
|
|
|
|
|
|
1. 带鉴权头调 `POST /api/host/quote/candidates`
|
|
|
2. 保存 `host_session_id`，让用户各选一条可用地址
|
|
|
3. 带鉴权头调 `POST /api/host/quote/submit`
|
|
|
4. 直接展示最终报价
|
|
|
|
|
|
### 第三方需要做
|
|
|
|
|
|
- API Key 放服务端，不暴露前端
|
|
|
- 每次请求带 `Authorization` + `X-Customer-Id`
|
|
|
- 第一步做地址选择 UI；第二步 Loading（超时 ≥ 420s）
|
|
|
|
|
|
### 第三方不需要做
|
|
|
|
|
|
- 不需要 `GET /api/quotes/{id}` 轮询
|
|
|
- 不需要自己做公制 → 英制换算（支持 `kg`/`t`/`cm`/`m`，服务端统一进一取整为 lb/in）
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. Apifox / cURL
|
|
|
|
|
|
### Apifox
|
|
|
|
|
|
| 步骤 | 方法 | URL |
|
|
|
|------|------|-----|
|
|
|
| 1 | POST | `{{baseUrl}}/api/host/quote/candidates` |
|
|
|
| 2 | POST | `{{baseUrl}}/api/host/quote/submit` |
|
|
|
|
|
|
第二步超时建议：`420000` ms。
|
|
|
|
|
|
### cURL（第一步）
|
|
|
|
|
|
```bash
|
|
|
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 @host-candidates-req.json
|
|
|
```
|
|
|
|
|
|
PowerShell（本机测公网，不要写 `127.0.0.1`，不要加 `:30325`）：
|
|
|
|
|
|
```powershell
|
|
|
curl.exe -s -w "`nHTTP: %{http_code}`n" `
|
|
|
-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"
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 常见错误
|
|
|
|
|
|
| code | HTTP | 说明 | 处理 |
|
|
|
|------|------|------|------|
|
|
|
| `UNAUTHORIZED` | 401 | 缺少或无效 Token/API Key | 检查 Bearer 与客户绑定 |
|
|
|
| `FORBIDDEN` | 403 | 客户 ID 与令牌不匹配 | 核对 `X-Customer-Id` |
|
|
|
| `VALIDATION_FAILED` | 400 | 参数不合法 / JSON 无效 | 检查字段、单位、州码 |
|
|
|
| `SESSION_EXPIRED` | 404 | `host_session_id` 过期 | 重新调第一步 |
|
|
|
| `ADDRESS_SESSION_MISMATCH` | 400 | 候选不在本次联想结果中 | 使用第一步返回的完整对象 |
|
|
|
| `ADDRESS_NOT_SELECTABLE` | 400 | 选了不可用候选 | 改用 `selectable: true` |
|
|
|
| `QUOTE_TIMEOUT` | 504 | 服务端等待超时 | 稍后重试 |
|
|
|
| `RATE_LIMITED` | 429 | 限流 | 降低频率 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. 客户管理接口（管理员）
|
|
|
|
|
|
供**管理端 / 内部运维**使用，不提供给第三方宿主直接调用。
|
|
|
|
|
|
### 8.1 鉴权
|
|
|
|
|
|
```http
|
|
|
Authorization: Bearer <Admin JWT>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
管理员 JWT 通过 `POST /api/auth/login` 获取（账号密码登录）。
|
|
|
|
|
|
### 8.2 获取客户列表
|
|
|
|
|
|
```http
|
|
|
GET /api/admin/customers?page=1&size=10&keyword=CUST_001
|
|
|
```
|
|
|
|
|
|
| 参数 | 必填 | 说明 |
|
|
|
|------|------|------|
|
|
|
| `page` | 是 | 页码，从 1 开始 |
|
|
|
| `size` | 是 | 每页 1–100 |
|
|
|
| `keyword` | 否 | 按客户 ID / 名称模糊搜索 |
|
|
|
|
|
|
成功时 `data.list[]` 主要字段：
|
|
|
|
|
|
| 字段 | 说明 |
|
|
|
|------|------|
|
|
|
| `customer_id` | 客户 ID |
|
|
|
| `status` | `active` / `disabled` |
|
|
|
| `embed_password_set` | 是否已设 `/embed-demo` 密码 |
|
|
|
| `active_api_key` | 当前有效 API Key；历史未保存原文时可能为 `null` |
|
|
|
| `api_keys[]` | Key 摘要（不含完整原文，仅前缀等） |
|
|
|
|
|
|
### 8.3 新建客户
|
|
|
|
|
|
```http
|
|
|
POST /api/admin/customers
|
|
|
```
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"name": "演示客户 003",
|
|
|
"remark": "重点客户",
|
|
|
"embed_password": "123456"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 必填 | 说明 |
|
|
|
|------|------|------|
|
|
|
| `name` | 是 | 客户名称 |
|
|
|
| `remark` | 否 | 备注 |
|
|
|
| `embed_password` | 否 | `/embed-demo` 登录密码；不传默认 `123456` |
|
|
|
|
|
|
响应中 `api_key` **仅在新建时额外返回一次**；同时写入 `active_api_key`。请立即保存发给第三方。
|
|
|
|
|
|
### 8.4 更新客户
|
|
|
|
|
|
```http
|
|
|
PATCH /api/admin/customers/{customer_id}
|
|
|
```
|
|
|
|
|
|
可更新：`name`、`remark`、`status`（`active`/`disabled`）、`embed_password`（至少 6 位）。
|
|
|
|
|
|
### 8.5 轮换 API Key
|
|
|
|
|
|
```http
|
|
|
POST /api/admin/customers/{customer_id}/rotate-key
|
|
|
```
|
|
|
|
|
|
- 原有效 Key 立即失效
|
|
|
- 响应中的 `api_key` 与 `active_api_key` 为新 Key
|
|
|
- 轮换后须通知第三方更换凭证
|
|
|
|
|
|
### 8.6 承运商官网账密（管理端）
|
|
|
|
|
|
```http
|
|
|
GET /api/admin/customers/{customer_id}/provider-credentials
|
|
|
PUT /api/admin/customers/{customer_id}/provider-credentials
|
|
|
```
|
|
|
|
|
|
用于绑定客户在 MotherShip / Flock 官网的登录账密（RPA 使用），**非第三方宿主对接接口**。
|
|
|
|
|
|
PUT 请求体示例：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"provider": "mothership",
|
|
|
"email": "user@example.com",
|
|
|
"password": "********"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 约束 | 说明 |
|
|
|
|------|------|
|
|
|
| `provider` | 仅 `mothership` 或 `flock` |
|
|
|
| 写入策略 | 仅允许首次绑定；已绑定后不可修改 / 清除 |
|
|
|
| 清除 | 不支持 `clear`；更换需新建客户 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 9. 嵌入演示登录
|
|
|
|
|
|
供 `/embed-demo` 演示页使用，不是正式宿主 API。
|
|
|
|
|
|
### 9.1 登录
|
|
|
|
|
|
```http
|
|
|
POST /api/embed-demo/login
|
|
|
```
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"customer_id": "CUST_003",
|
|
|
"password": "cust003@2026"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
- 密码以管理端「客户管理」中为该客户设置的为准
|
|
|
- 成功后写入 HttpOnly Cookie：`embed_demo_session`
|
|
|
|
|
|
### 9.2 当前会话 / 退出
|
|
|
|
|
|
```http
|
|
|
GET /api/embed-demo/me
|
|
|
POST /api/embed-demo/logout
|
|
|
```
|
|
|
|
|
|
`me` 依赖登录 Cookie，返回当前客户及加价配置。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 10. 其它渠道说明（非推荐宿主对接）
|
|
|
|
|
|
以下接口同样需要 Service Token / API Key，但**返回 `processing`，需客户端轮询**，不作为第三方默认同步对接方案：
|
|
|
|
|
|
| 渠道 | 提交 | 轮询 |
|
|
|
|------|------|------|
|
|
|
| MotherShip 旧三步 | `POST /api/quotes` 等 | `GET /api/quotes/{quote_id}` |
|
|
|
| Priority1 | `POST /api/priority1/quotes` | 同上 |
|
|
|
| Flock | `POST /api/flock/quotes` | 同上 |
|
|
|
|
|
|
第三方正式对接请优先使用本文档第 1–4 节的两步宿主接口。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 11. 联系与支持
|
|
|
|
|
|
- Token / API Key 失效或需开通新客户：联系我方运维 / 管理端操作
|
|
|
- `X-Customer-Id` 必须与发放凭证绑定一致，不可串用
|
|
|
- 老客户若 `active_api_key` 为空：在管理端「轮换 Key」一次后再查看
|
