ChinaLogisticHub
开始使用

API · v1

开发者

通过签名 REST API 和 HMAC 校验的 Webhook,将 ChinaLogisticHub 集成到您的 ERP、TMS 或 BI 工具。

Swagger UI(非生产环境)OpenAPI JSON
basehttps://api.chinalogistichub.com/api/v1/api/v1

REST

OpenAPI-described JSON endpoints.

Webhooks

HMAC-SHA256 signed event delivery.

Rate-aware

60 rpm default, enterprise raises it.

01

身份验证

在公司控制台中生成 API 密钥。使用以下任一请求头发送:

完整密钥仅在创建时显示一次。一旦泄露请立即作废。

request.http·
Authorization: Bearer clh_live_<prefix>_<secret>
# or
X-API-Key:     clh_live_<prefix>_<secret>

02

快速开始

curl200 OK
curl -H "Authorization: Bearer $CLH_KEY" \
     https://api.chinalogistichub.com/api/v1/api/v1/public/ping

03

OpenAPI 规范

适用于代码生成的机器可读契约(openapi-generator、orval 等)。

POST/api/v1/requests
GET/api/v1/requests/{id}/quotes
POST/api/v1/quotes/{id}/award
GET/api/v1/shipments/{id}
GET/api/v1/shipments/{id}/documents
POST/api/v1/developers/webhooks

04

Webhook

通过以下方式订阅事件: POST /api/v1/developers/webhooks 。每次投递会在以下请求头中携带 HMAC-SHA256 签名: X-CLH-Signature.

重试策略

6 次投递尝试,起始 30 秒指数退避。从未返回 2xx 的请求会进入死信日志,可通过以下方式查看: GET /developers/webhooks/:id/deliveries

签名请求头node
X-CLH-Signature: t=1713398400,v1=<hex>

const base = `${t}.${rawBody}`;
const expected = crypto.createHmac('sha256', secret)
  .update(base).digest('hex');
// Compare with timingSafeEqual, reject if |now - t| > 300s

支持的事件

  • request.created
  • request.status_changed
  • shipment.created
  • shipment.status_changed
  • shipment.delivered
  • quote.received
  • quote.awarded
  • quote.selected_confirmed
  • invoice.paid
  • document.uploaded
  • document.expiring

05

速率限制

默认:每个 API 密钥 60 次 / 分钟。Enterprise 套餐可提高限制。

ship faster

准备好集成?在以下位置创建密钥:

开发者控制台