查价嵌入示例

# 查价系统 · 网页嵌入对接文档（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 浏览器地址栏直开（推荐先测）把 `` 换成真实 Key，整段粘贴到浏览器： ```text https://if.dev.51track.vip/embed-demo?login_type=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":""}' ``` 成功示例（字段可能略多，以 `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 查价嵌入示例 ``` 服务端伪代码： ```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=&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`。