API 文档说明

本文档介绍API 使用说明, 请仔细阅读

调用方式

请求结构

HOST: https://api.ipfly.net

通信协议: API 所有接口均通过 HTTPS 进行通信,提供高安全性的通信通道。

请求方法:
支持的HTTP 请求方法:

POST ( Content-Type: application/json)

GET

公共参数

注意:
公共参数用于标识用户和接口签名。各接口文档不再重复说明,但每次请求必须携带
所有公共参数需统一置于 HTTP Header 中：

使用方法签名时,公共参数需要统一放到Http Header 请求头中,如下表所示:

参数名称	类型	必选	Http Header	描述
`app_id`	String	是	X-IF-APP-ID	接入ID,接入API 时分配的唯一标识
`nonce`	String	是	X-IF-NONCE	接口签名随机字符串(每请求唯一)
`timestamp`	Long	是	X-IF-TIMESTAMP	接口签名时间戳(毫秒级,±5分钟内有效)
`sign`	String	是	X-IF-SIGN	请求参数签名(详见签名算法)

请求示例

HTTP GET 请求结构示例:

HTTP POST （application/json）请求结构示例:

签名方法

API会对每个请求进行身份验证，用户需要使用安全凭证，经过特定的步骤对请求进行签名(Signature)，每个请求都需要在公共参数中指定该签名结果并以指定的方式和格式发送请求。
API支持GET和POST请求。对于GET方法，只支持 Content-Type: application/x-www-form-urlencoded 协议格式。对于POST方法，目前支持 Content-Type: application/json格式

签名目的

验身份验证：确保请求由持有有效密钥的用户发起

数据完整性：防止请求在传输中被篡改

时间验证：服务器校验时间戳（±5 分钟有效）

签名流程

步骤1：参数排序

对所有请求参数（含 body）按参数名的 ASCII 码升序排序

关键规则：

仅按参数名排序，参数值保持不变

按 ASCII 码排序（如 InstanceIds.2 排在 InstanceIds.12 之前）

application/json 请求中，body 字段作为整体参与排序（不拆分 JSON 内部字段）

举例参数的排序结果如下:

{
   "app_id":240xxxxxx001,
   "body":{"pageNum": 1,"pageSize": 50,"createTimeStart": "2023-03-16","createTimeEnd": "2023-08-05"},
   "nonce":"1233232",
   "num":12,
   "timestamp":1713255039992
}

步骤2：拼接签名字符串

将排序后的参数格式化为 key=value 形式。

用 & 连接所有参数

注意：“参数值”为原始值（非 URL 编码）

举例参数的排序结果如下:

"app_id=24083001001&body={"pageNum": 1,"pageSize": 50,"createTimeStart": "2023-03-16","createTimeEnd": "2024-08-05"}&nonce=cdbb619b47bb5340d41b6fecbd7bf9e154890ebcd26bfc0c3ae187c85c023ac1&num=25&timestamp=1713256038257"

步骤3：拼接签名KEY

在签名字符串末尾追加 &key=YOUR_SECRET_KEY（YOUR_SECRET_KEY 为客户端与服务端共享的密钥）

重要 : 密钥需妥善保管,不可在请求中传输

| 完整签名字符串示例：

"app_id=24083001001&body={"pageNum": 1,"pageSize": 50,"createTimeStart": "2023-03-16","createTimeEnd": "2024-08-05"}&nonce=cdbb619b47bb5340d41b6fecbd7bf9e154890ebcd26bfc0c3ae187c85c023ac1&num=25&timestamp=1713256038257&key=2f6ab3c81xxxxxxxxcff9a5e"

步骤4：生成签名

对完整签名字符串执行 MD5 哈希计算

结果即为 sign 参数值

步骤5：设置签名

将生成的 sign 值放入 HTTP Header X-IF-SIGN

详见 公共参数 部分

调用方式#

请求结构#

公共参数#

请求示例#

HTTP GET 请求结构示例:#

HTTP POST （application/json） 请求结构示例:#

签名方法#

签名目的#

签名流程#