|
|
# 查价系统 · 网页嵌入对接文档（iframe）
|
|
|
|
|
|
**版本**：1.0
|
|
|
**更新日期**：2026-07-22
|
|
|
**适用对象**：CC / 宿主前端 / 需在自有页面内嵌查价 UI 的第三方
|
|
|
**联调环境**：`https://if.dev.51track.vip`
|
|
|
**正式环境**：以我方书面通知为准（路径不变）
|
|
|
|
|
|
> 本文档可独立使用。完整 OpenAPI（服务端两步查价）见同目录 `api对接文档.md`。
|
|
|
> **宿主 postMessage 预填 / 回传报价**：见同目录 **`嵌入-postMessage对接文档.md`**（四模块区分 + 填什么 / 回什么）。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 一句话结论
|
|
|
|
|
|
宿主用 **iframe** 打开下面 URL（**由宿主服务端**把客户 API Key 拼进 `src`），用户**不会看到**嵌入登录页，直接进入 **MotherShip / Flock Freight** 两模块门户。
|
|
|
|
|
|
```text
|
|
|
https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=<客户API_Key>&embed=1
|
|
|
```
|
|
|
|
|
|
直进 MotherShip 登录后「创建新货件」（跳过模块点选；须已绑官网账密）：
|
|
|
|
|
|
```text
|
|
|
https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=<客户API_Key>&embed=1&module=MS_LOGGED_IN
|
|
|
```
|
|
|
|
|
|
等价参数：`entry=ms_logged_in`。宿主 postMessage 预填见 **`嵌入-postMessage对接文档.md`**。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 5 分钟自测（复制即用）
|
|
|
|
|
|
### 2.1 准备
|
|
|
|
|
|
| 项 | 值 |
|
|
|
|----|-----|
|
|
|
| Base | `https://if.dev.51track.vip` |
|
|
|
| 路径 | `/embed-demo` |
|
|
|
| 凭证 | 管理端发给该客户的 **API Key**（与 OpenAPI 同一把） |
|
|
|
|
|
|
**联调环境样例 Key**（仅 `if.dev`，与 `.env.example` 一致；正式客户勿用）：
|
|
|
|
|
|
```text
|
|
|
https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=demo-host-token&embed=1
|
|
|
```
|
|
|
|
|
|
已在联调环境实测：打开后直进两模块门户（CUST_001），地址栏 Key 被剥离。
|
|
|
|
|
|
### 2.2 浏览器地址栏直开（推荐先测）
|
|
|
|
|
|
把 `<API_Key>` 换成真实 Key，整段粘贴到浏览器：
|
|
|
|
|
|
```text
|
|
|
https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=<API_Key>&embed=1
|
|
|
```
|
|
|
|
|
|
**通过标准**：
|
|
|
|
|
|
1. 页面**不出现**「客户登录」表单（账号/密码/API Key 输入框）。
|
|
|
2. 出现 **MotherShip**、**Flock Freight** 两个模块入口（卡片）。
|
|
|
3. 地址栏里的 `api_key` 等敏感参数在进入后会被清掉（只剩 `/embed-demo` 或少量无关参数）。
|
|
|
4. 点进某一模块可继续选「免账号 / 登录后」查价。
|
|
|
|
|
|
**失败对照**：
|
|
|
|
|
|
| 现象 | 原因 | 处理 |
|
|
|
|------|------|------|
|
|
|
| 仍停在登录页 | 未带 Key，或参数名写错 | 核对 `api_key` / `login_type` |
|
|
|
| 红字「API Key 无效」等 | Key 错、已轮换、客户停用 | 管理端核对 |
|
|
|
| 空白 / 一直骨架屏 | 网络或域名不可达 | 换网络；确认 Base |
|
|
|
|
|
|
### 2.3 仅测登录接口（不打开页面）
|
|
|
|
|
|
```bash
|
|
|
curl -sS -X POST "https://if.dev.51track.vip/api/embed-demo/login" \
|
|
|
-H "Content-Type: application/json" \
|
|
|
-d '{"login_type":"api_key","api_key":"<API_Key>"}'
|
|
|
```
|
|
|
|
|
|
成功示例（字段可能略多，以 `code=0` 为准）：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "ok",
|
|
|
"data": {
|
|
|
"customer_id": "CUST_001",
|
|
|
"login_type": "api_key"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
失败：`code != 0`，HTTP 多为 401/403/400。
|
|
|
|
|
|
### 2.4 宿主页面 iframe（上线形态）
|
|
|
|
|
|
**Key 必须由宿主后端渲染进 HTML**，禁止写死在公开前端仓库 / 静态 CDN。
|
|
|
|
|
|
```html
|
|
|
<!DOCTYPE html>
|
|
|
<html lang="zh-CN">
|
|
|
<head>
|
|
|
<meta charset="utf-8" />
|
|
|
<title>查价嵌入示例</title>
|
|
|
<style>
|
|
|
html, body { margin: 0; height: 100%; }
|
|
|
iframe { width: 100%; height: 100%; border: 0; display: block; }
|
|
|
</style>
|
|
|
</head>
|
|
|
<body>
|
|
|
<!-- src 由服务端模板注入，勿在纯静态站写死 Key -->
|
|
|
<iframe
|
|
|
title="查价"
|
|
|
src="https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=REPLACE_WITH_API_KEY&embed=1"
|
|
|
allow="clipboard-read; clipboard-write"
|
|
|
></iframe>
|
|
|
</body>
|
|
|
</html>
|
|
|
```
|
|
|
|
|
|
服务端伪代码：
|
|
|
|
|
|
```text
|
|
|
src = base + "/embed-demo"
|
|
|
+ "?login_type=api_key"
|
|
|
+ "&api_key=" + url_encode(客户API_Key)
|
|
|
+ "&embed=1"
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. URL 参数一览
|
|
|
|
|
|
| 参数 | 必填 | 说明 | 别名 |
|
|
|
|------|------|------|------|
|
|
|
| `login_type` | 建议填 | `api_key`（推荐）或 `password` | `type`、`lt` |
|
|
|
| `api_key` | Key 登录必填 | 客户 API Key | `key`、`token` |
|
|
|
| `customer_id` | 密码登录必填 | 客户编号 | `customerId` |
|
|
|
| `password` | 密码登录必填 | 嵌入页客户密码 | `pwd` |
|
|
|
| `embed` | 建议 `1` | 宿主托管壳（隐藏「退出登录」等） | `hosted`、`from_cc`、`from_host` |
|
|
|
| `module` | 否 | 直进模块：`MS_GUEST` / `MS_LOGGED_IN` / `FLOCK_GUEST` / `FLOCK_LOGGED_IN` | `quote_module` |
|
|
|
| `entry` | 否 | 同上短写：`ms_logged_in` 等 | `default_module` |
|
|
|
|
|
|
规则：
|
|
|
|
|
|
- 只带 `api_key`（或 `key`）且不写 `login_type` → 按 **API Key 登录**。
|
|
|
- 短写等价：`?type=api_key&key=<API_Key>&embed=1`
|
|
|
|
|
|
账号密码直登（少用）：
|
|
|
|
|
|
```text
|
|
|
https://if.dev.51track.vip/embed-demo?login_type=password&customer_id=<客户编号>&password=<密码>&embed=1
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 登录成功后用户看到什么
|
|
|
|
|
|
1. **两模块门户**：MotherShip、Flock Freight。
|
|
|
2. 每个模块内可选：
|
|
|
- **免账号**：不绑官网账密即可查（受官网/货物硬限约束）。
|
|
|
- **登录后**：须已在管理端或嵌入页内绑定对应官网账密。
|
|
|
3. 查价结果在嵌入页内展示；不替代宿主侧 OpenAPI 下单流程（若有）。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 行为与安全（必读）
|
|
|
|
|
|
| 步骤 | 行为 |
|
|
|
|------|------|
|
|
|
| 1 | 打开 `/embed-demo` → 前端解析查询串 |
|
|
|
| 2 | `POST /api/embed-demo/login`（`login_type` + 凭证） |
|
|
|
| 3 | 成功 → 写嵌入会话 Cookie → 进门户（**跳过登录表单**） |
|
|
|
| 4 | `history.replaceState` 去掉地址栏中的 Key/密码 |
|
|
|
| 5 | 失败 → 错误文案 + 可回落手动登录 |
|
|
|
|
|
|
安全约定：
|
|
|
|
|
|
- **仅允许**宿主服务端短时把 Key 拼进 `iframe.src`；用户侧会短暂可见，成功后剥离。
|
|
|
- 生产 Cookie：`SameSite=None; Secure`（跨站 iframe 必需 HTTPS）。
|
|
|
- OpenAPI 仍走 `Authorization` 头，**不能**用本嵌入 URL 代替服务端调价接口鉴权。
|
|
|
- 勿把 Key 提交进 Git、前端包、移动端安装包。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 与 OpenAPI 的关系
|
|
|
|
|
|
| | 网页嵌入（本文） | OpenAPI |
|
|
|
|--|------------------|---------|
|
|
|
| 用途 | 给人点选查价 UI | 宿主服务端程序化查价 |
|
|
|
| 鉴权 | URL 短时带 Key → Cookie | 请求头 `Authorization` |
|
|
|
| 文档 | 本文 | `api对接文档.md` |
|
|
|
|
|
|
两条可并存：同一客户同一把 API Key。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 验收清单（对接方打勾）
|
|
|
|
|
|
- [ ] 地址栏直开带 Key：无登录表单，有两模块卡片
|
|
|
- [ ] `POST /api/embed-demo/login` 返回 `code=0`
|
|
|
- [ ] 宿主 HTTPS 页 iframe 可加载且会话不丢（刷新仍登录）
|
|
|
- [ ] Key **未**写进公开前端仓库
|
|
|
- [ ] 错 Key 时有明确错误，而非白屏
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. 联系与变更
|
|
|
|
|
|
参数名、路径变更以本文件版本号为准；重大变更另行通知。联调问题请提供：完整 `iframe.src`（**打码 Key**）、浏览器控制台 Network 中 `/api/embed-demo/login` 的状态码与响应 `code`/`message`。
|
