提交预报单接口

大客户通过本接口向 Takealot 仓储系统提交送仓预报单，登记 PO 单号、仓库、商品明细与申报信息，完成待收货登记。

提交预报单是开放平台的核心接口。客户将 Takealot 采购单（PO）对应的备货/直邮商品打包成预报单提交到仓储系统，登记仓库、商品明细与申报信息，后续由仓库完成收货、打单、质检、生成收费单、发货等履约环节。

预报单以 PO Number（Takealot 采购单号，24 位以内） 为业务主键，同一 PO Number 不可重复提交。

接口说明

项	值
方法	`POST`
路径	`/open/v1/forecasts`
Content-Type	`application/json; charset=utf-8`
鉴权	ApiKey 鉴权

公共请求头

请求头	必填	说明
`X-Api-Key`	是	ApiKey，详见鉴权说明
`Content-Type`	是	`application/json; charset=utf-8`

业务概念

提交前请理解以下概念，字段含义均围绕它们展开：

预报类型 forecast_type（非必填，默认 2）：
- 1（备货三全）：备货送仓。
- 2（直邮贴标，默认）：直邮代贴标场景。
- 两种类型的明细必填字段一致；区别仅在直邮贴标对物流单号做预报单内/全局唯一性校验。
草稿状态 draft_status（非必填，默认 1，可由客户端传入）：
- 1（草稿，默认）：提交后先落草稿，不进入履约流程，可在租户端确认后推送；
- 2（已推送）：提交即推送，直接进入履约流程；
- 草稿的 push_time 为空，推送后由系统回填。
PO Number：Takealot 采购单号，24 位以内（如 180401699），全局唯一，重复返回 HTTP 409 + 40901。自提订单（明细含物流单号 自提）的 PO 号仅允许大写字母、数字和连字符。
仓库 warehouse_code：目标入库仓，如 CPT（开普敦）、JHB（约翰内斯堡）、DBN（德班）、CPT2、JHB3。
二标文件：shipping_label（物流面单/箱唛）、shipping_note（装箱清单/箱单），均必填。二者通过商品条码（barcode）做一致性校验，不一致返回告警。文件地址需先通过上传 PDF 接口获取。

请求体字段

字段	类型	必填	说明
`po_number`	string(24)	是	Takealot 采购单号，24 位以内，唯一，重复返回 HTTP 409 + `40901`
`forecast_type`	integer	否	预报类型：`1`(备货三全) / `2`(直邮贴标)，默认 `2`(直邮贴标)
`draft_status`	integer	否	草稿状态：`1`(草稿) / `2`(已推送)，默认 `1`(草稿)；传非法值返回 `42201`
`warehouse_code`	string(40)	是	入库仓库代码：`CPT` / `JHB` / `DBN` / `CPT2` / `JHB3`
`forecast_date`	string	否	预报日期 `YYYY-MM-DD`，不传则取当天
`due_date`	string	是	截止入库日期 `YYYY-MM-DD`（Takealot Due Date）
`goods_type`	integer	否	货物类型：`1`(普货) / `2`(特货) / `3`(高货值)，默认 `1`
`shipping_label`	string	是	物流面单 PDF 访问地址，通过上传 PDF获取
`shipping_note`	string	是	装箱清单 PDF 访问地址，通过上传 PDF获取
`shipping_name`	string(200)	否	发货单名称，格式如 `PO-180401699-29/05/2026-JHB`
`length_cm`	number(cm)	否	长，用于计费
`width_cm`	number(cm)	否	宽，用于计费
`height_cm`	number(cm)	否	高，用于计费
`weight_kg`	number(kg)	否	重量，3 位小数
`box_count`	integer	否	箱子个数
`bag_count`	integer	否	袋子个数
`is_battery`	integer	否	是否带电，`0`/`1`，默认 `0`
`airway_bill_no`	string	否	头程空运单号
`batch_no`	string	否	批次号
`remark`	string(500)	否	备注
`items`	array	是	商品明细，见下表

items[] 字段

字段	类型	必填	适用类型	说明
`sku_code`	string(40)	是	全部	商品 SKU 编码（99 码）
`barcode`	string(13)	是	全部	商品条码（13 位）
`product_name_en`	string(100)	是	全部	产品英文名称
`cn_name`	string(64)	否	全部	申报品名（中文），≤64 字；替代已废弃的 `product_name_cn`，不传可由平台申报品名匹配服务自动回填
`en_name`	string(128)	否	全部	申报品名（英文），≤128 字；不传可由平台申报品名匹配服务自动回填
~~`product_name_cn`~~	string(100)	否	全部	已废弃（2026-10-17）：传入将被静默忽略、不入库，请改用 `cn_name`，详见修改记录
`forecast_quantity`	integer	是	全部	预报数量，> 0
`forecast_price`	number	是	全部	申报单价（USD，美元），> 0
`hs_code`	string(12)	是	全部	海关 HS Code（跨境清关用）
`tracking_number`	string	是	全部	物流单号，支持多个，多个用英文逗号分隔。特殊值 `库存` / `取消发货` / `自提` 不参与查重
`third_party_order_no`	string	否	全部	第三方订单号 (采购平台订单号)
`product_image`	string	是	全部	商品图片地址
`remark`	string(500)	否	全部	明细备注

请求示例（直邮贴标）

{
  "po_number": "180401699",
  "forecast_type": 2,
  "draft_status": 2,
  "warehouse_code": "JHB",
  "due_date": "2026-05-29",
  "shipping_name": "PO-180401699-29/05/2026-JHB",
  "shipping_label": "https://open.huixingguoji.com/storage/20260813/pdf_11_1786626240487_1234.pdf",
  "shipping_note": "https://open.huixingguoji.com/storage/20260813/pdf_11_1786626240488_5678.pdf",
  "length_cm": 40,
  "width_cm": 30,
  "height_cm": 25,
  "weight_kg": 8.5,
  "is_battery": 0,
  "remark": "易碎品，请轻放",
  "items": [
    {
      "sku_code": "TFL-A001",
      "barcode": "6001234567890",
      "product_name_en": "Ceramic Mug",
      "cn_name": "陶瓷马克杯",
      "en_name": "Ceramic Coffee Mug",
      "forecast_quantity": 60,
      "forecast_price": 2.5,
      "hs_code": "6912000000",
      "tracking_number": "TFL20260529000001ZA",
      "product_image": "https://cdn.example.com/img/a001.jpg"
    }
  ]
}

示例中的 PDF 地址需先调用上传 PDF 接口获取真实 URL，再回填到 shipping_label / shipping_note。

示例传 "draft_status": 2 表示提交即推送；若不传或传 1，则先落草稿（默认行为），可在租户端确认后推送。草稿不写入推送时间（push_time）。

响应

成功（HTTP 200）

{
  "code": "0",
  "message": "success",
  "data": {
    "po_number": "180401699",
    "item_count": 1,
    "status": "ACCEPTED",
    "create_time": "2026-08-13T20:00:00+08:00"
  }
}

字段	说明
`po_number`	采购单号（业务键，回传你提交的值）
`item_count`	成功落库的明细行数
`status`	接收状态，提交成功为 `ACCEPTED`
`create_time`	接收时间，ISO 8601

本接口仅完成预报单的接收登记。预报单在仓储系统后续的履约流转（状态枚举见下文）不在本接口返回范围内，如需查询可联系平台。

预报单状态枚举

status（履约状态）

值	状态	说明
`1`	已下单待收货	创建预报单后的默认状态
`2`	已收货待打包	仓库已收货
`3`	已打单待质检	已打印面单/箱单
`4`	已质检待生成收费单	质检合格
`5`	已生成收费单待发货	收费单已生成
`6`	已发货	履约完成
`7`	已取消	预报单已取消

draft_status（草稿/推送状态）

提交预报单时可通过请求字段 draft_status 指定（不传默认 1 草稿），详见字段说明与修改记录。

值	状态	说明
`1`	草稿	提交接口默认状态（`draft_status` 不传或传 `1`），尚未正式推送，`push_time` 为空
`2`	已推送	请求传 `"draft_status": 2`，提交即推送，进入履约流程并落 `push_time`

失败

{ "code": "42201", "message": "字段校验失败：forecast_price 必须大于 0", "data": null }

PO Number 重复时返回 HTTP 409：

{ "code": "40901", "message": "po_number 已存在：180401699" }

常见错误码（完整列表见错误码）：

错误码	含义
`40003`	ApiKey 无效
`40901`	PO Number 重复（HTTP 409）
`42201`	字段校验失败（必填缺失、数量/金额非法、PO 号超 24 位）
`42202`	字段格式错误（如自提订单 PO 号含非法字符）
`42901`	触发限流
`50001`	系统异常

提交预报单接口

On this page