7.0 KiB

Raw Permalink Blame History Unescape Escape

查价系统 · 网页嵌入对接文档（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 两模块门户。

https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=<客户API_Key>&embed=1

直进 MotherShip 登录后「创建新货件」（跳过模块点选；须已绑官网账密）：

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 一致；正式客户勿用）：

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，整段粘贴到浏览器：

https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=<API_Key>&embed=1

通过标准：

页面不出现「客户登录」表单（账号/密码/API Key 输入框）。
出现 MotherShip、Flock Freight 两个模块入口（卡片）。
地址栏里的 api_key 等敏感参数在进入后会被清掉（只剩 /embed-demo 或少量无关参数）。
点进某一模块可继续选「免账号 / 登录后」查价。

失败对照：

现象	原因	处理
仍停在登录页	未带 Key，或参数名写错	核对 `api_key` / `login_type`
红字「API Key 无效」等	Key 错、已轮换、客户停用	管理端核对
空白 / 一直骨架屏	网络或域名不可达	换网络；确认 Base

2.3 仅测登录接口（不打开页面）

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 为准）：

{
  "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。

<!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>

服务端伪代码：

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

账号密码直登（少用）：

https://if.dev.51track.vip/embed-demo?login_type=password&customer_id=<客户编号>&password=<密码>&embed=1

4. 登录成功后用户看到什么

两模块门户：MotherShip、Flock Freight。
每个模块内可选：
- 免账号：不绑官网账密即可查（受官网/货物硬限约束）。
- 登录后：须已在管理端或嵌入页内绑定对应官网账密。
查价结果在嵌入页内展示；不替代宿主侧 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。

7.0 KiB Raw Permalink Blame History Unescape Escape