鹰眼 API 文档
Open Platform Document Center

外观

对接指南 ​

API通用说明 ​

公共请求参数 ​

参数说明

参数名类型必填说明
appIdstring是应用Id,同账号
datastring是加密后的请求参数数据体
timestampstring是时间戳

参数示例

json
{
  "appId": "",
  "data": "",
  "timestamp": 0
}

公共返回参数 ​

参数说明

参数名类型必填说明
codeinteger是状态码
msgstring是返回消息
datastring是加密后的响应数据体

参数示例

json
{
  "code": 0,
  "msg": "",
  "data": ""
}

API加解密说明 ​

方式 ​

加密加签采用 SM4 加密算法,配置以及工具类联系研发。(只加解密 data 载体中的内容)

工具类 ​

Sm4Util

java
package com.hawkeye.open.utils;
import cn.hutool.core.util.HexUtil;
import cn.hutool.crypto.SmUtil;
import cn.hutool.crypto.symmetric.SM4;
import javax.crypto.SecretKey;

/**
 * SM4加解密工具类
 * @author hualess
 * @date 2024/12/2 17:45
 * @link <a href="https://hualess.cn"></a>
 */
public class Sm4Util {

	/**
	 * 获取sm4秘钥
	 *
	 * @return sm4秘钥
	 */
	public static String getSm4Key() {
		SM4 sm4 = SmUtil.sm4();
		SecretKey secretKey = sm4.getSecretKey();
		byte[] encoded = secretKey.getEncoded();
		return HexUtil.encodeHexStr(encoded);
	}

	/**
	 * sm4加密
	 *
	 * @param content 文本
	 * @param sm4Key  sm4秘钥
	 * @return 加密后的结果
	 */
	public static String encrypt(String content, String sm4Key) {
		SM4 sm4 = new SM4(HexUtil.decodeHex(sm4Key));
		return sm4.encryptHex(content);
	}

	/**
	 * @param content
	 * @param sm4Key
	 * @return 解密后的结果
	 */
	public static String decrypt(String content, String sm4Key) {
		SM4 sm4 = new SM4(HexUtil.decodeHex(sm4Key));
		return sm4.decryptStr(content);
	}

	public static void main(String[] args) {
		String sm4Key = getSm4Key();
		System.out.println("sm4Key：" + sm4Key);
		String content = "123456";
		String encrypt = encrypt(content, sm4Key);
		System.out.println("加密后：" + encrypt);
		String decrypt = decrypt(encrypt, sm4Key);
		System.out.println("解密后：" + decrypt);
	}
}

API规则说明 ​

所有的API请求必须使用HTTPS，请求时不应忽略服务器证书验证的错误，避免被恶意劫持。

数据格式 ​

使用 JSON作为消息体的数据交换格式。请求须设置 HTTP 头部（图片上传 API 除外）

txt
Content-Type: application/json
Accept: application/json

[!tip]提示 API 应答中的数据有可能包含客户传入的数据，即可能是未经检查的用户输入内容。为了避免 XSS（Cross-site scripting）攻击，请调用方在使用应答数据前根据场景做适当的转义或者过滤。

参数兼容性 ​

  • 请求是否成功，与请求参数的顺序无关
  • 请求是否成功，与请求 JSON 中的键值对出现的顺序无关
  • 处理应答时，不应假设应答 JSON 中的键值对出现的顺序
  • 当请求或应答中的 JSON 键值对的值为空（null）时，可以省略
  • 文档中所有标记为 Y 表示必填、N 非必填、O 条件必填

字符集 ​

仅支持 UTF-8 字符编码的一个子集：使用一至三个字节编码的字符。也就是说，不支持 Unicode 辅助平面中的四至六字节编码的字符

日期格式 ​

所有的日期对象，使用 ISO 8601所定义的格式。

示例:

txt
yyyy-MM-DDTHH:mm:ss.SSSZ
yyyy-MM-DDTHH:mm:ssZ
yyyy-MM-DDTHH:mm:ss.SSS+08:00
yyyy-MM-DDTHH:mm:ss+08:00

错误信息 ​

鹰眼系统使用 HTTP 状态码来表示请求处理的结果。

  • 处理成功的请求，如果有应答的消息体将返回 200，若没有应答的消息体将返回 204；
  • 已经被成功接受待处理的请求，将返回 202；
  • 请求处理失败时，如缺少必要的入参、订单操作不规范等，将会返回 4xx 范围内的错误码；
  • 请求处理时发生了鹰眼系统侧的服务系统错误，将返回 500/501/503 的状态码。这种情况比较少见。

错误码和错误提示 ​

当请求处理失败时，除了 HTTP 状态码表示错误之外，API 将在消息体返回错误相应说明具体的错误原因。

  • code：详细错误码；
  • msg：错误描述，使用易理解的文字表示错误的原因；

Example:

json
{
  "code": 500,
  "msg": "无效请求"
}

HTTP 状态码 ​

常见的 HTTP 状态码见下表。

状态码错误类型一般的解决方案
200 - OK处理成功
Successfully processed		/
204 - No Content处理成功，无返回 Body
Successfully processed, no return body		/
400 - Bad Request协议或者参数非法
Protocol or parameter is invalid		请根据接口返回的详细信息检查您的程序
Check your program based on the detailed information in the interface return
401 - Unauthorized签名验证失败
Signature verification failed		请检查签名参数和方法是否都符合签名算法要求
Check whether the signature parameters and methods comply with the signature algorithm requirements
403 - Forbidden权限异常
Permission issue		请开通客户号相关权限。请联系产品或商务申请
Enable the related permissions for the customer number. Contact product or business to apply
404 - Not Found请求的资源不存在
The requested resource does not exist		请对接客户检查需要查询的 ID 或者请求 URL 是否正确
Please check if the ID to be queried or the request URL is correct
406 - Not Acceptable不接受的请求
Unacceptable request		请检查请求时间戳内的随机串是否重复
Please check if the random string within the request timestamp is duplicated
429 - Too Many Requests请求超过频率限制
Exceeded frequency limit		请求未受理，请降低频率后重试
The request was not accepted; please retry after reducing the frequency
500 - Server Error系统错误
System error		按具体接口的错误指引进行重试
Retry according to the specific error guidance of the interface
502 - Bad Gateway服务下线，暂时不可用
Service offline, temporarily unavailable		请求无法处理，请稍后重试
The request could not be processed; please try again later
503 - Service Unavailable服务不可用，过载保护
Service unavailable, overload protection		请求无法处理，请稍后重试
The request could not be processed; please try again later

安全 ​

参考接口加解密

最后更新于: