鉴权说明

通过 ApiKey 请求头对开放平台接口进行鉴权，单一凭证、接入简单。

开放平台所有接口均通过 ApiKey 鉴权。您只需在请求头中携带平台分配的 ApiKey 即可调用，无需计算签名。本文说明凭证获取与使用方式。

1. 凭证

接入后，平台为您分配一个 ApiKey：

ApiKey：接入身份凭证，会出现在请求头中，用于标识调用方身份与权限。
请妥善保管 ApiKey，不要提交到代码仓库、不要暴露在客户端（浏览器 / App）。一旦泄露请立即联系商务团队重置。
一个商户可拥有一个或多个 ApiKey，可按环境（沙箱 / 生产）或业务线分别分配。

ApiKey 同时具备身份标识与访问凭据作用，等同于账号密码，务必按密钥标准管理。

2. 请求头

每个请求需携带以下头：

请求头	说明
`X-Api-Key`	您的 ApiKey
`Content-Type`	`application/json; charset=utf-8`（写接口）

仅需 X-Api-Key 一个鉴权头，无需时间戳、nonce 或签名字段。

3. 调用示例

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 @parcel.json

PHP

$ch = curl_init('https://open.test.huixingguoji.com/open/v1/forecasts');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json; charset=utf-8',
        'X-Api-Key: YOUR_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $bodyJson,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://open.test.huixingguoji.com/open/v1/forecasts"))
    .header("Content-Type", "application/json; charset=utf-8")
    .header("X-Api-Key", apiKey)
    .POST(HttpRequest.BodyPublishers.ofString(bodyJson))
    .build();
HttpResponse<String> resp = httpClient.send(req, HttpResponse.BodyHandlers.ofString());

Python

import requests

resp = requests.post(
    "https://open.test.huixingguoji.com/open/v1/forecasts",
    json=body,
    headers={"X-Api-Key": api_key},
)

提交预报单的完整字段见提交预报单接口。

4. 安全建议

传输加密：所有请求必须走 HTTPS，HTTP 将被拒绝。
服务端使用：ApiKey 仅在您的服务端使用，不要下发到前端。
定期轮换：建议定期通过商务/控制台重置 ApiKey。
最小权限：按业务线/环境分配独立 ApiKey，避免一把钥匙开所有门。

5. 常见错误

错误码	含义	排查
`40101`	缺少 ApiKey	检查是否携带 `X-Api-Key` 请求头
`40003`	ApiKey 无效/失效	确认 ApiKey 正确、未过期/撤销，且与所用环境（沙箱/生产）匹配
`40301`	权限不足	确认该 ApiKey 已开通对应接口权限

详见错误码。

鉴权说明

On this page