物联网智慧云平台能力调用参考文档
文档版本 V1.0.0
版本说明
| 版本号 |
更新时间 |
更新人 |
主要内容或重大修改 |
| v1.0.0 |
2021-05-27 |
|
新增接口：
查询卡片状态
查询卡片用量
查询所属群组信息
查询规定群组数据
停复机 |
错误码
| 错误码 |
说明 |
| 0 |
正确 |
| 500 |
内部错误，请联系管理员 |
| 11000 |
请求参数错误，请参考能力调用文档 |
| 12004 |
transId 或 appid 或 token 鉴权失败 |
| 12009 |
卡号鉴权失败，不属于此用户 |
| 12010 |
卡号鉴权失败，不存在本系统 |
| 12021 |
token 过期，重新获取的 token 会立马更新 |
| 443 |
客户端错误: 无效的appid |
| 12022 |
appid 或 password 鉴权不通过 |
| 12034 |
群组 ID 不属于本企业 |
| 446 |
客户端错误: 未设置时间戳 |
| 12089 |
该卡片不是待激活、已激活、已停机，无法进行操作 |
| 12098 |
当前停机原因不符合自主发起复机操作要求,只有主动申请停机的 才允许自主复机 |
| 12099 |
卡片主套餐超出有效期，无法复机 |
| 12100 |
卡片所属套餐的用量已达量 |
| 12010 |
卡片所属流量池可用量已达量 |
| 19010 |
其他错误，联系管理员 |
1. 认证接口
1.1 认证服务接口
token（令牌）获取接口
1.1.1 认证服务接口
服务地址 :
http://sz.cotonda.com/iotManage/api/getToken
业务描述：
集团客户从自服务平台获取 appid 和 password 进行认证服务校验，成功则返回鉴权标识 token。该接口 用于用户获取 token，客户和 OneLink 能力开放平台同 时缓存该 token，token 过期则平台返回错误 码，用户重新调用 token 获取接口获 取 token，token 过期时间为 2 小时。OneLink 能力开放平台业 务接口需要对 token 校验，校验通过则完成身份验证。
请求参数说明
| 参数 |
是否必须 |
类型 |
含义 |
| appid |
是 |
String |
应用编码，第三方应用唯一标识。由物联集 团客户向科通达提出 API 接入申请，科通达 物联网全网管理员在 物联云网智慧云平台 能力开放 平台上分配并展示给集团户， appid 样例：202105242146195403 |
| password |
是 |
String |
API 接入秘钥，由科通达物联网提供，集团 客户从自服务平台获取（物联云网智慧云 平 台上 API 使用说明下），token 过期时间暂 定为 2 小时。 |
| timeStamp |
是 |
String |
时间戳 yyyyMMddHHmmss+10 个随机数 |
URL :
http://sz.cotonda.com/iotManage/api/getToken?appid=xxxx&password=xxxx&timeStamp=xxxx
返回参数说明
| 参数 |
是否必须 |
默认值 |
含义 |
| success |
是 |
boolean |
请求是否成功。true - 成功 false - 失败 |
| errorCode |
是 |
int |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
返回结果集（errorCode 为“0”时，data 包 含正确的结果数据；errorCode 为“非 0”时， data 为空） 此处为 token 的值，需要保存起 来，一小时后过期 |
返回报文举例
成功：
{
"success": true，
"errorCode": 0，
"errorMsg": "",
"data": "token": "d362fc0cfe91e3b1263abec0b44869d8065f3b8cbe974b8805bfa7b4435b83da"
}
失败： {
"success": flase，
"errorMsg":"PASSWORD 鉴权不通过",
"data":{},
"errorCode":12022
}
2. 物联卡管理类
2.1 复机
服务地址：
http://sz.cotonda.com/iotManage/api/activationCard
业务描述：
集团客户可以通过卡号 iccid 变更集团归属物联卡的状态（同一卡号 3 分钟内 不能通过此类接口重复办理业务）。
请求参数说明：
| 参数 |
是否必填 |
类型 |
含义 |
| transId |
是 |
String |
事务编码，由物联卡集团客户按照相应规则自 主生成，生成规则：yyyyMMddHHmmss+APPID+ 八 位 随 机 数 ， appid 样 例 ： 2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通过指定接口获取。 |
| iccid |
是 |
String |
集成电路卡识别码，IC 卡的唯一识别号码，共 有 20 位字符组成，举例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/activationCard?transId=xxxx&token=xxxx&icci d=xxxx
返回参数说明：
| 参数 |
是否必须 |
默认值 |
含义 |
| suceess |
是 |
boolean |
请求是否成功。true - 成功 false - 失败 |
| errorCode |
是 |
int |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
返回结果集（errorCode 为“0”时，data 包 含正确的结果数据；errorCode 为“非 0”时， data 为空） 此处为 iccid 的值 |
返回报文举例
成功：
{
"success": true，
"errorCode": 0，
"errorMsg": "",
"data": "898600D6991330004146"
}
失败： {
"success": flase，
"errorMsg":"TOKEN 不存在或已过期，请重新获取",
"data":{},
"errorCode":12022
}
2.2 停机
服务地址：
http://sz.cotonda.com/iotManage/api/stopCard
业务描述：
集团客户可以通过卡号 iccid 变更集团归属物联卡的状态
请求参数说明:
| 参数 |
是否必须 |
类型 |
含义 |
| transId |
是 |
String |
事务编码，由物联卡集团客户按照相应规则自 主生成，生成规则：yyyyMMddHHmmss+APPID+ 八 位 随 机 数 ， appid 样 例 ： 2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通过指定接口获取。 |
| iccid |
是 |
String |
集成电路卡识别码，IC 卡的唯一识别号码，共 有 20 位字符组成，举例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/stopCard?transId=xxxx&token=xxxx&iccid=xxxx
返回参数说明：
| 参数 |
是否必须 |
默认值 |
含义 |
| suceess |
是 |
boolean |
请求是否成功。true - 成功 false - 失败 |
| errorCode |
是 |
int |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
返回结果集（errorCode 为“0”时，data 包 含正确的结果数据；errorCode 为“非 0”时， data 为空） 此处为 iccid 的值 |
返回报文举例
成功：
{
"success": true，
"errorCode": 0，
"errorMsg": "",
"data": "898600D6991330004146"
}
失败： {
"success": flase，
"errorMsg":"TOKEN 不存在或已过期，请重新获取",
"data":{},
"errorCode":12022
}
3. 物联卡查询类
3.1 查询卡状态
服务地址：
http://sz.cotonda.com/iotManage/api/getCardStatus
业务描述：
集团客户可以通过卡号 iccid 查询集团归属物联卡的状态
请求参数说明：
| 参数 |
是否必须 |
类型 |
含义 |
| transId |
是 |
String |
事务编码，由物联卡集团客户按照相应规则自 主生成，生成规则：yyyyMMddHHmmss+APPID+ 八 位 随 机 数 ， appid 样 例 ： 2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通过指定接口获取。 |
| iccid |
是 |
String |
集成电路卡识别码，IC 卡的唯一识别号码，共 有 20 位字符组成，举例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/getCardStatus?transId=xxxx&token=xxxx&icci d=xxxx
返回参数说明：
| 参数 |
是否必须 |
默认值 |
父级 |
含义 |
| suceess |
是 |
boolean |
无 |
请求是否成功。true - 成功 false - 失 败 |
| errorCode |
是 |
int |
无 |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
无 |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
无 |
返回结果集（errorCode 为“0”时，data 包含正确的结果数据；errorCode 为“非 0”时， data 为空） |
| activateTime |
是 |
String |
data |
第一次激活时间 |
| status |
是 |
int |
data |
卡片状态（1：待激活 2：已激活 3：已停机 4：已失效 5：测试卡 6：已销户 7：库存 ） |
| iccid |
是 |
String |
data |
iccid |
返回报文举例
成功：
{
"data": {
"activateTime": "2020-10-24 11:37", 第一次激活的时间
"cardStatus": 2,
"iccId": "898600D6991330004146"
},
"errorCode": 0,
"errorMsg": "",
"success": true
}
失败： {
"success": flase，
"errorMsg":"TOKEN 不存在或已过期，请重新获取",
"data":{},
"errorCode":12022
}
3.2 查询卡用量
服务地址：
http://sz.cotonda.com/iotManage/api/getCardDosage
业务描述：
集团客户可以通过卡号 iccid 查询集团归属物联卡的状态
请求参数说明:
| 参数 |
是否必须 |
类型 |
含义 |
| transId |
是 |
String |
事务编码，由物联卡集团客户按照相应规则自 主生成，生成规则：yyyyMMddHHmmss+APPID+ 八 位 随 机 数 ， appid 样 例 ：2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通过指定接口获取。 |
| iccid |
是 |
String |
集成电路卡识别码，IC 卡的唯一识别号码，共 有 20 位字符组成，举例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/getCardStatus?transId=xxxx&token=xxxx&icci d=xxxx
返回参数说明：
| 参数 |
是否必须 |
默认值 |
父级 |
含义 |
| suceess |
是 |
boolean |
无 |
请求是否成功。true - 成功 false - 失 败 |
| errorCode |
是 |
int |
无 |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
无 |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
无 |
返回结果集（errorCode 为“0”时，data 包含正确的结果数据；errorCode 为“非 0”时， data 为空） |
| updateTime |
是 |
String |
data |
最近更新时间 |
| dosage |
是 |
double |
data |
卡片用量 |
| iccid |
是 |
String |
data |
iccid |
返回报文举例
成功：
{
"data": {
"dosage": 0,
"updateTime": "2021-05-11 18:15"
},
"errorCode": 0,
"errorMsg": "卡片状态为 1",
"success": true
}
失败：
{
"success": flase，
"errorMsg":"TOKEN 不存在或已过期，请重新获取",
"data":{},
"errorCode":12022
}
3.3 查询群组信息
服务地址：
http://sz.cotonda.com/iotManage/api/getCardDosage
业务描述：
集团客户可以通过卡号 iccid 查询集团归属物联卡的状态
请求参数说明:
| 参数 |
是否必须 |
类型 |
含义 |
| transId |
是 |
String |
事务编码，由物联卡集团客户按照相应规则自 主生成，生成规则：yyyyMMddHHmmss+APPID+ 八 位 随 机 数 ， appid 样 例 ：2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通过指定接口获取。 |
URL:
:http://sz.cotonda.com/iotManage/api/queryGroupInfo?transId=xxxx&token=xxxx
返回参数说明：
| 参数 |
是否必须 |
默认值 |
父级 |
含义 |
| suceess |
是 |
boolean |
无 |
请求是否成功。true - 成功 false - 失 败 |
| errorCode |
是 |
int |
无 |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
无 |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
无 |
返回结果集（errorCode 为“0”时，data 包含正确的结果数据；errorCode 为“非 0”时， data 为空） |
| name |
是 |
String |
data |
群组名称 |
| flowPoolId |
是 |
String |
data |
群组 id |
返回报文举例
成功：
{
"data": [
{
"name": "流量池 30G",
"flowPoolId": "splitNum00014508"
}
],
"errorCode": 0,
"errorMsg": "",
"success": true
}
失败：
{
"success": flase，
"errorMsg":"TOKEN 不存在或已过期，请重新获取",
"data":{},
"errorCode":12022
}
3.4 查询群组信息
服务地址：
http://sz.cotonda.com/iotManage/api/getCardDosage
业务描述：
集团客户可以通过卡号 iccid 查询集团归属物联卡的状态
请求参数说明:
| 参数 |
是否必须 |
类型 |
含义 |
| transId |
是 |
String |
事务编码，由物联卡集团客户按照相应规则自 主生成，生成规则：yyyyMMddHHmmss+APPID+ 八 位 随 机 数 ， appid 样 例 ：2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通过指定接口获取。 |
| flowPoolId |
是 |
String |
群组 id |
URL:
http://sz.cotonda.com/iotManage/api/stopCard?queryGroupData=xxxx&token=xxxx& flowPoolId=xxxx
返回参数说明：
| 参数 |
是否必须 |
默认值 |
父级 |
含义 |
| suceess |
是 |
boolean |
无 |
请求是否成功。true - 成功 false - 失 败 |
| errorCode |
是 |
int |
无 |
错误码。0-成功 非 0-失败 |
| errorMsg |
是 |
String |
无 |
时间戳 yyyyMMddHHmmss+10 个随机数 |
| data |
是 |
Object |
无 |
返回结果集（errorCode 为“0”时，data 包含正确的结果数据；errorCode 为“非 0”时， data 为空） |
| name |
是 |
String |
data |
群组名称 |
| flowPoolId |
是 |
String |
data |
群组 id |
| quantity |
是 |
int |
data |
总卡数 |
| activateNum |
是 |
int |
data |
激活卡数 |
| stopNum |
是 |
int |
data |
停机卡数 |
| totalFlow |
是 |
double |
data |
可用总流量 |
| dosage |
是 |
double |
data |
已用量 |
| surplus |
是 |
double |
data |
剩余量 |
| numberSements |
是 |
List |
data |
包含流量池的所属号段 |
| startIccId |
是 |
String |
numberSements |
某一号段开始的 iccId |
| endIccId |
是 |
String |
numberSements |
某一号段结束的 iccId |
返回报文举例
成功：
{
"data": {
"activateNum": 13,
"dosage": 503,
"flowPoolId": "splitNum00004508",
"name": "流量池 30G",
"numberSegments": [
{
"endIccId": "898604801920C0200004",
"startIccId": "898604801920C0200000"
},
{ "endIccId": "898604801920C0200010",
"startIccId": "898604801920C0200005"
},
{
"endIccId": "898604801920C0200024",
"startIccId": "898604801920C0200013"
},
{
"endIccId": "898604801920C0200012",
"startIccId": "898604801920C0200011"
}
],
"quantity": 25,
"stopNum": 4,
"surplus": 7,
"totalFlow": 510
},
"errorCode": 0,
"errorMsg": "",
"success": true
}
失败：
{
"success": flase，
"errorMsg":"TOKEN 不存在或已过期，请重新获取",
"data":{},
"errorCode":12022
}