1. 概览

本文是爱快开放平台 Open API 3.0 的官方文档，旨在为爱快开放平台合作者提供详细的 Open API 描述，各类相关资源的入口汇总等 内容主要涵盖：

  • 协议、调用地址

  • 交互规范

  • 数据模型

  • 接口测试界面

1.1. 版本信息

版本 : 3.0.0

1.2. URI scheme

域名 : open.ikuai8.com
基础路径 : /api/v3
方案 : HTTPS

1.3. 标签

  • 平台认证类接口 : Open Platform Auth【调用频度限制：60次 / 分钟】

  • 路由器授权查询类接口 : Router Authorization Query【调用频度限制：60次 / 分钟】

  • 路由器系统设置类接口 : Router System Settings【调用频度限制：120次 / 分钟】

  • 路由器认证计费类接口 : Router Auth Billing【调用频度限制：120次 / 分钟】

2. 快速开始

2.1. 重要提示

iKuai Open API 3.0 以下称新版 继承并发展自初版 iKuai Open API 以下称初版、旧版 [1]，在分析了初版 API 长期运行统计结果，总结了对接合作方的反馈，并充分考虑安全，效率，稳定，容错，对接难度等因素后，爱快对 3.0 版本的 Open API 的调用方式和规范进行了调整。

力求达到如下目标：
简化新加入爱快开放平台合作者的对接难度
降低从旧版 API 升级到 3.0 的复杂度与代价 [2]

现将重点内容罗列如下：

  1. 废弃了旧版 API 需要对整个请求正文进行 RSA 加密的方式，改为简短的字段加密，降低客户端与服务端的额外计算消耗，同时规避了加密原文过长导致需要 chunk 加密串的问题

  2. 引入 AccessToken 作为 API 认证凭据，认证成功一次可以复用一定次数或时长，且有多种 Token 存活策略可供选择

  3. 新版 API 兼容在爱快 2.x (部分路由)和全新架构的 3.x (全部路由)设备上的调用，也即：在新版 API 调试成功的代码可以获得长期支持(LTS)，不必为不同版本路由编写多套调用代码

  4. 对不急于迁移到 3.0 版本 API 的调用者来说，无须做任何改变，旧版 Open API 保持原样 [3]

  5. 现有运行在爱快开放平台上的合作商业务、open_id 与公钥、授权设备信息、审核通过的业务涵盖的 API 信息，对新版 API 依然有效且一致。官方后续开放的 API 则依旧按照开放平台的业务审核流程进行申请。

3分钟视频，玩转 iKuai Open API 3.0

2.2. API 调试方式 (官方推荐方式)

不编写任何代码，快速开始调用 API，查看调用结果！
快速生成多种语言的客户端代码，开箱即用！
与爱快开发人员使用同样的工具，调试新版 iKuai Open API！

2.2.1. 准备条件

工具：postman

安装 postman for chrome 插件 [4]

iKuai Open API 3.0.0 的 postman 描述文件
以下文件无须下载，postman 支持导入 URL
确保 hash 校验与官方描述的一致！
Table 1. iKuai Open API 3.0 collection for postman
URL https://open.ikuai8.com/doc/3.0/postman_collection.json

MD5

ed4bd780bb97eaaafe4d5aeb4b6aacb0

SHA1

22cb132b981908c5b022850545053676427e403f
Table 2. iKuai Open API 3.0 environment for postman
URL https://open.ikuai8.com/doc/3.0/postman_environment.json

MD5

203B39F42CCC171CC391F3A6DB18F52F

SHA1

7AFA4C3422CCF3BF26BBB361F71FBEB2DC756D9F

2.2.2. 调试步骤

1 启动 postman
2 导入 iKuai Open API 3.0.0 的 postman 描述文件
3 输入必要的参数（open_id, open_rsa_pubkey, gwid）
4 测试各个接口
5 使用 postman 的 code 功能生成目标语言的客户端代码
6 愉快的开始业务逻辑的开发进程

使用 postman 调试 API 时，为简化操作，RSA 加密在 postman 内部完成，免去了在 postman 外部自行生成加密串的麻烦。但方便的同时，需要调用者将其爱快开放平台公钥填入 postman 的 Pre-request Script，此时一定注意

谨慎使用诸如：postman 的 share collection，share evnironment 等会暴露自己公钥等信息的功能。

这里推荐几种安全实践：

a) 离线使用 postman (不登录 postman 账号)，不使用 share collection，不使用 share evnironment
或者
b) 每次使用 postman 测试完成，就清空 Pre-request Script 中的 open_id 和 open_rsa_pubkey 变量
或者
c) 不将开放平台公钥填入 postman，在 postman 外部自行生成加密签名，仅将加密串结果硬编码进 Pre-request Script

3. 资源

3.1. 平台认证类接口

Open Platform Auth【调用频度限制：60次 / 分钟】

3.1.1. 『获取 AccessToken』

POST /open/access_token
说明

使用从爱快开放平台获取的公钥生成加密签名串，获取AccessToken 签名 sign = base64_encode( rsa_enc_use_pubkey ( request_time, pubkey ) ) base64_encode 和 rsa_enc_use_pubkey 使用各种语言自己的 base64 和 rsa 实现

参数
类型 名称 说明 类型

Body

body
必填

JSON 格式的请求体

AccessTokenRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

AccessToken

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/access_token
请求 body
{
  "client_type" : "OPEN_PARTNER",
  "client_id" : "ikoxxxxxxxxxxxxxxxx",
  "request_time" : 1503525563,
  "options" : {
    "token_lifetime" : 7200
  },
  "sign" : "WamFBz2+2EaLTuvcCVg4//ZsicziHoZ1bssV3ezaFfWz+15d92ErR/25kMBgET/FsmobAj9aMfhja9juMMF1riExB6dzDh6lr/mAD6Fnnf/bDcohtYA/tlZl9+uWP/YbDu9T+2KIHR1btd2YvdebPQDRAkwWPjTJJzPhTF5dh7M="
}
HTTP响应示例
响应 200
{
  "access_token" : "WzcPH/UdrH+maCgJI5LeXmR8kL8YD+s5fzdulp5fGLky2Ur+TVxTvsgX7SaUpPrxPBdmGFgFQFGYjZgEbXKbx8RHWvLN97sACK/eBtN1/vIKbkjoieuX62kaXqShfTI4AngtEA1B6nx7jiipwiQy6/3yK8Y3sqS++ZyS21Ih+W8=",
  "token_create_time" : 1504579937,
  "token_excess_time" : 7200,
  "token_expire_at_server_time" : "2017-09-05 12:52:17"
}

3.1.2. 『刷新 AccessToken』

POST /open/refresh_token
说明

使用未过期的 AccessToken，获取新的 AccessToken

参数
类型 名称 说明 类型

Body

body
必填

JSON 格式的请求体

AccessTokenRefreshRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

AccessToken

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/refresh_token
请求 body
{
  "access_token" : "WzcPH/UdrH+daCgJI5LeXmR8kL8Yy+s5fzdllp5fGLwy2Ur+sVxTvsgXhSaUpPrxPBgmGFGFQ6GYjZgEbXKbx8RHWvLN9aWACK/eBtN1/vIKbkjoi8uX62kaXqSqfTI4AngtEA1Bhni7jiipwiQy6/3yK8Y3soS++ZyS21Ih+W8=",
  "client_id" : "ikoxxxxxxxxxxxxxxxx",
  "options" : {
    "token_lifetime" : 7200
  }
}
HTTP响应示例
响应 200
{
  "access_token" : "WzcPH/UdrH+maCgJI5LeXmR8kL8YD+s5fzdulp5fGLky2Ur+TVxTvsgX7SaUpPrxPBdmGFgFQFGYjZgEbXKbx8RHWvLN97sACK/eBtN1/vIKbkjoieuX62kaXqShfTI4AngtEA1B6nx7jiipwiQy6/3yK8Y3sqS++ZyS21Ih+W8=",
  "token_create_time" : 1504579937,
  "token_excess_time" : 7200,
  "token_expire_at_server_time" : "2017-09-05 12:52:17"
}

3.2. 路由器授权查询类接口

Router Authorization Query【调用频度限制：60次 / 分钟】

3.2.1. 『获取授权设备列表』

POST /open/dev_list
说明

使用 AccessToken，获取授权的设备列表

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

DeviceListResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/dev_list
请求 header
"string"
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "dev_id" : "xxxxx",
    "dev_remark" : "xxxxx",
    "owner_mobile" : "xxxxx",
    "owner_qq" : "xxxxx",
    "open_apis" : [ "1", "2", "3", "7", "8", "10", "12" ]
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.3. 路由器系统设置类接口

Router System Settings【调用频度限制：120次 / 分钟】

3.3.1. 『获取路由器基本信息』

POST /open/9/{gwid}
说明

固件、系统版本、ip地址，等……

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

RouterBasicResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/9/string
请求 header
"string"
HTTP响应示例
响应 200
{
  "ErrorCode" : 3000,
  "ErrorMsg" : "success",
  "Data" : {
    "name" : "iKuai-Router",
    "ap_count" : "0",
    "up_speed" : "11954",
    "down_speed" : "10632",
    "total_up" : "1220344280",
    "total_down" : "5233241489",
    "online" : "12",
    "libver" : "1.9.157",
    "sysuptime" : "173555",
    "router_ver" : "2.6.7",
    "partner" : "",
    "gwid" : "xxxxx",
    "enterprise" : "",
    "firmware" : "IK-RouterOS",
    "mac" : "00:11:22:33:44:55",
    "reflexive_address" : "100.101.102.103"
  }
}

3.3.2. 『设置路由器白名单』

POST /open/10/{gwid}
说明

设置直接放行的网址白名单

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

WhiteListRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/10/string
请求 header
"string"
请求 body
{
  "param" : {
    "whitelist" : "baidu.com",
    "whitelist_https" : "alipay.com",
    "whiteip" : "8.8.8.8",
    "noauth_mac" : "00:11:22:33:44:55,66:77:88:99:AA:BB"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4. 路由器认证计费类接口

Router Auth Billing【调用频度限制：120次 / 分钟】

3.4.1. 『获取账号列表』

POST /open/1/{gwid}
说明

获取指定设备的认证账号列表

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

AccountListReqeust
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

AccountListResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/1/string
请求 header
"string"
请求 body
{
  "param" : {
    "TYPE" : "data"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "share" : 1,
    "comment" : "备注",
    "download" : 1000,
    "auto_mac" : 0,
    "bind_vlanid" : "0",
    "username" : "username",
    "ip_addr" : "10.10.10.10",
    "ppptype" : "pppoe",
    "mac" : "00:11:22:33:44:55",
    "phone" : "138xxxxxxxx",
    "upload" : 0,
    "id" : 1,
    "cardid" : "xxxxx",
    "packages" : 0,
    "passwd" : "xxxxx",
    "create_time" : 1504591262,
    "name" : "姓名",
    "address" : "xxxxx",
    "enabled" : "yes",
    "start_time" : 1504591262,
    "bind_ifname" : "vlan1",
    "expires" : 1504595262,
    "auto_vlanid" : 0,
    "last_conntime" : 1504595262
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.2. 『在线用户踢下线』

POST /open/3/{gwid}
说明

使用用户 mac 踢下线 (较新版本的路由器支持其他方式，如：username)

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

OnlineUserKickRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/3/string
请求 header
"string"
请求 body
{
  "param" : {
    "mac" : "00:11:22:33:44:55",
    "username" : "OldJack"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.3. 『获取在线用户列表』

POST /open/4/{gwid}
说明

查询当前路由器在线用户

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

OnlineUserListRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

OnlineUserListResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/4/string
请求 header
"string"
请求 body
{
  "param" : {
    "TYPE" : "data",
    "skip" : 0,
    "limit" : 10
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "ip" : "1.2.3.4",
    "mac" : "00:11:22:33:44:55",
    "type" : 0,
    "up" : 0,
    "down" : 0,
    "connect" : 0,
    "total_up" : "xxxxx",
    "total_down" : "xxxxx",
    "connect_time" : "xxxxx",
    "id" : "10",
    "auth_time" : "xxxxx",
    "session" : "xxxxx",
    "username" : "xxxxx",
    "ppptype" : "pppoe",
    "pppdev" : "xxxxx",
    "ip_addr" : "10.11.12.13",
    "ip_addr_int" : "168496141",
    "upload" : "1000",
    "download" : "10000",
    "interface" : "eth0",
    "expires" : "0",
    "phone" : "138xxxxxxxx",
    "name" : "realname",
    "comment" : "comment",
    "webid" : "1"
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.4. 『添加账号』

POST /open/5/{gwid}
说明

为指定路由添加上网账号

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

AccountCreationRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

AccountCreationResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/5/string
请求 header
"string"
请求 body
{
  "param" : {
    "share" : 1,
    "comment" : "备注",
    "download" : 1000,
    "auto_mac" : 0,
    "bind_vlanid" : "0",
    "username" : "username",
    "ip_addr" : "10.10.10.10",
    "ppptype" : "pppoe",
    "mac" : "00:11:22:33:44:55",
    "phone" : "138xxxxxxxx",
    "upload" : 0,
    "cardid" : "xxxxx",
    "packages" : 0,
    "passwd" : "xxxxx",
    "create_time" : 1504591262,
    "name" : "姓名",
    "address" : "xxxxx",
    "enabled" : "yes",
    "start_time" : 1504591262,
    "bind_ifname" : "any",
    "expires" : 1504595262,
    "auto_vlanid" : 0,
    "last_conntime" : 1504595262
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 3000,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "id" : 1,
    "RowId" : 1
  }
}

3.4.5. 『修改账号』

POST /open/6/{gwid}
说明

修改指定路由的某上网账号

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

AccountEditRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/6/string
请求 header
"string"
请求 body
{
  "param" : {
    "share" : 1,
    "comment" : "备注",
    "download" : 1000,
    "auto_mac" : 0,
    "bind_vlanid" : "0",
    "username" : "username",
    "ip_addr" : "10.10.10.10",
    "ppptype" : "pppoe",
    "mac" : "00:11:22:33:44:55",
    "phone" : "138xxxxxxxx",
    "upload" : 0,
    "id" : 1,
    "cardid" : "xxxxx",
    "packages" : 0,
    "passwd" : "xxxxx",
    "create_time" : 1504591262,
    "name" : "姓名",
    "address" : "xxxxx",
    "enabled" : "yes",
    "start_time" : 1504591262,
    "bind_ifname" : "vlan1",
    "expires" : 1504595262,
    "auto_vlanid" : 0,
    "last_conntime" : 1504595262
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.6. 『启用/停用账号』

POST /open/7/{gwid}
说明

启用/停用指定路由的某上网账号

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

AccountStatusRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/7/string
请求 header
"string"
请求 body
{
  "param" : {
    "id" : 1,
    "status" : "up"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.7. 『删除账号』

POST /open/8/{gwid}
说明

启用/停用指定路由的某上网账号

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

AccountDeleteRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/8/string
请求 header
"string"
请求 body
{
  "param" : {
    "id" : 1
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.8. 『查询账号』

POST /open/11/{gwid}
说明

使用用户名查询账号信息

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

FindAccountByUsername
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

AccountListResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/11/string
请求 header
"string"
请求 body
{
  "param" : {
    "username" : "username"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "share" : 1,
    "comment" : "备注",
    "download" : 1000,
    "auto_mac" : 0,
    "bind_vlanid" : "0",
    "username" : "username",
    "ip_addr" : "10.10.10.10",
    "ppptype" : "pppoe",
    "mac" : "00:11:22:33:44:55",
    "phone" : "138xxxxxxxx",
    "upload" : 0,
    "id" : 1,
    "cardid" : "xxxxx",
    "packages" : 0,
    "passwd" : "xxxxx",
    "create_time" : 1504591262,
    "name" : "姓名",
    "address" : "xxxxx",
    "enabled" : "yes",
    "start_time" : 1504591262,
    "bind_ifname" : "vlan1",
    "expires" : 1504595262,
    "auto_vlanid" : 0,
    "last_conntime" : 1504595262
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.9. 『添加优惠券』

POST /open/18/{gwid}
说明

添加优惠券

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CouponAddingRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

CouponAddingResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/18/string
请求 header
"string"
请求 body
{
  "param" : {
    "comment" : "备注",
    "username" : "coupon_code",
    "enabled" : "yes",
    "expires" : 1504595262,
    "timeout" : 3600
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 3000,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "RowId" : 1
  }
}

3.4.10. 『删除优惠券』

POST /open/19/{gwid}
说明

删除优惠券

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CouponDeleteRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/19/string
请求 header
"string"
请求 body
{
  "param" : {
    "id" : 1
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.11. 『编辑优惠券』

POST /open/20/{gwid}
说明

编辑优惠券

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CouponEditRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

CouponEditResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/20/string
请求 header
"string"
请求 body
{
  "param" : {
    "id" : 1,
    "comment" : "备注",
    "username" : "coupon_code",
    "enabled" : "yes",
    "expires" : 1504595262,
    "timeout" : 3600
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 3000,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x"
  }
}

3.4.12. 『获取优惠券列表』

POST /open/21/{gwid}
说明

获取指定设备的优惠券列表

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CouponListReqeust
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

CouponListResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/open/21/string
请求 header
"string"
请求 body
{
  "param" : {
    "TYPE" : "data",
    "skip" : 0,
    "limit" : 10
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "id" : 1,
    "comment" : "备注",
    "username" : "coupon_code",
    "enabled" : "yes",
    "expires" : 1504595262,
    "timeout" : 3600,
    "used" : 1
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.13. 『推送/更新自定义认证信息』

POST /custom/22/{gwid}
说明

将指定路由器上的某个上网用户的认证信息，发送到 iKuai 开放平台，如果当前不存在则创建，已存在则更新。重要：认证类型支持多种，但一次只能定义一种，其他留空。调用 API 时选择的认证类型、在爱快云配置下发的认证类型、用户认证上网时填写的认证类型必须一致，否则无法校验认证信息。

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CustomAuthInfoRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

CustomAuthInfoResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/custom/22/string
请求 header
"string"
请求 body
{
  "param" : {
    "user_id" : "user_identifer",
    "mobile" : "",
    "card_id" : "xxxxxxxxxx",
    "adsl_id" : "",
    "passport" : "",
    "eep_id" : "",
    "room_number" : "",
    "other" : "",
    "imsi" : "xxxxx",
    "imei" : "xxxxx",
    "name" : "Pete",
    "upload" : 13579,
    "download" : 24680,
    "expires" : 1504595262,
    "comment" : "备注"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "username" : "b57d72a1ec69235ffbb3cdf007eae3c6"
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.14. 『获取自定义认证用户列表』

POST /custom/23/{gwid}
说明

获取指定设备的上的自定义认证用户列表

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

CustomAuthUserListResponse

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/custom/23/string
请求 header
"string"
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : [ {
    "username" : "e57d72e1ec69d35ffbb3cd2f0aeae3c6",
    "mobile" : "",
    "card_id" : "xxxxxxxxxx",
    "adsl_id" : "",
    "passport" : "",
    "eep_id" : "",
    "room_number" : "",
    "other" : "",
    "imsi" : "xxxxx",
    "imei" : "xxxxx",
    "name" : "Pete",
    "upload" : 13579,
    "download" : 24680,
    "expires" : 1504595262,
    "comment" : "备注",
    "created_at" : "2018-02-20 01:02:03",
    "updated_at" : "2018-02-21 04:05:06"
  } ],
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.15. 『删除自定义认证信息』

POST /custom/24/{gwid}
说明

以 username 为标识，删除某台路由器上的自定义认证用户

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CustomAuthUserDeleteRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/custom/24/string
请求 header
"string"
请求 body
{
  "param" : {
    "username" : "b57d72a1ec69235ffbb3cdf007eae3c6"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

3.4.16. 『更新自定义认证信息』

POST /custom/25/{gwid}
说明

以 username 为标识，更新某台路由器上的自定义认证用户信息

参数
类型 名称 说明 类型

Header

IK-Access-Token
必填

调用『获取 AccessToken』接口成功后得到的 token

string

Path

gwid
必填

设备的 gwid

string

Body

body
必填

JSON 格式的请求体

CustomAuthUserUpdateRequest
响应
HTTP代码 说明 类型

200

正常响应正文
头 :
x-ratelimit-limit (integer (int32)) : 频度阈值，每分钟限制次数.
x-ratelimit-remaining (integer (int32)) : 当前分钟剩余次数.

SimpleSuccess

404

Not Found，请求地址无效或请求方法错误

无内容

429

调用超限
头 :
x-ratelimit-reset (integer (int64)) : 重置时间戳（以服务器时间为准）.
retry-after (integer (int64)) : 多少秒后重置.

无内容
提交格式

  • application/json

返回格式

  • application/json

HTTP请求示例
请求 path
/custom/25/string
请求 header
"string"
请求 body
{
  "param" : {
    "username" : "b57d72a1ec69235ffbb3cdf007eae3c6",
    "mobile" : "xxxxxxxxxx",
    "card_id" : "xxxxxxxxxx",
    "adsl_id" : "xxxxxxxxxx",
    "passport" : "xxxxxxxxxx",
    "eep_id" : "xxxxxxxxxx",
    "room_number" : "xxxxxxxxxx",
    "other" : "xxxxxxxxxx",
    "imsi" : "xxxxx",
    "imei" : "xxxxx",
    "name" : "Pete",
    "upload" : 13579,
    "download" : 24680,
    "expires" : 1504595262,
    "comment" : "备注"
  }
}
HTTP响应示例
响应 200
{
  "ErrorCode" : 0,
  "ErrorMsg" : "success",
  "Data" : { },
  "Extra" : {
    "version" : "3.x",
    "other_field1" : 1,
    "other_field2" : "xxxxx"
  }
}

4. 定义

4.1. AccessTokenRequest

名称 说明 类型

client_id
必填

样例 : "ikoxxxxxxxxxxxxxxxx"

string

client_type
必填

样例 : "OPEN_PARTNER"

enum (OPEN_PARTNER)

options
必填

样例 : AccessTokenRequestOptions

AccessTokenRequestOptions

request_time
必填

发起请求时的真实时间戳(UNIX_TIMESTAMP)，不能与服务器误差太大
样例 : 1503525563

integer

sign
必填

样例 : "WamFBz2+2EaLTuvcCVg4//ZsicziHoZ1bssV3ezaFfWz+15d92ErR/25kMBgET/FsmobAj9aMfhja9juMMF1riExB6dzDh6lr/mAD6Fnnf/bDcohtYA/tlZl9+uWP/YbDu9T+2KIHR1btd2YvdebPQDRAkwWPjTJJzPhTF5dh7M="

string

4.2. AccessTokenRequestOptions

名称 说明 类型

token_lifetime
必填

期望的 AccessToken 存活时长（单位秒）
样例 : 7200

integer

4.3. AccessTokenRefreshRequest

名称 说明 类型

access_token
可选

样例 : "WzcPH/UdrH+daCgJI5LeXmR8kL8Yy+s5fzdllp5fGLwy2Ur+sVxTvsgXhSaUpPrxPBgmGFGFQ6GYjZgEbXKbx8RHWvLN9aWACK/eBtN1/vIKbkjoi8uX62kaXqSqfTI4AngtEA1Bhni7jiipwiQy6/3yK8Y3soS++ZyS21Ih+W8="

string

client_id
可选

样例 : "ikoxxxxxxxxxxxxxxxx"

string

options
可选

样例 : AccessTokenRequestOptions

AccessTokenRequestOptions

4.4. AccessToken

名称 说明 类型

access_token
可选

AccessToken，用来在对应的授权设备上调用 iKuai Open API
样例 : "WzcPH/UdrH+maCgJI5LeXmR8kL8YD+s5fzdulp5fGLky2Ur+TVxTvsgX7SaUpPrxPBdmGFgFQFGYjZgEbXKbx8RHWvLN97sACK/eBtN1/vIKbkjoieuX62kaXqShfTI4AngtEA1B6nx7jiipwiQy6/3yK8Y3sqS++ZyS21Ih+W8="

string

token_create_time
可选

AccessToken 创建时间戳（以服务器时间为准）
样例 : 1504579937

integer

token_excess_time
可选

AccessToken 剩余时长（单位秒）
样例 : 7200

integer

token_expire_at_server_time
可选

友好格式的 AccessToken 过期时间（以服务器时间为准）
样例 : "2017-09-05 12:52:17"

string

4.5. AccountCreationRequest

名称 说明 类型

param
必填

样例 : AccountCreationReqBody

AccountCreationReqBody

4.6. AccountCreationReqBody

名称 说明 类型

address
可选

住址(最大长度512)
最大长度 : 512
样例 : "xxxxx"

string

auto_mac
必填

自动绑定MAC，0-关闭，1-开启
样例 : 0

integer

auto_vlanid
必填

0-关闭，1-开启 (iK-Router 3.2.0+ 专有)
样例 : 0

integer

bind_ifname
必填

绑定网卡
样例 : "any"

string

bind_vlanid
必填

绑定vlanid(0表示不绑定；支持格式2000/2000.400；范围1~4090)
样例 : "0"

string

cardid
可选

证件号码(最大长度64)
最大长度 : 64
样例 : "xxxxx"

string

comment
可选

备注
最大长度 : 128
样例 : "备注"

string

create_time
必填

创建时间
样例 : 1504591262

integer

download
必填

下载
样例 : 1000

integer

enabled
必填

状态
样例 : "yes"

enum (yes, no)

expires
可选

过期日期
样例 : 1504595262

integer

ip_addr
可选

固定IP
样例 : "10.10.10.10"

string

last_conntime
必填

最后一次连接时间戳，0表示显示为空 (iK-Router 3.2.0+ 专有)
样例 : 1504595262

integer

mac
可选

绑定MAC
样例 : "00:11:22:33:44:55"

string

name
可选

姓名(最大长度128)
最大长度 : 128
样例 : "姓名"

string

packages
必填

套餐类型(对应套餐功能的id, 0表示自定义)
样例 : 0

integer

passwd
必填

密码(最大长度128)
最大长度 : 128
样例 : "xxxxx"

string

phone
可选

手机(最大长度64)
最大长度 : 64
样例 : "138xxxxxxxx"

string

ppptype
必填

拨号类型(any、pppoe、pptp、l2tp、ovpn、web)
样例 : "pppoe"

enum (any, pppoe, pptp, l2tp, ovpn, web)

share
必填

共享数
样例 : 1

integer

start_time
必填

开始时期
样例 : 1504591262

integer

upload
必填

upload
样例 : 0

integer

username
必填

用户名
最大长度 : 128
样例 : "username"

string

4.7. AccountCreationResponse

名称 说明 类型

Data
可选

样例 : EmptyObject

EmptyObject

ErrorCode
可选

样例 : 3000

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : AccountCreationResponseExtra

AccountCreationResponseExtra

4.8. AccountCreationResponseExtra

名称 说明 类型

RowId
可选

添加成功的账号ID (iK-Router 3.x 专有)
样例 : 1

integer

id
可选

添加成功的账号ID (iK-Router 2.x 专有)
样例 : 1

integer

version
可选

返回数据对应路由的版本，该字段对于区分不同版本路由返回的数据格式，进而编写分支逻辑非常有用
样例 : "3.x"

string

4.9. AccountListReqeust

名称 说明 类型

param
必填

样例 : AccountListReqBody

AccountListReqBody

4.10. AccountListReqBody

名称 说明 类型

TYPE
必填

样例 : "data"

string

4.11. AccountListResponse

名称 说明 类型

Data
可选

样例 : [ "Account" ]

< Account > array

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.12. AccountDeleteRequest

名称 说明 类型

param
必填

样例 : AccountDeleteReqBody

AccountDeleteReqBody

4.13. AccountDeleteReqBody

名称 说明 类型

id
必填

id
样例 : 1

integer

4.14. AccountStatusRequest

名称 说明 类型

param
必填

样例 : AccountStatusReqBody

AccountStatusReqBody

4.15. AccountStatusReqBody

名称 说明 类型

id
必填

id
样例 : 1

integer

status
必填

设置目标状态
样例 : "up"

enum (up, down)

4.16. AccountEditRequest

名称 说明 类型

param
必填

样例 : Account

Account

4.17. Account

名称 说明 类型

address
可选

住址(最大长度512)
最大长度 : 512
样例 : "xxxxx"

string

auto_mac
必填

自动绑定MAC，0-关闭，1-开启
样例 : 0

integer

auto_vlanid
必填

0-关闭，1-开启 (iK-Router 3.2.0+ 专有)
样例 : 0

integer

bind_ifname
必填

绑定网卡
样例 : "vlan1"

string

bind_vlanid
必填

绑定vlanid(0表示不绑定；支持格式2000/2000.400；范围1~4090)
样例 : "0"

string

cardid
可选

证件号码(最大长度64)
最大长度 : 64
样例 : "xxxxx"

string

comment
可选

备注
最大长度 : 128
样例 : "备注"

string

create_time
必填

创建时间
样例 : 1504591262

integer

download
必填

下载
样例 : 1000

integer

enabled
必填

状态
样例 : "yes"

enum (yes, no)

expires
可选

过期日期
样例 : 1504595262

integer

id
必填

id
样例 : 1

integer

ip_addr
可选

固定IP
样例 : "10.10.10.10"

string

last_conntime
必填

最后一次连接时间戳，0表示显示为空 (iK-Router 3.2.0+ 专有)
样例 : 1504595262

integer

mac
可选

绑定MAC
样例 : "00:11:22:33:44:55"

string

name
可选

姓名(最大长度128)
最大长度 : 128
样例 : "姓名"

string

packages
必填

套餐类型(对应套餐功能的id, 0表示自定义)
样例 : 0

integer

passwd
必填

密码(最大长度128)
最大长度 : 128
样例 : "xxxxx"

string

phone
可选

手机(最大长度64)
最大长度 : 64
样例 : "138xxxxxxxx"

string

ppptype
必填

拨号类型(any、pppoe、pptp、l2tp、ovpn、web)
样例 : "pppoe"

enum (any, pppoe, pptp, l2tp, ovpn, web)

share
必填

共享数
样例 : 1

integer

start_time
必填

开始时期
样例 : 1504591262

integer

upload
必填

upload
样例 : 0

integer

username
必填

用户名
最大长度 : 128
样例 : "username"

string

4.18. CouponAddingRequest

名称 说明 类型

param
必填

样例 : CouponAddingReqBody

CouponAddingReqBody

4.19. CouponAddingReqBody

名称 说明 类型

comment
必填

备注
最大长度 : 128
样例 : "备注"

string

enabled
必填

状态
样例 : "yes"

enum (yes, no)

expires
必填

过期日期
样例 : 1504595262

integer

timeout
必填

时限（秒）
样例 : 3600

integer

username
必填

优惠券代码
最大长度 : 128
样例 : "coupon_code"

string

4.20. CouponAddingResponse

名称 说明 类型

Data
可选

样例 : EmptyObject

EmptyObject

ErrorCode
可选

样例 : 3000

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : CouponAddingResponseExtra

CouponAddingResponseExtra

4.21. CouponAddingResponseExtra

名称 说明 类型

RowId
可选

添加成功后的ID (iK-Router 3.x 专有)
样例 : 1

integer

version
可选

返回数据对应路由的版本，该字段对于区分不同版本路由返回的数据格式，进而编写分支逻辑非常有用
样例 : "3.x"

string

4.22. CouponDeleteRequest

名称 说明 类型

param
必填

样例 : CouponDeleteReqBody

CouponDeleteReqBody

4.23. CouponDeleteReqBody

名称 说明 类型

id
必填

id
样例 : 1

integer

4.24. CouponEditRequest

名称 说明 类型

param
必填

样例 : CouponEditReqBody

CouponEditReqBody

4.25. CouponEditReqBody

名称 说明 类型

comment
必填

备注
最大长度 : 128
样例 : "备注"

string

enabled
必填

状态
样例 : "yes"

enum (yes, no)

expires
必填

过期日期
样例 : 1504595262

integer

id
必填

优惠券 ID
样例 : 1

integer

timeout
必填

时限（秒）
样例 : 3600

integer

username
必填

优惠券代码
最大长度 : 128
样例 : "coupon_code"

string

4.26. CouponEditResponse

名称 说明 类型

Data
可选

样例 : EmptyObject

EmptyObject

ErrorCode
可选

样例 : 3000

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : CouponEditResponseExtra

CouponEditResponseExtra

4.27. CouponEditResponseExtra

名称 说明 类型

version
可选

返回数据对应路由的版本，该字段对于区分不同版本路由返回的数据格式，进而编写分支逻辑非常有用
样例 : "3.x"

string

4.28. CouponListReqeust

名称 说明 类型

param
必填

样例 : CouponListReqBody

CouponListReqBody

4.29. CouponListReqBody

名称 说明 类型

TYPE
必填

样例 : "data"

string

limit
必填

样例 : 10

integer

skip
必填

样例 : 0

integer

4.30. CouponListResponse

名称 说明 类型

Data
可选

样例 : [ "Coupon" ]

< Coupon > array

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.31. Coupon

名称 说明 类型

comment
可选

备注
最大长度 : 128
样例 : "备注"

string

enabled
可选

状态
样例 : "yes"

enum (yes, no)

expires
可选

过期日期
样例 : 1504595262

integer

id
可选

优惠券 ID
样例 : 1

integer

timeout
可选

时限（秒）
样例 : 3600

integer

used
可选

是否使用过（1：是，0：否）
样例 : 1

integer

username
可选

优惠券代码
最大长度 : 128
样例 : "coupon_code"

string

4.32. CustomAuthInfoRequest

名称 说明 类型

param
必填

样例 : CustomAuthInfoReqBody

CustomAuthInfoReqBody

4.33. CustomAuthInfoReqBody

名称 说明 类型

adsl_id
可选

宽带账号(认证类型，单选)
最大长度 : 32
样例 : ""

string

card_id
可选

身份证(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

comment
可选

备注
最大长度 : 255
样例 : "备注"

string

download
可选

下行限速
样例 : 24680

integer (int32)

eep_id
可选

港澳通行证(认证类型，单选)
最大长度 : 32
样例 : ""

string

expires
可选

过期时间戳
样例 : 1504595262

integer

imei
可选

IMEI
最大长度 : 64
样例 : "xxxxx"

string

imsi
可选

IMSI
最大长度 : 64
样例 : "xxxxx"

string

mobile
可选

手机号(认证类型，单选)
最大长度 : 13
样例 : ""

string

name
可选

优惠券代码
最大长度 : 16
样例 : "Pete"

string

other
可选

其他类型(认证类型，单选)
最大长度 : 32
样例 : ""

string

passport
可选

护照号码(认证类型，单选)
最大长度 : 32
样例 : ""

string

room_number
可选

房间号(认证类型，单选)
最大长度 : 16
样例 : ""

string

upload
可选

上行限速
样例 : 13579

integer (int32)

user_id
必填

开发者自行定义的 user_id，该字段不参与认证信息鉴别，仅供开发者鉴别自己的用户标识用途
最大长度 : 64
样例 : "user_identifer"

string

4.34. CustomAuthInfoResponse

名称 说明 类型

Data
可选

样例 : [ "CustomAuthInfoUsername" ]

< CustomAuthInfoUsername > array

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.35. CustomAuthInfoUsername

名称 说明 类型

username
可选

用户的唯一标识（路由器里的上网用户的 username），踢用户下线等操作需要此键值
样例 : "b57d72a1ec69235ffbb3cdf007eae3c6"

string

4.36. CustomAuthInfoUser

名称 说明 类型

adsl_id
可选

宽带账号(认证类型，单选)
最大长度 : 32
样例 : ""

string

card_id
可选

身份证(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

comment
可选

备注
最大长度 : 255
样例 : "备注"

string

created_at
可选

创建时间
样例 : "2018-02-20 01:02:03"

string

download
可选

下行限速
样例 : 24680

integer (int32)

eep_id
可选

港澳通行证(认证类型，单选)
最大长度 : 32
样例 : ""

string

expires
可选

过期时间戳
样例 : 1504595262

integer

imei
可选

IMEI
最大长度 : 64
样例 : "xxxxx"

string

imsi
可选

IMSI
最大长度 : 64
样例 : "xxxxx"

string

mobile
可选

手机号(认证类型，单选)
最大长度 : 13
样例 : ""

string

name
可选

优惠券代码
最大长度 : 16
样例 : "Pete"

string

other
可选

其他类型(认证类型，单选)
最大长度 : 32
样例 : ""

string

passport
可选

护照号码(认证类型，单选)
最大长度 : 32
样例 : ""

string

room_number
可选

房间号(认证类型，单选)
最大长度 : 16
样例 : ""

string

updated_at
可选

最后更新时间
样例 : "2018-02-21 04:05:06"

string

upload
可选

上行限速
样例 : 13579

integer (int32)

username
可选

认真用户的唯一标识，踢用户下线时需要此键值
最大长度 : 64
样例 : "e57d72e1ec69d35ffbb3cd2f0aeae3c6"

string

4.37. CustomAuthUserListResponse

名称 说明 类型

Data
可选

样例 : [ "CustomAuthInfoUser" ]

< CustomAuthInfoUser > array

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.38. CustomAuthUserUpdateRequest

名称 说明 类型

param
必填

样例 : CustomAuthUserUpdateReqBody

CustomAuthUserUpdateReqBody

4.39. CustomAuthUserUpdateReqBody

名称 说明 类型

adsl_id
可选

宽带账号(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

card_id
可选

身份证(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

comment
可选

备注
最大长度 : 255
样例 : "备注"

string

download
可选

下行限速
样例 : 24680

integer (int32)

eep_id
可选

港澳通行证(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

expires
可选

过期时间戳
样例 : 1504595262

integer

imei
可选

IMEI
最大长度 : 64
样例 : "xxxxx"

string

imsi
可选

IMSI
最大长度 : 64
样例 : "xxxxx"

string

mobile
可选

手机号(认证类型，单选)
最大长度 : 13
样例 : "xxxxxxxxxx"

string

name
可选

优惠券代码
最大长度 : 16
样例 : "Pete"

string

other
可选

其他类型(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

passport
可选

护照号码(认证类型，单选)
最大长度 : 32
样例 : "xxxxxxxxxx"

string

room_number
可选

房间号(认证类型，单选)
最大长度 : 16
样例 : "xxxxxxxxxx"

string

upload
可选

上行限速
样例 : 13579

integer (int32)

username
必填

自定义认证的唯一标识，与路由器中的 username 对应
最大长度 : 64
样例 : "b57d72a1ec69235ffbb3cdf007eae3c6"

string

4.40. CustomAuthUserDeleteRequest

名称 说明 类型

param
必填

样例 : CustomAuthUserDeleteReqBody

CustomAuthUserDeleteReqBody

4.41. CustomAuthUserDeleteReqBody

名称 说明 类型

username
必填

自定义认证的唯一标识，与路由器中的 username 对应
最大长度 : 64
样例 : "b57d72a1ec69235ffbb3cdf007eae3c6"

string

4.42. DeviceListResponse

名称 说明 类型

Data
可选

样例 : [ "Device" ]

< Device > array

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.43. Device

名称 说明 类型

dev_id
可选

设备ID
样例 : "xxxxx"

string

dev_remark
可选

设备友好名称
样例 : "xxxxx"

string

open_apis
可选

平台合作商，在本设备上可以调用的 api_id 列表
样例 : [ "1", "2", "3", "7", "8", "10", "12" ]

< string > array

owner_mobile
可选

设备所有者手机号
样例 : "xxxxx"

string

owner_qq
可选

设备所有者QQ号
样例 : "xxxxx"

string

4.44. FindAccountByUsername

名称 说明 类型

param
必填

样例 : FindAccountByUsernameReqBody

FindAccountByUsernameReqBody

4.45. FindAccountByUsernameReqBody

名称 说明 类型

username
必填

账号名
样例 : "username"

string

4.46. OnlineUserKickRequest

名称 说明 类型

param
必填

样例 : OnlineUserKickReqBody

OnlineUserKickReqBody

4.47. OnlineUserKickReqBody

名称 说明 类型

mac
可选

使用 mac 地址 下线用户 (绝大多数情况下的通用方式)
样例 : "00:11:22:33:44:55"

string

username
可选

使用 username 下线用户 (仅 iK-Router 3.1.6 以上版本)
样例 : "OldJack"

string

4.48. OnlineUserListRequest

名称 说明 类型

param
必填

样例 : OnlineUserListReqBody

OnlineUserListReqBody

4.49. OnlineUserListReqBody

名称 说明 类型

TYPE
必填

样例 : "data"

string

limit
必填

获取多少条
样例 : 10

integer

skip
必填

跳过多少条
样例 : 0

integer

4.50. OnlineUser

名称 说明 类型

auth_time
可选

认证时间(时间戳) (iK-Router 3.x 专有)
样例 : "xxxxx"

string

comment
可选

备注 (iK-Router 3.x 专有)
样例 : "comment"

string

connect
可选

连接数 (iK-Router 2.x 专有)
样例 : 0

integer

connect_time
可选

连接时长 (iK-Router 2.x 专有)
样例 : "xxxxx"

string

down
可选

下行流量 (iK-Router 2.x 专有)
样例 : 0

integer

download
可选

限速下行 (iK-Router 3.x 专有)
样例 : "10000"

string

expires
可选

过期时间(时间戳,0表示不限) (iK-Router 3.x 专有)
样例 : "0"

string

id
可选

id (iK-Router 3.x 专有)
样例 : "10"

string

interface
可选

接口名称 (iK-Router 3.x 专有)
样例 : "eth0"

string

ip
可选

IP地址 (iK-Router 2.x 专有)
样例 : "1.2.3.4"

string

ip_addr
可选

客户机IP (iK-Router 3.x 专有)
样例 : "10.11.12.13"

string

ip_addr_int
可选

客户机IP整数 (iK-Router 3.x 专有)
样例 : "168496141"

string

mac
可选

MAC地址
样例 : "00:11:22:33:44:55"

string

name
可选

姓名 (iK-Router 3.x 专有)
样例 : "realname"

string

phone
可选

手机号 (iK-Router 3.x 专有)
样例 : "138xxxxxxxx"

string

pppdev
可选

pppd设备 (iK-Router 3.x 专有)
样例 : "xxxxx"

string

ppptype
可选

拨号类型(any、pppoe、pptp、l2tp、ovpn、web) (iK-Router 3.x 专有)
样例 : "pppoe"

enum (any, pppoe, pptp, l2tp, ovpn, web)

session
可选

SESSION (iK-Router 3.x 专有)
样例 : "xxxxx"

string

total_down
可选

累计下行流量 (iK-Router 2.x 专有)
样例 : "xxxxx"

string

total_up
可选

累计上行流量 (iK-Router 2.x 专有)
样例 : "xxxxx"

string

type
可选

认证方式 (iK-Router 2.x 专有) 0-未认证, 1-用户密码, 2-优惠券, 3-固定密码, 4-手机, 5-腾讯QQ, 6-微博, 7-无密码, 8-微信, 9-支付宝, 10-手机管家, 11-免费试用, 12-微信连wifi
样例 : 0

integer

up
可选

上行流量 (iK-Router 2.x 专有)
样例 : 0

integer

upload
可选

限速上行 (iK-Router 3.x 专有)
样例 : "1000"

string

username
可选

用户名 (iK-Router 3.x 专有)
样例 : "xxxxx"

string

webid
可选

WEB认证类型ID(只对web认证有效，如微信、一键认证……) (iK-Router 3.x 专有)
样例 : "1"

string

4.51. OnlineUserListResponse

名称 说明 类型

Data
可选

样例 : [ "OnlineUser" ]

< OnlineUser > array

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.52. RouterBasicResponse

名称 说明 类型

Data
可选

样例 : RouterBasic

RouterBasic

ErrorCode
可选

样例 : 3000

integer

ErrorMsg
可选

样例 : "success"

string

4.53. RouterBasic

名称 说明 类型

ap_count
可选

AP数量
样例 : "0"

string

down_speed
可选

下行速率
样例 : "10632"

string

enterprise
可选

企业版 (iK-Router 3.x 专有)
样例 : ""

string

firmware
可选

固件
样例 : "IK-RouterOS"

string

gwid
可选

gwid
样例 : "xxxxx"

string

libver
可选

协议库版本
样例 : "1.9.157"

string

mac
可选

mac地址
样例 : "00:11:22:33:44:55"

string

name
可选

友好名称
样例 : "iKuai-Router"

string

online
可选

在线数
样例 : "12"

string

partner
可选

partner
样例 : ""

string

reflexive_address
可选

ip地址
样例 : "100.101.102.103"

string

router_ver
可选

路由系统版本
样例 : "2.6.7"

string

sysuptime
可选

系统上线时长
样例 : "173555"

string

total_down
可选

总下载量
样例 : "5233241489"

string

total_up
可选

总上传量
样例 : "1220344280"

string

up_speed
可选

上行速率
样例 : "11954"

string

4.54. WhiteListRequest

名称 说明 类型

param
必填

样例 : WhiteListReqBody

WhiteListReqBody

4.55. WhiteListReqBody

名称 说明 类型

noauth_mac
必填

免认证mac列表
样例 : "00:11:22:33:44:55,66:77:88:99:AA:BB"

string

whiteip
必填

ip网址白名单列表
样例 : "8.8.8.8"

string

whitelist
必填

http网址白名单列表
样例 : "baidu.com"

string

whitelist_https
必填

https网址白名单列表
样例 : "alipay.com"

string

4.56. SimpleSuccess

名称 说明 类型

Data
可选

样例 : EmptyObject

EmptyObject

ErrorCode
可选

样例 : 0

integer

ErrorMsg
可选

样例 : "success"

string

Extra
可选

样例 : ExtraObject

ExtraObject

4.57. ExtraObject

名称 说明 类型

other_field1
可选

根据调用的 API，返回不同的附加信息
样例 : 1

integer

other_field2
可选

根据调用的 API，返回不同的附加信息
样例 : "xxxxx"

string

version
可选

返回数据对应路由的版本，该字段对于区分不同版本路由返回的数据格式，进而编写分支逻辑非常有用
样例 : "3.x"

string

4.58. EmptyObject

类型 : object

5. 错误代码与消息

5.1. 服务器返回消息结构说明

{
  "ErrorCode": 30000,
  "ErrorMsg": "Success",
  "Data": [ {
      "id": 1,
      "hostname": "iKuai Router Awesome",
      "language": 2,
      "switch_dpi": 1,
      "switch_nat": 1,
      "switch_ntp": 1,
      "time_zone": 8
    } ],
  "Extra": {
    "version": "3.x"
  }
}
键名 值 备注

ErrorCode

错误代码

整数

ErrorMsg

错误消息

字符串

Data

返回数据

对象或数组

Extra

数据附加信息

API 调用结果的附加信息，如：该次调用返回数据的版本[5]，新建一条记录后返回的记录 ID

5.2. API 外部错误

此类错误发生在路由控制 API 调用之前
包括：HTTP 常见错误，API 认证错误，API 授权错误，API 数据格式错误，等……

5.2.1. HTTP 错误

代码 消息 说明

404

Not Found

错误的请求方法或路径

429

Too Many Attempts

服务器接口调用频率超过阈值(N次/分钟)，服务器响应头中包含以下信息
x-ratelimit-limit，x-ratelimit-remaining 获取当前分钟剩余次数
一旦超限，检查：x-ratelimit-reset，retry-after 获取重置时间

400000

Bad request.

检查 HTTP 请求头的 Content-Type

5.2.2. API 认证错误

代码 消息 说明

400001

Unauthorized.

API 认证失败，检查 HTTP 请求头的 IK-Access-Token；AccessToken 过期

400002

AccessToken not found or expire.

AccessToken 无效或过期

400015

AccessToken not found.

刷新 AccessToken 时，没有提供有效的旧 Token

400016

AccessToken does not belongs to the client.

AccessToken 的所有者与请求中的 client_id 不匹配

5.2.3. API 授权与提交参数错误

代码 消息 说明

400003

api not available.

请求的 Api 状态为：已停用

400004

api not found.

没有此 Api

400005

the encryption time does not match the request time.

解密后的时间戳必须与请求体中的 request_time 时间戳一致

400006

signature verification failed.

iKuai Open 平台著名的 400006，rsa 解密错误，检查 rsa 加密代码

400007

too much differences between request_time and server time.

请求体中的 request_time 时间戳与当前真实的服务器时间戳误差不能太大，
重要：确保调用发生在真实时间

400008

open_id not found.

open_id 在平台中无法查询到，检查 open_id

400009

open_id not available.

该 open_id 处于停用状态

400010

no access to the device.

指定设备对该 open_id 未授权

400011

invalid parameters.

请求参数有不合法的值，根据不同 API 提示出错参数

400012

device authorization is temporarily disabled.

设备与业务已关联，但状态为停用

400013

partner business did not pass.

第三方业务审核中，或明确拒绝

400014

the device is authorized, but not the corresponding api.

设备对业务已授权，但业务中不包含相应的 Api

5.2.4. 其他错误

代码 消息 说明

400017

unknown device version.

设备版本未知，不能在其上调用任何 Api

400018

api definition not found.

罕见的服务器内部错误

500001

known server error.

未知的服务器内部错误

5.3. API 内部错误

此类错误发生在路由控制 API 调用之后
包括：添加重复记录，设备离线，等……

5.3.1. 爱快路由 2.x 版本专有

ErrorCode 为 0 表示成功，其他都表示失败
代码 消息 说明

1400

invalid request

非法请求

1404

resource not found

资源没有发现或者路由器不在线

1409

resource occupied

同一路由器上有其它操作正在执行

1500

internal error

内部错误

1501

unsupported operation

指定的资源或者操作未实现

1502

unable to reach resource

无法与路由器建立连接

5.3.2. 爱快路由 3.x 版本专有

ErrorCode 能够整除 10000 表示成功，其他都表示失败
10000 成功
20000 成功
30000 成功
代码 说明

10001

验证账号密码失败

10002

账号被禁用

10003

无效的IP

10004

读取授权失败

10005

执行授权失败

10006

Post 内容太长

10007

JSON 格式错误

10008

语法错误

10009

没有找到对应功能

30001

执行失败

30002

命令错误
1. 初版 Open API 的版本号涵盖了 v1.x 和 v2.x，而最新版本的 API 与爱快最新架构的 3.x 系列路由同步开发，因此沿用相同的版本号！
2. 由于爱快全新的 3.x 系列路由器架构升级变化颇大，底层接口进行彻底重构，因此完全兼容旧版本 Open API 难以实现，但官方依然努力使得变化部分对接口调用者的影响降低到尽量小。
3. 注意：旧版 API 无法在 3.x 及其后版本的爱快路由器上调用 Open API
4. postman 官网还提供多种平台的独立程序下载，但独立程序体积较大，且对某些 js 代码兼容性不及 chrome 插件
5. 路由器系统版本、OpenAPI 版本