Joryea

在 Joryea 开放平台上构建集成

自有系统对接、业务自动化与数据同步：通过签名鉴权的 REST 数据面（Open Data Plane）读取车源数据，与服务商体系同源同频。

申请接入查看接入流程

平台能力

开放数据面

读取已上架车源（GET /api/v1/open/v1/listings），支持分页与类目过滤。敏感字段在服务端脱敏，仅白名单字段出平台。

HMAC 签名鉴权

每个请求以 client secret 对规范串做 HMAC-SHA256 签名，线上不传密钥本体；±5 分钟时间窗阻断重放攻击。

scope 权限模型

每个开放平台应用按需授予细粒度作用域（如 listings:read），越权请求在任何数据返回前即被 403 拒绝。

可预期的限流策略

数据面流量按应用限流，超限返回 429 与 Retry-After 头，规范集成可据此自动退避重试。

快速开始：调用车源列表端点

端到端可运行示例：拼装规范串、计算签名、读取一页车源。请将占位凭证替换为您自己的凭证。

请求示例（curl）

# 占位凭证：请在商家中心「开放平台凭证」获取后替换
CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"

# 1) 规范串四段：METHOD / pathWithQuery / timestamp / sha256hex(body)
#    GET 请求 body 恒为空串，其 sha256 固定为
#    e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
METHOD="GET"
PATH_WITH_QUERY="/api/v1/open/v1/listings?page=1&pageSize=20"
TIMESTAMP="$(date +%s)"
BODY_HASH="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

# 2) 签名 = HMAC-SHA256(CLIENT_SECRET, 规范串) 的小写 hex
CANONICAL=$(printf '%s\n%s\n%s\n%s' "$METHOD" "$PATH_WITH_QUERY" "$TIMESTAMP" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" | awk '{print $NF}')

# 3) 发起请求（签名三头缺一不可）
curl -s "https://www.joryea.com${PATH_WITH_QUERY}" \
  -H "x-client-id: ${CLIENT_ID}" \
  -H "x-timestamp: ${TIMESTAMP}" \
  -H "x-signature: ${SIGNATURE}"

签名算法（伪代码）

canonical = UPPER(method) + "\n" + pathWithQuery + "\n" + timestamp + "\n" + sha256hex(body)
signature = lowercase_hex( HMAC_SHA256(clientSecret, canonical) )

# 校验顺序（任一失败统一 401 OPEN_UNAUTHORIZED，防探测）：
#   缺头 → 未知 clientId → 时间窗越界（±300s）→ 签名不符（恒定时间比较）
# 签名通过后做 scope 白名单裁决：不足 → 403 OPEN_SCOPE_DENIED

响应示例（节选）

{
  "items": [
    {
      "listingId": "lst_9f2c81e4",
      "title": "2022 比亚迪 汉 EV 旗舰型",
      "titleEn": "2022 BYD Han EV Flagship",
      "category": "sedan",
      "priceAmount": 18990000,
      "priceCurrency": "CNY",
      "images": ["https://cdn.joryea.com/media/lst_9f2c81e4/01.jpg"],
      "dealerOrgId": "org_5a71d30b"
    }
  ],
  "total": 42
}

签名请求头：x-client-id 标识应用，x-timestamp 为 epoch 秒时间戳，x-signature 为小写十六进制 HMAC-SHA256 签名。
鉴权失败统一返回 401 OPEN_UNAUTHORIZED；作用域不足返回 403 OPEN_SCOPE_DENIED。

四步接入

从申请到上线的引导式路径。

申请凭证
提交对接场景说明，平台审核后签发 client ID、client secret 及所需 scope。
签名验证
实现规范串拼装与 HMAC-SHA256 签名，在预发环境调用车源端点直至鉴权通过。
联调
以真实业务流程对沙盒数据联调，覆盖分页、空结果、时钟偏移与错误信封。
上线
切换生产凭证，密钥入库保管，并对 401/429 信号建立重试与监控。

常见问题

谁可以申请开放平台接入？

需要将自有系统（ERP、DMS、第三方市场等）与 Joryea 对接的服务商与开发者。通过下方联系入口提交场景说明，平台审核后签发凭证。

为什么用 HMAC 签名而不是静态 API Key？

密钥本体从不出现在请求中，线上只有签名；配合时间窗可防御重放与传输截获。静态 Key 一旦泄露即全线失守，两者安全等级不同。

车源端点返回什么数据？

已上架车源的白名单脱敏视图：listingId、title、titleEn、category、priceAmount（最小货币单位，即分）、priceCurrency、images 与 dealerOrgId，外加 total 总数供分页。

错误码如何理解？

401 OPEN_UNAUTHORIZED 涵盖缺头、未知应用、时间窗越界与签名不符（刻意不作区分以防探测）；403 OPEN_SCOPE_DENIED 表示应用缺少所需作用域；404 OPEN_APP_NOT_FOUND 表示应用已不存在。

密钥泄露后如何轮换？

在车商中心「开放平台凭证」页轮换 client secret。轮换后旧密钥立即失效，请在同一窗口完成服务配置更新。