接口格式统一说明
API 标准结构
若无特殊声明,则所有的 API 标准格式为 application/json,且响应参数参考以下标准。
{ "data": { // 数据 }, "statusCode": "SUCCESS", // 响应码 "message": null, // 响应内容 "success": true // 是否成功 }
响应码状态表
响应码
描述
SUCCESS
操作处理成功。
TIMESTAMP_ERROR
时间戳异常。
SIGNATURE_ERROR
鉴权签名验证失败。
ACCESS_KEY_ERROR
API公钥错误。
PARAMETER_ERROR
其余参数错误。
NO_ADVERTISEMENT
当前暂未匹配到广告信息,请稍后重试。
ACCOUNT_STATUS_ERROR
账户状态异常。
SYSTEM_ERROR
系统异常。
鉴权方式
所有 HTTP 请求均需要在 header 传入以下参数:
字段名称
字段类型
字段描述
access-key
String
当前系统生成的API公钥,与API私钥结合使用。
timestamp
Long
请求发出时的 UTC 时间戳,精确到毫秒。
signature
String
鉴权签名,具体详见运算方式。
signature 鉴权逻辑的算法为:HmacSHA256。在商户的账号审核通过后,商户会自动获得一个绑定的公钥(access-key)和私钥(secret-key)。
其中 HmacSHA256 的计算信息为:
{access-key}_{timestamp}
例如:B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R_1625546438154。两个 timestamp 需要保持一致。
HmacSHA256 的私钥信息为分配的私钥(secret-key):
{secret-key}
例如:WUYx7DTQZakugtP9gOAimYUphcnc3jWuPRi1UVnWmwXSnMnsCVBzz1ILdaxisvz9。
则计算后的 signature 为:(不区分大小写)
EDB15CF33C232128BDF118CEB147C453181939F8B37EC43886F68B3BCC2C19CD
鉴权代码示例(Java)
String originSignature = String.format("%s_%s", accessKey, timestamp); Mac hashInstance = Mac.getInstance("HmacSHA256"); hashInstance.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256")); byte[] hash = hashInstance.doFinal(originSignature.getBytes()); String signature = DatatypeConverter.printHexBinary(hash);