认证方式

本体系下的所有接口都使用同一套鉴权规则，通过服务端鉴权校验的接口才会被正常地、合法地执行接口文档中描述的业务逻辑。

鉴权参数

商家和酷家乐进行商务合作之后，酷家乐将会分配给商家一组 appkey 和 appsecret，这两个参数在接口鉴权中起到了最重要的作用。

所有接口的入参，除了各接口文档中所描述的，还必须额外加上以下 URL Query Param：

参数	是否必须	含义
appkey	是	商家和酷家乐商务合作之后，酷家乐分配给商家的 appkey。这会是一个 10 位长度的字符串。
timestamp	是	格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒（北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒）起至现在的总毫秒数，比如：1485878400000。注意，一些编程语言自带的库获取到的时间戳是精确到秒，这时需要乘以 1000。
appuid	否	第三方用户的 ID。不是所有接口都需要这个参数，具体的接口文档中会在 URL Query Param 注明该接口是否需要这个参数。
sign	是	签名值，根据 appuid 是否存在，有两种不同的计算方式。

签名计算规则

方式一：appuid 不存在

sign = md5(appsecret + appkey + timestamp)

方式二：appuid 存在

sign = md5(appsecret + appkey + appuid + timestamp)

注意

appsecret 我们不可在网络中传播，而只是用于在计算 sign 值的时候使用。appsecret 只应该保存在商家应用的服务端以及酷家乐的服务端，请避免泄露，否则导致安全问题，酷家乐有权封禁商家的接口调用。

请求示例

示例 1：不需要 appuid 的接口

接口文档中描述需要 URL Query Param 为 test_param，那么最后调用的时候应该是类似：

GET https://openapi.kujiale.com/v2/test?appkey=[appKey]&timestamp=[timestamp]&sign=[sign]&test_param=123

其中 sign 的计算方式为：sign = md5(appsecret + appkey + timestamp)

示例 2：需要 appuid 的接口

如果接口文档中 URL Query Param 还注明需要 appuid：

GET https://openapi.kujiale.com/v2/test?appkey=[appKey]&timestamp=[timestamp]&appuid=[appuid]&sign=[sign]&test_param=123

其中 sign 的计算方式为：sign = md5(appsecret + appkey + appuid + timestamp)

Python 示例

import hashlib
import time
import requests

appkey = "YOUR_APPKEY"
appsecret = "YOUR_APPSECRET"

# 生成时间戳（毫秒）
timestamp = str(int(time.time() * 1000))

# 计算签名（假设不需要 appuid）
sign_str = appsecret + appkey + timestamp
sign = hashlib.md5(sign_str.encode()).hexdigest()

# 构建请求
url = "https://openapi.kujiale.com/v2/test"
params = {
    "appkey": appkey,
    "timestamp": timestamp,
    "sign": sign,
    "test_param": "123"
}

response = requests.get(url, params=params)
print(response.json())

响应格式

所有接口返回统一格式：

{
  "c": "0",      // 状态码，"0" 表示成功
  "d": { ... },  // 返回数据
  "m": null,     // 消息
  "f": ""        // 额外信息
}

字段	说明
c	状态码，"0" 表示成功，其他值表示错误
d	返回的业务数据
m	错误消息（失败时）
f	额外信息

错误处理

当 c 不为 "0" 时，表示请求失败。常见错误码：

错误码	说明
-1	通用错误
1	配置错误
12	Token 异常
13	任务不存在或已结束