chajia/api调用文档/api对接文档.md

美美与共查价系统 · 宿主 OpenAPI 技术对接文档

版本：1.2
更新日期：2026-07-22
适用对象：第三方宿主系统（服务端对接 / 网页嵌入）

---

1. 文档说明

本文档供第三方宿主系统对接「美美与共查价中台」使用。

中台对接 两个官网，每个官网各有 免账号 / 登录后 两种查价方式，合计 四条互斥路线：

路线 ID	官网	账密	说明
MS_GUEST	MotherShip	无	免登录 Widget / Direct 路径
MS_LOGGED_IN	MotherShip	有（该客户已绑定 MotherShip 账密）	官网 Create shipment 登录态路径
FLOCK_GUEST	Flock Freight	无	免登录 Direct（失败可回退 DOM）
FLOCK_LOGGED_IN	Flock Freight	有（该客户已绑定 Flock 账密）	强制官网登录 DOM，禁止 Direct

核心规则：根据「用户/宿主上传的承运商账密」与「本票货物/地址参数是否符合某官网硬限」判定路线后，整票只走一条路线，禁止混用上限、混用接口、混用结果字段。

本文档仅列出对调用方有意义且可依赖的字段。响应中如出现未在本文档定义的其他字段，均属于平台保留字段，调用方不应依赖。

对接形态：

形态	说明	见章节
OpenAPI 服务端调用	宿主后端带 API Key 调两步查价接口	§2～§6
网页嵌入（iframe）	宿主页面嵌查价 UI；须直传类型+Key，跳过登录页	§2.5

安全要求：API Key、承运商官网账密仅允许保存在宿主服务端或经我方管理端加密存储；禁止写入宿主公开前端仓库、移动端安装包。OpenAPI 调用禁止把 Key 放进 URL；iframe 嵌入仅允许由宿主服务端在生成 iframe.src 时短时拼入查询串（见 §2.5）。

---

2. 接入信息

2.1 基础地址

环境	Base URL
当前联调 / 演示	https://if.dev.51track.vip

公网访问不要追加端口（如 :30325）。:30325 仅用于服务器本机调试。

嵌入页路径：{Base URL}/embed-demo

2.2 请求格式

• 请求方法：以各接口定义为准
• 请求体：JSON
• 字符编码：UTF-8
• Content-Type：application/json

2.3 鉴权请求头（OpenAPI）

请求头	必填	说明
Authorization	是	Bearer <API Key>；Key 通常以 chj_ 开头，由我方管理端发放
X-Customer-Id	是	客户 ID，必须与 API Key 绑定一致
Content-Type	是	固定为 application/json

本次联调凭证（示例，正式值由我方单独发放）：

配置项	值	说明
API Key	<由我方发放>	放入 Authorization: Bearer ...
Customer ID	<由我方发放>	放入 X-Customer-Id

注意（OpenAPI）：API Key 不得放入 URL、请求体或业务日志明文。

请求头示例：

Authorization: Bearer chj_xxxxxxxxxxxxxxxxxxxxx
X-Customer-Id: CUST_001
Content-Type: application/json

内网联调若使用环境 Token（非正式第三方形态）：

Authorization: Bearer demo-host-token
X-Customer-Id: CUST_001
Content-Type: application/json

2.4 通用响应结构

字段	类型	说明
code	Number / String	0 表示接口调用成功；非 0 表示鉴权、参数或业务处理失败
message	String	提示信息；成功时通常为 ok
data	Object / null	成功时的业务数据；失败时多为 null

2.5 网页嵌入（iframe / CC 等宿主）— 跳过登录页

2.5.1 目标

宿主将查价系统嵌进自有页面时：

1. 用户不应再看到嵌入页「客户登录」表单。
2. 宿主传入 登录类型 + 凭证 后，直接进入 MotherShip / Flock Freight 两模块门户。
3. 模块内可再选「免账号 / 登录后」；登录后路线需已绑定承运商官网账密（可在嵌入页内配置）。

2.5.2 URL 查询参数

参数	必填	说明
login_type	建议	api_key 或 password；别名：type、lt
api_key	Key 登录必填	客户 API Key；别名：key、token
customer_id	密码登录必填	客户编号；别名：customerId
password	密码登录必填	嵌入页客户密码；别名：pwd
embed	可选	1 / true：宿主托管壳（隐藏「退出登录」）；别名：hosted、from_cc、from_host

仅带 api_key（或 key）且未写 login_type 时，按 api_key 登录处理。

2.5.3 推荐写法（CC：API Key）

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

短写：

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

iframe 示例（Key 须由宿主后端渲染进 HTML，禁止写死在公开前端仓库）：

<iframe
  title="查价"
  src="https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=chj_xxxxxxxx&embed=1"
  style="width:100%;height:900px;border:0;"
  allow="clipboard-read; clipboard-write"
></iframe>

账号密码直登（较少用）：

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

2.5.4 行为与安全

步骤	行为
1	打开嵌入页 → 读取查询串 → 调用 POST /api/embed-demo/login
2	成功 → 写入嵌入会话 Cookie → 进入两模块门户（不展示登录页）
3	前端 history.replaceState 去掉地址栏中的 Key/密码等敏感参数
4	失败 → 展示错误文案，并可回落手动登录表单

安全约定：

• Key 只允许宿主服务端拼进 iframe.src；用户浏览器地址栏会短暂可见，登录成功后会被剥离。
• 生产环境嵌入 Cookie 使用 SameSite=None; Secure，以支持跨站 iframe。
• 勿在公开仓库、前端构建产物、CDN 静态配置中明文提交 API Key。
• OpenAPI 仍须走 Authorization 头（§2.3），与嵌入 URL 直传互不替代。

2.5.5 常见错误

现象	可能原因	处理
仍停在登录页	未传 api_key / login_type，或 Key 为空	检查 iframe src
提示 API Key 无效	Key 错误、已轮换、或客户停用	管理端核对 Key 与客户状态
提示缺少 Authorization	宿主在调 OpenAPI 时未带鉴权头	与嵌入无关；按 §2.3 补头
登录成功但刷新掉登录	跨站 Cookie 被拦 / 非 HTTPS	确认生产 HTTPS；Cookie 为 None+Secure

成功响应示例（OpenAPI 通用）：

{
  "code": 0,
  "message": "ok",
  "data": { }
}

失败响应示例：

{
  "code": "VALIDATION_FAILED",
  "message": "请填写 2 位州码",
  "data": null
}

调用方不能仅根据 HTTP 状态码判断业务成功。仅当 code = 0 时，才能判定本次接口调用成功。
异步询价业务失败时，轮询接口可能仍返回 HTTP 200 且 code = 0，此时须检查 data.status：若为 failed，按失败处理并展示 data.error_message。

---

3. 路线判定（必读）

宿主在发起询价前，按下列顺序 确定唯一路线，然后只调用该路线对应接口与字段。

3.1 判定流程

1) 宿主明确选择官网，或按参数硬限自动匹配：
   - 符合 MotherShip 硬限且业务选 MotherShip → 进入 MS_*
   - 符合 Flock 硬限且业务选 Flock → 进入 FLOCK_*
   - 两网站都不符合 → 拒绝询价，提示用户改货改地址
   - 禁止：同一票并行打两家再拼结果（除非宿主产品明确要求「比价」且各自独立展示）

2) 查该客户在我方是否已绑定对应官网账密（管理端「查价网站账密」）：
   - MotherShip 已绑账密 → 必须走 MS_LOGGED_IN（服务端强制登录态，禁止匿名 Direct/缓存价）
   - MotherShip 未绑账密 → 走 MS_GUEST
   - Flock 已绑账密 → 必须走 FLOCK_LOGGED_IN（服务端强制 DOM 登录，禁止 Direct）
   - Flock 未绑账密 → 走 FLOCK_GUEST

3) 账密与参数必须同属一条路线：
   - 有 Flock 账密但货物只符合 MotherShip → 只能走 MS_*（Flock 账密本票不用）
   - 有 MotherShip 账密但货物只符合 Flock → 只能走 FLOCK_*
   - 有账密却按免账号字段凑合提交：服务端仍可能强制登录态，价格口径与免账号不同，宿主须按登录后字段规范传参

3.2 两官网硬限对照（换算后英制）

项	MotherShip（MS_*）	Flock（FLOCK_*）
地址形态	街道 + 城市 + 州码（建议邮编）；须经候选确认	仅邮编（5 位）；提货邮编 ≠ 派送邮编
托盘 / 件数	1～25	免账号 4～20；登录后 form_mode=logged_in_quick 时 1～999
单托重量	0.01～9999 lb；登录后 Weight each ≤ 5000 lb	按整票总重，≤ 45000 lb
尺寸	L≤999 in，W/H≤99 in	L≤636 in，W≤102 in，H≤108 in
其它	整票总重 ≤ 249975 lb	免账号须满足拖车线性英尺（约 53'）

重量 / 尺寸支持 lb/kg/t（公制吨）、in/cm/m 入参，服务端统一换算为 lb/in（小数进一取整）。宿主应在提交前按目标官网硬限拦截。

3.3 接口总览

路线	推荐调用链	等待方式	典型耗时
MS_GUEST	POST /api/host/quote/candidates → POST /api/host/quote/submit	同步（submit 内等待）	10～420 s
MS_LOGGED_IN	POST /api/addresses/mothership-suggest（可选）→ 组地址 → POST /api/quotes → GET /api/quotes/{quote_id}	异步轮询	轮询总窗口建议 ≥ 420 s
FLOCK_GUEST	POST /api/flock/quotes → GET /api/quotes/{quote_id}	异步轮询	建议 ≥ 210 s（可配置）
FLOCK_LOGGED_IN	同上；flock_input.form_mode = "logged_in_quick"	异步轮询	建议 ≥ 210 s

MS_GUEST 也可改用异步三步（POST /api/quotes + 轮询），但第三方默认同步对接请用宿主两步接口。
已绑定 MotherShip 账密时，即便误调宿主两步接口，服务端仍会强制登录态 RPA；宿主两步不支持登录后扩展字段（cargo_lines / mothership_details 等），完整登录后能力请走 MS_LOGGED_IN 异步接口。

---

4. 承运商账密（路线开关）

账密由我方管理端按客户绑定，RPA 运行时解密使用，不进入询价请求体。

4.1 管理端接口（内部运维，非宿主日常调用）

GET  /api/admin/customers/{customer_id}/provider-credentials
PUT  /api/admin/customers/{customer_id}/provider-credentials

需管理员 JWT。PUT 示例：

{
  "provider": "mothership",
  "email": "user@example.com",
  "password": "********"
}

字段	类型	必填	约束	说明
provider	String	是	mothership 或 flock	对应官网
email	String	是	非空	官网登录邮箱
password	String	是	非空	官网登录密码

影响：

• 绑定成功后，该客户对该 provider 自动切换到对应 *_LOGGED_IN 路线。
• 账密错误时询价可能返回 PROVIDER_LOGIN_FAILED（或业务失败 error_message 提示确认账密）。
• 更换账密须按管理端策略操作；勿在业务日志打印明文密码。

宿主侧若自行收集用户官网账密，应通过约定安全通道交给我方写入管理端，或由双方约定的 BFF 代写；询价 OpenAPI 请求体中不要传官网密码。

---

5. 路线 A：MotherShip 免账号（MS_GUEST）

适用：客户未绑定 MotherShip 账密；参数符合 MotherShip 硬限。

5.1 调用流程

1. 带鉴权头调用「获取地址候选」。
2. 保存 host_session_id（约 30 分钟有效）。
3. 用户从 pickup_candidates、delivery_candidates 各选 1 条 selectable = true。
4. 将完整候选对象与 host_session_id 提交「提交并获取报价」。
5. 第二步可能持续 10～420 秒；客户端与网关超时建议 ≥ 420 秒。
6. status = done 展示 quotes[]；failed 展示中文 error_message。

第二步期间展示 Loading，并禁止重复提交。

5.2 第一步：获取地址候选

接口地址

POST /api/host/quote/candidates

请求参数

字段	类型	必填	约束	说明
pickup_address	Object	是	见下表	提货草稿地址
delivery_address	Object	是	见下表	派送草稿地址
cargo	Object	是	见下表	货物信息

地址对象（pickup_address / delivery_address）

字段	类型	必填	约束	说明
street	String	是	非空	街道地址
city	String	是	非空	城市
state	String	是	固定 2 位	美国州二字码，如 CA、TX
zip	String	否	12345 或 12345-6789；可空	邮编；建议传

货物对象（cargo）

字段	类型	必填	约束	说明
weight.value	Number	是	正数	单托重量数值
weight.unit	String	是	lb、kg 或 t（公制吨）；别名 lbs/pound(s)/tonne(s)；禁止 ton/tons（美制短吨歧义）	重量单位
dimensions.length / width / height	Number	是	正数	单托尺寸
dimensions.unit	String	是	in、cm 或 m；别名 inch/meter 亦可	尺寸单位
pallet_count	Number	是	整数 1～25	托盘数
cargo_type	String	是	见 §12.1	货物类型枚举

请求示例：

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

响应数据

字段	类型	说明
data.host_session_id	String (UUID)	第二步必传；约 30 分钟有效
data.pickup_candidates	Array<Object>	提货候选
data.delivery_candidates	Array<Object>	派送候选
data.requires_selection	Boolean	是否需要用户选择

候选对象字段

字段	类型	说明
option_id	String	候选唯一标识
display_label	String	展示文案
formatted_address	String	格式化地址
street / city / state / zip	String	结构化地址
selectable	Boolean	仅可选 true
unavailable_reason	String	不可选原因（可能出现）

调用后处理规则

1. 必须保存 host_session_id。
2. 提货、派送各选 1 条 selectable = true。
3. 第二步必须回传第一步返回的完整候选对象，禁止只传 option_id，禁止自行拼装。
4. 会话过期后须重新调用本接口。

5.3 第二步：提交候选并获取报价

接口地址

POST /api/host/quote/submit

请求参数

字段	类型	必填	约束	说明
host_session_id	String	是	UUID；来自第一步	宿主会话 ID
pickup_candidate	Object	是	第一步完整候选	提货地址
delivery_candidate	Object	是	第一步完整候选	派送地址

超时与重试

• 客户端 HTTP 超时：420000 ms。
• 网关 proxy_read_timeout ≥ 420 秒。
• SESSION_EXPIRED：重新走第一步。
• QUOTE_TIMEOUT：可稍后重试；建议重新获取候选。

响应数据

字段	类型	说明
data.quote_id	String	报价单号
data.request_id	String	请求标识
data.status	String	done / failed
data.currency	String	固定 USD
data.valid_until	String	ISO 有效期
data.source_type	String	rpa / cache / stale 等
data.quotes	Array<Object>	档位列表
data.error_code / error_message	String	失败时

quotes[] 字段

字段	类型	说明
service_level	String	如 standard、guaranteed
rate_option	String	如 lowest、fastest、bestValue
carrier	String	承运商
transit_days	String	时效描述
final_total	Number	对客户展示价（USD，已含加价）

档位数量不固定，按实际列表展示。

成功响应示例：

{
  "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
      }
    ]
  }
}

---

6. 路线 B：MotherShip 登录后（MS_LOGGED_IN）

适用：客户已绑定 MotherShip 账密；参数符合 MotherShip 硬限（含登录后 Weight each ≤ 5000 lb）。

服务端检测到账密后会强制登录态查价，禁止命中匿名 Direct / L2 缓存价。

6.1 调用流程

1. （推荐）用 POST /api/addresses/mothership-suggest 按关键字联想，用户点选候选。
2. 组装完整询价体（含地址确认字段 + 可选登录后字段）。
3. POST /api/quotes → 得到 quote_id，status 多为 processing。
4. 轮询 GET /api/quotes/{quote_id} 至 done / failed（间隔建议 2 s，总窗口 ≥ 420 s）。
5. 成功时读 data.quotes[]（结构同 §5.3）。

6.2 地址联想（可选但推荐）

接口地址

POST /api/addresses/mothership-suggest

请求参数

字段	类型	必填	约束	说明
customer_id	String	是	与鉴权客户一致	客户 ID
query	String	是	去空白后 ≥ 3 字符	用户键入的地址关键字

请求示例：

{
  "customer_id": "CUST_001",
  "query": "1234 Warehouse"
}

响应数据

字段	类型	说明
data.candidates	Array<Object>	候选列表（字段同 §5.2 候选对象）

用户选定后，须把候选映射进 pickup_address / delivery_address（见下节必填确认字段）。

6.3 提交询价

接口地址

POST /api/quotes

请求参数（核心）

字段	类型	必填	约束	说明
request_id	String	是	非空；建议 UUID	幂等 / 追踪
customer_id	String	是	与鉴权一致	客户 ID
pickup_address	Object	是	见下表	提货地址（须已确认）
delivery_address	Object	是	见下表	派送地址（须已确认）
weight	Object	是	value 正数；unit lb/kg/t	单托重量（兼容字段）
dimensions	Object	是	unit in/cm/m	单托尺寸（兼容字段）
pallet_count	Number	是	1～25	托盘数；多行时建议为各行 quantity 合计
cargo_type	String	是	见 §12.1	货物类型
service_level	String	否	standard / guaranteed	服务等级
rate_option	String	否	lowest / fastest	价格偏好
ready_date	String	否	YYYY-MM-DD；周末会拨到下一工作日	可提货日
ready_time	String	否	≤32 字符	可提货时间
pickup_accessorials	Array<String>	否	每项 ≤64；最多 20	提货附加服务 id
delivery_accessorials	Array<String>	否	同上	派送附加服务 id
cargo_lines	Array<Object>	否	1～20 行	登录后多行货物（RPA 按行填）；字段已为英制，不做 kg/cm/m/t 换算
mothership_details	Object	否	见下	二级 Details（联系人/FBA 等）

地址对象必填确认字段（与免账号草稿不同）

字段	类型	必填	说明
street / city / state	String	是	结构化地址；state 2 位
zip	String	否	可空字符串
place_id	String	是	通常用候选 option_id
formatted_address	String	是	完整展示地址
selected_from_suggestions	Boolean	是	必须为 true
mothership_option_id	String	是	候选 option_id
mothership_display_label	String	是	候选 display_label
selected_from_mothership	Boolean	是	必须为 true

cargo_lines[]

字段	类型	必填	说明
cargo_type	String	是	行货物类型文案/枚举
quantity	Number	是	正数，≤999
weight_lb	Number	是	该行单件重量 lb（须已换算；不接受 kg/t）建议 ≤5000
length_in / width_in / height_in	Number	是	该行尺寸 英寸（须已换算；不接受 cm/m）

mothership_details（节选）

字段	类型	说明
pickup / delivery	Object	company_name、suite、联系人姓名邮箱电话、reference、notes、opens_at、closes_at
request_delivery_appointment	Boolean	是否预约送货
fba_number / fba_po_number	String	FBA 相关
cargo[]	Array	description、nmfc、hazmat、alcohol、tobacco、件数类型与数量等

请求示例（登录后最小可用）：

{
  "request_id": "2dd352e6-9a1d-4563-8f13-ebff18aabdb9",
  "customer_id": "CUST_001",
  "pickup_address": {
    "street": "1234 Warehouse Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "place_id": "Eisx...",
    "formatted_address": "1234 Warehouse Street, Los Angeles, CA, USA",
    "selected_from_suggestions": true,
    "mothership_option_id": "Eisx...",
    "mothership_display_label": "1234 Warehouse Street, Los Angeles, CA, USA",
    "selected_from_mothership": true
  },
  "delivery_address": {
    "street": "5678 Distribution Dr, Wilmer",
    "city": "Dallas",
    "state": "TX",
    "zip": "75201",
    "place_id": "EihE...",
    "formatted_address": "Distribution Dr, Wilmer, Dallas, TX, USA",
    "selected_from_suggestions": true,
    "mothership_option_id": "EihE...",
    "mothership_display_label": "Distribution Dr, Wilmer, Dallas, TX, USA",
    "selected_from_mothership": true
  },
  "weight": { "value": 1103, "unit": "lb" },
  "dimensions": { "length": 48, "width": 40, "height": 60, "unit": "in" },
  "pallet_count": 2,
  "cargo_type": "general_freight",
  "ready_date": "2026-07-22",
  "cargo_lines": [
    {
      "cargo_type": "general_freight",
      "quantity": 2,
      "weight_lb": 1103,
      "length_in": 48,
      "width_in": 40,
      "height_in": 60
    }
  ]
}

提交成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "quote_id": "QTE_20260721_0012",
    "status": "processing"
  }
}

随后进入 §9 轮询。

---

7. 路线 C：Flock 免账号（FLOCK_GUEST）

适用：客户未绑定 Flock 账密；参数符合 Flock 免账号硬限（托盘 4～20、总重 ≤45000 lb、线性英尺等）。

服务端优先走 Direct JSON；失败时按环境配置可回退 DOM 填表（可能弱注册）。

7.1 调用流程

1. 校验邮编、取货日、件数、总重、尺寸与线性英尺。
2. POST /api/flock/quotes → quote_id + processing。
3. 轮询 GET /api/quotes/{quote_id}（总窗口建议 ≥ 210 s）。
4. 成功时读 data.flock.lines[]（不是 MotherShip 的 quotes[] 形态）。

7.2 提交询价

接口地址

POST /api/flock/quotes

若服务端关闭 Flock 能力，可能返回业务不可用（如 QUOTE_UNAVAILABLE）。

请求参数

字段	类型	必填	约束	说明
request_id	String	是	非空	请求标识
customer_id	String	是	与鉴权一致	客户 ID
flock_input	Object	是	见下表	Flock 表单参数

flock_input（免账号）

字段	类型	必填	约束	说明
pickup_date	String	是	MM/DD/YYYY；不可早于今天；不可周末	提货日
pickup_zip	String	是	5 位邮编	提货邮编
delivery_zip	String	是	5 位；≠ pickup_zip	派送邮编
pallet_count	Number	是	整数 4～20	托盘件数
total_weight	Object	是*	value 正数；unit lb/kg/t	整票总重；也可用 total_weight_lb
dimensions	Object	否	缺省 48×40×48 in；unit in/cm/m	单托尺寸
form_mode	String	否	免账号不要传 logged_in_quick	省略即为匿名
registration	Object	否	见附录	DOM 回退时可选自填弱注册信息

* total_weight 与 total_weight_lb 二选一即可。

硬限（换算后）

项	限制
总重	≤ 45000 lb
尺寸	L≤636，W≤102，H≤108（in）
线性英尺	整票占用 ≤ 约 53'（否则校验失败）

请求示例：

{
  "request_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
  "customer_id": "CUST_001",
  "flock_input": {
    "pickup_date": "07/22/2026",
    "pickup_zip": "90001",
    "delivery_zip": "75201",
    "pallet_count": 6,
    "total_weight": { "value": 12000, "unit": "lb" },
    "dimensions": { "length": 48, "width": 40, "height": 48, "unit": "in" }
  }
}

提交成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "quote_id": "QTE_20260721_0201",
    "status": "processing"
  }
}

7.3 结果字段（轮询成功后）

字段	类型	说明
data.flock.reference	String	Flock 参考号（可能为空）
data.flock.lines[]	Array	报价行
data.flock.lines[].tier	String	flock_direct / standard
data.flock.lines[].label	String	展示名
data.flock.lines[].transit_days / transitDays	String	时效
data.flock.lines[].final_total_usd	Number	对客户展示价（USD，已含加价）
data.flock.shipment_meta	Object	提货日、邮编、重量等摘要

一档即可能成功；勿假设固定两档。展示价优先 final_total_usd。

---

8. 路线 D：Flock 登录后（FLOCK_LOGGED_IN）

适用：客户已绑定 Flock 账密；参数按登录后 Quick 表单填写。

服务端强制官网登录 DOM，禁止匿名 Direct。宿主须传 form_mode: "logged_in_quick"，并尽量补齐登录后字段，否则 RPA 可能填表失败。

8.1 调用流程

与 §7.1 相同（同一对接口），差异仅在请求体与服务端执行路径。

8.2 提交询价

接口地址

POST /api/flock/quotes（同路线 C）

flock_input 相对免账号的差异

字段	类型	必填	约束	说明
form_mode	String	是（本路线）	固定 logged_in_quick	切换登录后校验与 RPA 表单
pallet_count	Number	是	1～999	登录后件数上限放宽
pickup_location_type	String	建议	官网地点类型	如商业/住宅等 id/文案
delivery_location_type	String	建议	同上	派送地点类型
packaging_type	String	建议	包装类型	登录后 Quick 字段
freight_class	String	建议	货运等级	登录后 Quick 字段
description	String	建议	货物描述	登录后 Quick 字段
stackable / turnable	Boolean	否		可堆叠 / 可翻转
additional_services	Array<String>	否		附加服务 id
vehicle_types	Array<String>	否		允许车型 id
pickup_liftgate / pickup_inside / pickup_pallet_jack	Boolean	否		提货附属
delivery_liftgate / delivery_inside / delivery_pallet_jack	Boolean	否		派送附属
call_before_pickup / call_before_delivery	Boolean	否		提货/派送前电话
pickup_service / delivery_service 及窗口时间字段	String	否	总重 >5000 lb 时官网才开放高级调度	见实现字段名

登录后不再强制免账号的 4～20 托盘与线性英尺校验；尺寸/总重上限仍适用 Flock 官网硬限。

请求示例：

{
  "request_id": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
  "customer_id": "CUST_001",
  "flock_input": {
    "form_mode": "logged_in_quick",
    "pickup_date": "07/22/2026",
    "pickup_zip": "90001",
    "delivery_zip": "75201",
    "pallet_count": 2,
    "total_weight": { "value": 2200, "unit": "lb" },
    "dimensions": { "length": 48, "width": 40, "height": 48, "unit": "in" },
    "packaging_type": "Pallets",
    "freight_class": "70",
    "description": "General freight",
    "pickup_location_type": "Business with a dock or forklift",
    "delivery_location_type": "Business with a dock or forklift"
  }
}

结果字段同 §7.3。

---

9. 通用：异步轮询

适用于 MS_LOGGED_IN、FLOCK_GUEST、FLOCK_LOGGED_IN（以及非推荐的 MotherShip 异步三步）。

9.1 接口地址

GET /api/quotes/{quote_id}

9.2 请求

• 方法：GET
• 路径参数：quote_id（提交接口返回）
• 鉴权头：同 §2.3（须为报价所属客户）

9.3 响应数据

字段	类型	说明
data.quote_id	String	报价单号
data.request_id	String	请求标识
data.status	String	processing / done / failed / expired
data.currency	String	USD
data.quotes	Array	MotherShip 档位（MS_* 成功时）
data.flock	Object	Flock 结果（FLOCK_* 成功时）
data.error_code / error_message	String	失败时
data.rpa_stage / rpa_stage_label	String	processing 时可能出现的进度
data.valid_until	String	成功时有效期

9.4 轮询建议

项	建议
间隔	2 s；10 s 后可加密至约 0.8 s
MotherShip 总窗口	≥ 420000 ms
Flock 总窗口	≥ 210000 ms（以联调环境配置为准）
终止条件	done / failed / expired / 超时
并发	同一用户操作防重复提交

---

10. 错误码

10.1 接口层错误（code !== 0）

code	HTTP	说明	处理建议
UNAUTHORIZED	401	缺少或无效 API Key	检查 Bearer / 轮换
FORBIDDEN	403	客户与 Key 不匹配，或无权访问报价	核对 X-Customer-Id / quote_id
VALIDATION_FAILED	400	字段不合法	按当前路线硬限与必填项检查
SESSION_EXPIRED	404	host_session_id 过期	仅 MS_GUEST：重走候选
ADDRESS_SESSION_MISMATCH	400	候选不属于本次会话	使用返回的完整对象
ADDRESS_NOT_SELECTABLE	400	提交了不可选候选	改选 selectable: true
QUOTE_NOT_FOUND	404	报价不存在	检查 quote_id
QUOTE_TIMEOUT	504	同步等待超时	稍后重试
RATE_LIMITED	429	限流	降频
QUOTE_UNAVAILABLE	503	渠道不可用（如 Flock 关闭/占用）	稍后重试或换路线
INTERNAL_ERROR	5xx	系统异常	稍后重试

10.2 询价业务失败（code = 0 且 data.status = failed）

error_code	说明
QUOTE_UNAVAILABLE	暂时无法获取报价
QUOTE_TIMEOUT	询价超时
QUOTE_ENTRY_UNAVAILABLE	报价入口暂时无法打开
ADDRESS_SUGGESTION_NOT_FOUND	地址无法匹配
CARRIER_NO_CAPACITY	该线路暂无可用运力
ADDRESS_NOT_SUPPORTED	地址不在服务范围
RPA_CAPTCHA	触发验证码
SESSION_EXPIRED	承运商登录会话过期
PROVIDER_LOGIN_FAILED	承运商账密不正确或未即时更新
RPA_DATA_INVALID	未能解析完整报价
PAGE_LOAD_TIMEOUT	承运商页面加载超时

对外展示优先使用中文 error_message。

---

11. 对接建议

11.1 第三方需要做

1. 服务端保存 API Key 与 Customer ID，后端代理调用。
2. 实现路线判定（§3），一票一路。
3. 账密由管理端绑定；有账密则按登录后字段规范传参。
4. MS_GUEST：地址选择 UI + submit Loading（≥420 s）。
5. 异步路线：实现轮询与超时；Flock 读 flock.lines，MotherShip 读 quotes。
6. 成功后注意 valid_until。

11.2 第三方不需要做

1. 不需要在请求体传官网密码。
2. 不需要自行做单位换算（支持 lb/kg/t、in/cm/m，服务端统一进一取整为 lb/in）。
3. 不需要调用管理端客户 CRUD / embed-demo 登录作为正式对接。
4. 不需要把 Priority1 实验接口当作本期正式四路线之一。

11.3 cURL 示例

MS_GUEST 第一步：

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 @ms-guest-candidates.json

FLOCK_GUEST 提交：

curl -X POST "https://if.dev.51track.vip/api/flock/quotes" \
  -H "Authorization: Bearer <API Key>" \
  -H "X-Customer-Id: CUST_001" \
  -H "Content-Type: application/json" \
  --data-binary @flock-guest.json

轮询：

curl -X GET "https://if.dev.51track.vip/api/quotes/QTE_20260721_0201" \
  -H "Authorization: Bearer <API Key>" \
  -H "X-Customer-Id: CUST_001"

11.4 Apifox 环境变量建议

变量	示例值
baseUrl	https://if.dev.51track.vip
token	chj_...
customerId	与 Token 绑定的客户 ID

Headers：Authorization: Bearer {{token}}，X-Customer-Id: {{customerId}}，Content-Type: application/json。

---

12. 附录

12.1 货物类型枚举（cargo_type，MotherShip）

值	说明
general_freight	普通货物（默认）
machinery	机械设备
furniture	家具
electronics	电子产品
building_materials	建材
auto_parts	汽车配件
food_nonperishable	非生鲜食品
apparel	服装
other	其他

12.2 报价状态（status）

值	说明
processing	询价进行中（须继续轮询）
done	成功
failed	失败，看 error_message
expired	报价已过期

12.3 Flock registration（可选，免账号 DOM 回退）

字段	类型	说明
first_name / last_name	String	姓名
company	String	公司
email	String	工作邮箱
phone	String	10 位美国电话
shipments_per_month	String	1-25 / 26-50 / 51-100 / 101+

12.4 非推荐 / 不在本期四路线

说明	接口
MotherShip 免账号异步三步（可用，非默认同步方案）	POST /api/quotes + 轮询
Priority1（实验）	POST /api/priority1/quotes
/embed-demo 演示门户	Cookie 登录，非正式 OpenAPI
管理端客户 / 预警等	仅运维

---

13. 联系与支持

事项	说明
开通客户 / API Key / 绑定官网账密	联系我方运维或管理端操作
Key 失效	轮换后立即通知宿主更换
故障排查	提供时间、路线 ID、quote_id 或 host_session_id、请求摘要（勿传完整 Key/密码）
文档版本	1.1（2026-07-21）