API 文档说明

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

调用方式

请求结构

host: https://api.ipfly.net/

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

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

POST (Content-Type: application/json)

GET

公共参数

注意:
公共参数是用于标识用户和接口签名的参数，如非必要，在每个接口单独的文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。

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

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

HTTP GET 请求结构示例:

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

签名方法

API 会对每个请求进行身份验证，用户需要使用安全凭证，经过特定的步骤对请求进行签名（Signature），每个请求都需要在公共参数中指定该签名结果并以指定的方式和格式发送请求。

签名目的

签名通过以下方式帮助保护请求:

验证请求者的身份
签名确保请求是由持有有效访问密钥的人发送的。请联系客户经理获取密钥相关信息。

保护传输中的数据
为了防止请求在传输过程中被篡改，API 会使用请求参数来计算请求的哈希值，并将生成的哈希值加密后作为请求的一部分，发送到API 服务器。服务器会使用收到的请求参数以同样的过程计算哈希值，并验证请求中的哈希值。如果请求被篡改，将导致哈希值不一致，API 将拒绝本次请求。时间戳验证,需要保持时间同步,API 验证时间戳差值跨度5分钟

签名过程

API 支持 GET 和 POST 请求。对于GET方法，只支持 Content-Type: application/x-www-form-urlencoded 协议格式。对于POST方法，目前支持 Content-Type: application/json格式

对参数排序
首先对所有请求参数按参数名的字典序（ ASCII 码）升序排序。
注意：

只按参数名进行排序，参数值保持对应即可，不参与比大小；

按 ASCII 码比大小，如 InstanceIds.2 要排在 InstanceIds.12 后面，不是按字母表，也不是按数值。用户可以借助编程语言中的相关排序函数来实现这一功能，如 PHP 中的 ksort 函数。Java 中的treeMap.

对于application/json 请求, 请求体JSON字符串(最终发送字符串)作为一个整体 使用 body={$json} 作为键值 参与排序, 这里不会把json 内容中的单个字段进行排序
举例参数的排序结果如下:

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

拼接签名字符串
此步骤生成签名字符串。
将把上一步排序好的请求参数格式化成“参数名称=参数值”的形式，如对 app_id 参数，其参数名称为 "app_id" ，参数值为 "240xxxxxx001" ，因此格式化后就为 app_id=240xxxxxx001.
注意：“参数值”为原始值而非 url 编码后的值。

然后将格式化后的各个参数用"&"拼接在一起，最终生成的请求字符串为:

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

拼接签名KEY:

签名KEY 用户需要妥善保管在本地, 不要在通信过程中进行传输

将步骤2中拼接的字符串末尾追加签名KEY: &key=2f6ab3c81xxxxxxxxcff9a5e得到字符串:

"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 计算签名得到 Signature;

设置签名
将生成签名的参数放入header 中,详见 公共参数 部分

调用方式#

请求结构#

公共参数#

签名方法#