5.7 KiB

Raw Blame History Unescape Escape

外部系统 API 对接说明

完整对接指南（含美美与共示例、前端职责、自测方法）见 第三方对接指南。

Base URL：https://<你的域名>（示例：https://if.dev.51track.vip）

响应格式

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

code !== 0 时为业务错误；询价业务失败时 HTTP 可能仍为 200，data.status === "failed"。

方式 A：宿主两步接口（推荐）

接口路径不变，鉴权由服务器 .env 控制：

模式	`HOST_PUBLIC_API_ENABLED`	请求头
公开（联调/内网）	`true`	只需 `Content-Type: application/json`
鉴权（对接第三方）	`false`	见下方 Token 头

步骤	方法	路径	说明
1	POST	`/api/host/quote/candidates`	地址 + 货物 → 联想候选 + `host_session_id`
2	POST	`/api/host/quote/submit`	确认候选 → 同步返回最终报价（服务端内部轮询）

公开模式 无需 Authorization / X-Customer-Id。只需：

Content-Type: application/json

鉴权模式 须携带（Token 由我方在 HOST_SERVICE_TOKENS 中配置后发放）：

Authorization: Bearer <Service Token>
X-Customer-Id: <Customer ID>
Content-Type: application/json

服务端 .env 示例（为美美与共单独发 Token）：

HOST_PUBLIC_API_ENABLED=false
HOST_SERVICE_TOKENS={"meimei-2026":{"customerId":"CUST_001","permissions":["pricing:markup:write"]}}
CUSTOMER_REGISTRY=CUST_001

1. 联想地址

请求体： 见 host-candidates-req.example.json

成功响应 data 字段：

字段	说明
`host_session_id`	UUID，第二步必传；30 分钟有效
`pickup_candidates`	提货候选列表
`delivery_candidates`	派送候选列表
`requires_selection`	是否需用户从多条候选中选择

候选对象字段：option_id、display_label、formatted_address、street、city、state、zip、selectable、unavailable_reason

2. 确认并取报价

{
  "host_session_id": "第一步返回的 UUID",
  "pickup_candidate": { "option_id": "...", "display_label": "...", "formatted_address": "...", "street": "...", "city": "...", "state": "CA", "zip": "90001" },
  "delivery_candidate": { "option_id": "...", "display_label": "...", "formatted_address": "...", "street": "...", "city": "...", "state": "TX", "zip": "75201" }
}

pickup_candidate / delivery_candidate 须为第一步返回列表中的完整对象（option_id 须匹配）。

成功响应 data： 与 GET /api/quotes/{id} 相同，主要字段：

字段	说明
`status`	`done` 成功；`failed` 失败
`quotes[]`	多档报价
`quotes[].final_total`	对客户展示价（USD，含加价）
`quotes[].carrier`	承运商
`quotes[].transit_days`	时效
`error_message`	`status=failed` 时的原因

注意：

第二步 HTTP 连接可能保持 10–420 秒，Nginx 须设 proxy_read_timeout 420s;
宿主无需再调 GET /api/quotes/{id} 轮询

货物字段（第一步 `cargo`）

字段	类型	说明
`weight.value`	number	单托重量
`weight.unit`	`lb` \| `kg`	重量单位
`dimensions.length/width/height`	number	单托尺寸
`dimensions.unit`	`in` \| `cm`	尺寸单位
`pallet_count`	number	托盘数 1–25
`cargo_type`	string	见下方枚举

货物类型： general_freight · machinery · furniture · electronics · building_materials · auto_parts · food_nonperishable · apparel · other

方式 A 错误码

code	HTTP	说明
`VALIDATION_FAILED`	400	参数无效；若 message 为「请求体格式无效」多为 JSON 格式错误
`UNAUTHORIZED`	401	鉴权模式下缺少或无效的 `Authorization`
`SESSION_EXPIRED`	404	`host_session_id` 过期或无效
`ADDRESS_SESSION_MISMATCH`	400	候选不在本次联想结果中
`ADDRESS_NOT_SELECTABLE`	400	选了不可用的候选
`QUOTE_TIMEOUT`	504	服务端轮询超时
`RATE_LIMITED`	429	限流

方式 B：Token 三步接口（旧流程，需客户端轮询）

前置条件： 在请求头携带 Token（与方式 A 鉴权模式相同）。

Authorization: Bearer <Service Token>
X-Customer-Id: <Customer ID>
Content-Type: application/json

Token 在 .env 的 HOST_SERVICE_TOKENS 中配置。

步骤	方法	路径
1	POST	`/api/addresses/mothership-candidates`
2	POST	`/api/quotes`
3	GET	`/api/quotes/{quote_id}`（每 2 秒轮询，最长约 7 分钟）

第二步 body 须含 customer_id、request_id（UUID v4）、经 MotherShip 确认的 pickup_address / delivery_address 及货物字段。详情见第三方对接指南 §6。

快速自测（方式 A）

Windows PowerShell（推荐用 JSON 文件，避免引号转义问题）：

curl.exe -s -X POST "https://if.dev.51track.vip/api/host/quote/candidates" `
  -H "Content-Type: application/json" `
  --data-binary "@deploy/host-candidates-req.example.json"

返回 "code":0 且含 host_session_id 即成功。

Linux / macOS：

curl -s -X POST "https://if.dev.51track.vip/api/host/quote/candidates" \
  -H "Content-Type: application/json" \
  --data-binary "@deploy/host-candidates-req.example.json"

文档版本：2026-06-30

5.7 KiB Raw Blame History Unescape Escape