提交预报单接口

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

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

预报单以 PO Number（Takealot 采购单号，9 位纯数字） 为业务主键，同一 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（直邮贴标，默认）：直邮代贴标场景。
- 两种类型的明细必填字段一致；区别仅在直邮贴标对物流单号做预报单内/全局唯一性校验。
PO Number：Takealot 采购单号，9 位纯数字（如 180401699），全局唯一，重复返回 40901。
仓库 warehouse_code：目标入库仓，如 JNB-1（约翰内斯堡）、CPT-1（开普敦）、DBN-1（德班）。
二标文件：shipping_label（物流面单/箱唛）、shipping_note（装箱清单/箱单），均必填。二者通过商品条码（barcode）做一致性校验，不一致返回告警。文件地址需先通过上传 PDF 接口获取。产品标签（marketplace_label）由平台侧生成维护，无需推送。

请求体字段

字段	类型	必填	说明
`po_number`	string(40)	是	Takealot 采购单号，9 位纯数字，唯一，重复返回 `40901`
`forecast_type`	integer	否	预报类型：`1`(备货三全) / `2`(直邮贴标)，默认 `2`(直邮贴标)
`warehouse_code`	string(40)	是	入库仓库代码：`JNB-1` / `CPT-1` / `DBN-1` 等
`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-1`
`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)	是	全部	产品英文名称
`product_name_cn`	string(100)	是	全部	产品中文名称
`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,
  "warehouse_code": "JNB-1",
  "due_date": "2026-05-29",
  "shipping_name": "PO-180401699-29/05/2026-JHB-1",
  "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",
      "product_name_cn": "陶瓷马克杯",
      "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。

响应

成功（HTTP 200）

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

字段	说明
`forecast_no`	平台生成的预报单号（`FC` + 日期 + 序号）
`po_number`	采购单号（业务键，回传你提交的值）
`item_count`	成功落库的明细行数
`status`	接收状态，提交成功为 `ACCEPTED`
`create_time`	接收时间，ISO 8601

本接口仅完成预报单的接收登记。预报单在仓储系统后续的履约流转（已收货 → 已打单 → 已质检 → 已发货等）不在本接口返回范围内，如需查询可联系平台。

失败

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

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

错误码	含义
`40003`	ApiKey 无效
`40901`	PO Number 重复
`42201`	字段校验失败（必填缺失、数量/金额非法、PO 号非 9 位）
`42901`	触发限流
`50001`	系统异常

提交预报单接口

On this page