具语开放接口

主题

对接指南 ​

本文帮助您从零开始完成接口对接。请按顺序阅读，完成每一步即可成功调用。

第一步：获取凭证 ​

在调用接口前，您需要联系我们获取以下信息：

凭证说明示例
AccessKey（AK）访问标识，用于身份识别your_access_key
SecretKey（SK）密钥，用于计算签名，不可暴露给客户端your_secret_key

安全警告

SecretKey 仅允许保存在服务端或安全环境变量中，严禁写入前端代码、日志、版本控制系统。

第二步：确定服务地址 ​

环境基地址用途
测试环境http://203.2.112.61:8095开发联调，数据不影响生产
正式环境https://api.juyu.top生产使用

所有接口均以 /openapi 为前缀，完整示例：

POST http://203.2.112.61:8095/openapi/order/createOrder

第三步：构造请求 ​

一个完整的 API 请求由以下部分组成：

┌─────────────────────────────────────────────┐
│  POST /openapi/order/createOrder HTTP/1.1   │  ← 请求方法 + 路径
│  Host: api.juyu.top                         │  ← 服务地址
│  Content-Type: application/json; charset=UTF-8 │  ← 内容类型
│  X-Access-Key: your_access_key              │  ← 身份标识
│  X-Timestamp: 1718236800                    │  ← 时间戳（Unix秒）
│  X-Nonce: a1b2c3d4e5f6                      │  ← 防重放随机串
│  X-Sign: 6a8f3c...（小写hex）                 │  ← 签名
│                                             │
│  {"cusSelfOid":"ORDER-001", ...}            │  ← 业务请求体
└─────────────────────────────────────────────┘

公共请求头 ​

请求头类型必填说明示例值
Content-TypeString是固定值application/json; charset=UTF-8
X-Access-KeyString是分配给您的访问标识your_access_key
X-TimestampString是Unix 秒时间戳（十进制字符串），须与签名计算一致1718236800
X-SignString是HMAC-SHA256 签名结果（小写十六进制）6a8f3c1d2e...
X-NonceString建议防重放随机串，建议每次请求唯一a1b2c3d4e5f6

第四步：计算签名 ​

签名用于验证请求的合法性和完整性。

4.1 收集参与签名的参数 ​

规则：

  1. POST/PUT 等非 GET 请求：URL Query 参数 + JSON Body 一级字段 合并参与签名
  2. 同名键以 Body 为准
  3. 键 _t、sign 不参与签名
  4. 值为 null 的字段不参与签名
  5. Body 值的字符串转换规则：
值类型转换规则示例
字符串原样"hello" → hello
数值 / 布尔转字符串100 → 100，true → true
对象 / 数组紧凑 JSON[1,2] → [1,2]

4.2 构造规范化串 ​

将收集到的参数按参数名升序排序后拼接：

text
paramPart = key1=value1&key2=value2&...
canonical = paramPart + "|ts=" + timestamp + "|ak=" + accessKey

4.3 计算签名值 ​

text
X-Sign = HMAC-SHA256(canonical, secretKey)   // 结果转小写十六进制字符串

第五步：发起请求并验证 ​

完整请求示例 ​

假设参数如下：

项值
AccessKeytest_ak
SecretKeytest_sk
接口POST /openapi/order/createOrder
时间戳1718236800
Body{"cusSelfOid":"ORDER-001","companyWorkNo":"101121"}

签名计算过程：

text
① 收集参数（Body 一级字段）：
   cusSelfOid = ORDER-001
   companyWorkNo = 101121

② 按参数名升序排列拼接：
   paramPart = "companyWorkNo=101121&cusSelfOid=ORDER-001"

③ 拼接规范化串：
   canonical = "companyWorkNo=101121&cusSelfOid=ORDER-001|ts=1718236800|ak=test_ak"

④ HMAC-SHA256 签名：
   X-Sign = HMAC-SHA256(canonical, "test_sk")
          = "a3f8e2b1c4d5..."  // 小写十六进制

最终请求：

http
POST /openapi/order/createOrder HTTP/1.1
Host: api.juyu.top
Content-Type: application/json; charset=UTF-8
X-Access-Key: test_ak
X-Timestamp: 1718236800
X-Nonce: rand123456
X-Sign: a3f8e2b1c4d5...

{"cusSelfOid":"ORDER-001","companyWorkNo":"101121"}

统一响应体 ​

所有接口返回统一结构：

json
{
  "code": 200,
  "message": "success",
  "result": { ... },
  "traceId": "20260613120000-abc123"
}
字段类型说明
codeInteger业务状态码，200 表示成功
messageString提示信息
resultObject / Array / null业务数据
traceIdString链路追踪标识（可选）

请以 code 判断业务是否成功，不要依赖 HTTP 状态码。

常见错误码 ​

code含义排查方向
200成功—
400参数校验失败检查必填参数、格式
401签名验证失败检查 AK/SK、canonical 串、时间戳
403无权限确认 AK 是否已开通对应接口
500服务端异常提供 traceId 联系技术支持

接口清单 ​

分组接口路径说明
订单创建订单/openapi/order/createOrder新增订单，返回具语运单号
订单修改订单/openapi/order/updateOrder按具语运单号更新
订单取消订单/openapi/order/orderCancel商家侧取消订单
订单物流取消/openapi/order/logisticsCancel物流侧取消待揽收订单（0→2）
订单绑定物流运单/openapi/order/bindWaybill回传物流运单号并同步轨迹
运单运单数据拉取/openapi/waybill/getWaybillData按条件拉取运单
运单轨迹数据拉取/openapi/waybill/getTrackData按条件拉取轨迹
运单运单号转换/openapi/waybill/convertJyWaybillNo物流运单号批量转具语运单号
超区地址关键字检索/openapi/superzone/searchAddressByKeyword地址联想（索引/地图）
超区超区公司列表/openapi/superzone/superZonePriceList超区配置列表查询
IM获取登录令牌/openapi/im/getAccountToken获取 IM SDK 登录令牌
IM是否可使用 IM/openapi/im/isIm查询 IM 开关状态
IM创建企业控制台群聊/openapi/im/createTeam商家/物流发起企业控制台客服群

联调建议 ​

  1. 先跑通签名：用最简参数（如取消订单只需 jyWaybillNo）验证签名是否正确
  2. 时间戳对齐：确保服务器时间与标准时间偏差在 5 分钟内
  3. Body 一致性：用于计算签名的 Body 内容必须与实际发送的请求体完全一致（包括字段顺序、空格）
  4. 签名失败排查清单：
    • [ ] AK 是否正确
    • [ ] 时间戳是否与签名计算时一致
    • [ ] 参数是否按名称升序排列
    • [ ] null 值字段是否已排除
    • [ ] Body 中对象/数组是否用了紧凑 JSON（无空格）

具语物流开放平台