API 修改记录

开放平台 API 变更日志 —— 每次接口/字段/行为变更的影响范围与客户端适配指引。

本页记录开放平台 API 的所有变更（新增接口、字段变更、行为变更、参数限制调整等），并标注客户端是否需要修改代码，方便开发人员快速评估影响。

订阅方式：关注本页更新，或联系平台技术支持加入变更通知邮件列表。

日期	接口	变更	需要客户端修改吗
2026-10-17	`POST /open/v1/forecasts`	明细新增申报品名字段 `cn_name` / `en_name`；废弃 `product_name_cn`（不再入库）	🔴 必须修改（见详情）
2026-10-17	`POST /open/v1/forecasts`	新增可选字段 `draft_status`（草稿状态），默认值 `1` 草稿	⚠️ 需要按需修改（见详情）
2026-10-01	`POST /open/v1/forecasts`	`marketplace_label` 字段下线，传入将被静默忽略	🟢 无需修改（建议清理）
2026-09-05	`GET /open/v1/forecasts/tracking`	新增限流：1 次 / 3 秒 / ApiKey，超限返回 `42901`	⚠️ 建议实现退避重试
2026-09-05	`POST /open/v1/files/pdf`	单文件大小上限 10MB 收紧至 300KB（`42206`）	⚠️ 需检查文件大小
2026-08-26	`POST /open/v1/forecasts`	移除废弃字段 `forecast_no`；补充状态枚举说明	🟢 无需修改

2026-10-17 明细申报品名字段调整：新增 `cn_name` / `en_name`，废弃 `product_name_cn`

影响接口：POST /open/v1/forecasts（提交预报单）

兼容性：⚠️ 部分兼容 —— 请求不会报错，但 product_name_cn 传入后不再入库（静默忽略），不迁移会导致中文名丢失。

你需要做什么

你的场景	是否修改	做法
请求体里传了 `product_name_cn`	🔴 必须修改	字段名改为 `cn_name`（申报品名，中文，≤64 字），否则中文名将不再保存
需要提供英文申报品名	⚠️ 建议修改	新增 `en_name`（申报品名，英文，≤128 字）；不传可由平台申报品名匹配服务自动回填
从未传过 `product_name_cn`，也不需要中文名	🟢 无需修改	`cn_name` / `en_name` 均为可选字段

变更详情（对齐 ERP 租户端 2026-10-16 「预报单明细增加申报品名字段 cn_name/en_name」调整）

新增明细可选字段 cn_name（string，≤64 字）：申报品名（中文，来自申报品名匹配服务）；
新增明细可选字段 en_name（string，≤128 字）：申报品名（英文，来自申报品名匹配服务）；
废弃 product_name_cn：传入被静默忽略、不报错、不入库；product_name_en（产品英文名）不受影响，仍必填；
超长校验：cn_name >64 字、en_name >128 字返回 42201（字段校验失败）。

迁移示例

 "items": [
   {
     "sku_code": "TFL-A001",
     "product_name_en": "Ceramic Mug",
-    "product_name_cn": "陶瓷马克杯",
+    "cn_name": "陶瓷马克杯",
+    "en_name": "Ceramic Coffee Mug",
     ...
   }
 ]

2026-10-17 提交预报单新增 `draft_status` 字段（草稿状态可由客户端指定）

影响接口：POST /open/v1/forecasts（提交预报单）

兼容性：向后兼容 —— 新字段为可选，旧请求体不传也能正常调用，不会报错。

你需要做什么

你的场景	是否修改	做法
接受「提交后先落草稿」，在租户端确认后推送	🟢 无需修改	不传 `draft_status`，默认即为草稿
希望保持「提交即推送」直达履约流程	🔴 必须修改	请求体显式传 `"draft_status": 2`，否则将落草稿
需要两段式流程（先草稿、后推送）	🟢 无需修改	不传或传 `"draft_status": 1`，推送动作在租户端完成

变更详情

新增可选请求字段 draft_status（integer）：
- 1 = 草稿（默认）：提交后不进入履约流程，可在租户端确认后推送；
- 2 = 已推送：提交即推送，直接进入履约流程。
未传 draft_status 时，一律按 1（草稿）处理；传入 1 / 2 之外的值返回 42201（字段校验失败）。
push_time（推送时间）行为调整：仅已推送（2）才写入；草稿为空，待推送后由系统回填。
服务端原调试配置 forecast.draft_status 已移除，草稿状态统一由客户端请求控制。

请求示例

{
  "po_number": "180401699",
  "forecast_type": 2,
  "draft_status": 1,
  "warehouse_code": "JHB",
  "due_date": "2026-05-29",
  "shipping_label": "https://open.huixingguoji.com/storage/xxx/label.pdf",
  "shipping_note": "https://open.huixingguoji.com/storage/xxx/note.pdf",
  "items": [ /* ... */ ]
}

2026-10-01 `marketplace_label` 字段下线

影响接口：POST /open/v1/forecasts

兼容性：向后兼容 —— 传入该字段会被静默忽略，不报错、不生效。

你需要做什么：🟢 无需修改；建议从请求体中移除 marketplace_label，避免误导后续维护。产品标签图片现由平台侧维护，不再经预报单提交。

2026-09-05 轨迹查询接口新增限流

影响接口：GET /open/v1/forecasts/tracking

变更详情：按 ApiKey 固定窗口限流 —— 每 3 秒最多 1 次请求；超限返回 HTTP 429 + 42901，请按 Retry-After 响应头做指数退避重试（轨迹为实时查询第三方数据，限流旨在保护上游）。

你需要做什么：⚠️ 高频轮询的客户端需要实现退避重试；低频（如用户触发式）查询一般无感。

2026-09-05 PDF 上传大小上限收紧（10MB → 300KB）

影响接口：POST /open/v1/files/pdf

变更详情：单文件上限由 10MB 收紧至 300KB；超限返回 42206（文件超出大小限制）。

你需要做什么：⚠️ 生成面单/装箱清单 PDF 时需控制体积（压缩图片、精简页数），超过 300KB 的文件会被拒绝。

2026-08-26 移除废弃字段 `forecast_no`、补充状态枚举

影响接口：POST /open/v1/forecasts

变更详情：文档移除废弃字段 forecast_no（预报单号由系统生成，业务键统一为 po_number）；补充 status / draft_status 状态枚举说明与错误码 HTTP 状态映射。

你需要做什么：🟢 无需修改；如仍使用 forecast_no 请改为 po_number。

历史低影响变更

日期	说明
2026-09-07	文档修正：仓库代码示例更正为 `CPT` / `JHB` / `DBN` / `CPT2` / `JHB3`（无 API 行为变更）
2026-08-21	承运商品牌名称由 CN Express 更名为 Huixing Express（文案性变更，接口无影响）
2026-08-18	开放平台文档站上线，接口文档迁移至 `/docs` 路径