快速入门
了解开放平台的基础环境、接入步骤，并用第一个请求验证 ApiKey 与提交预报单流程。
本页帮助您在最短时间内完成第一次接口调用。正式接入前，请先阅读鉴权说明了解 ApiKey 鉴权方式。
1. 接入前置条件
- 已完成商务对接，获得专属 ApiKey。
- 已开通沙箱环境用于联调。
2. 环境地址
| 环境 | 契约前缀 | 用途 |
|---|---|---|
| 沙箱（Sandbox） | https://open.test.huixingguoji.com | 联调测试，数据隔离 |
| 生产（Production） | https://open.huixingguoji.com | 正式提交真实数据 |
沙箱与生产接口行为完全一致，仅数据隔离。上线前务必在沙箱完成全流程联调。
3. 通用请求约定
- 协议：HTTPS（不支持 HTTP）。
- 数据格式：
application/json; charset=utf-8。 - 字符编码：UTF-8。
- 时间格式：ISO 8601（如
2026-08-11T20:00:00+08:00）或日期YYYY-MM-DD。
4. 第一个请求：提交一个测试预报单
以提交预报单接口 POST /open/v1/forecasts 为例，构造一个最小可用请求。
4.1 请求头
| 请求头 | 说明 |
|---|---|
Content-Type | application/json; charset=utf-8 |
X-Api-Key | 您的 ApiKey，详见鉴权说明 |
4.2 请求体
{
"po_number": "180401699",
"forecast_type": 1,
"warehouse_code": "JNB-1",
"due_date": "2026-05-29",
"shipping_label": "https://open.huixingguoji.com/storage/20260815/pdf_11_1786626240487_1234.pdf",
"shipping_note": "https://open.huixingguoji.com/storage/20260815/pdf_11_1786626240488_5678.pdf",
"items": [
{
"sku_code": "TFL-A001",
"barcode": "6001234567890",
"product_name_en": "Ceramic Mug",
"product_name_cn": "陶瓷马克杯",
"product_image": "https://cdn.example.com/img/a001.jpg",
"forecast_quantity": 60,
"forecast_price": 2.5,
"hs_code": "6912000000",
"tracking_number": "TFL20260529000001ZA"
}
]
}字段含义与取值见提交预报单接口：
forecast_type为整数（1=备货三全 /2=直邮贴标），非必填，默认2。两种类型的明细必填字段一致，直邮贴标(2)对物流单号额外做唯一性校验。
4.3 成功响应
{
"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"
}
}4.4 使用 curl 验证
curl -X POST 'https://open.test.huixingguoji.com/open/v1/forecasts' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'X-Api-Key: YOUR_API_KEY' \
-d @forecast.json