物聯(lián)網(wǎng)智慧云平臺(tái)能力調(diào)用參考文檔
文檔版本 V1.0.0
版本說(shuō)明
| 版本號(hào) |
更新時(shí)間 |
更新人 |
主要內(nèi)容或重大修改 |
| v1.0.0 |
2021-05-27 |
|
新增接口：
查詢(xún)卡片狀態(tài)
查詢(xún)卡片用量
查詢(xún)所屬群組信息
查詢(xún)規(guī)定群組數(shù)據(jù)
停復(fù)機(jī) |
錯(cuò)誤碼
| 錯(cuò)誤碼 |
說(shuō)明 |
| 0 |
正確 |
| 500 |
內(nèi)部錯(cuò)誤，請(qǐng)聯(lián)系管理員 |
| 11000 |
請(qǐng)求參數(shù)錯(cuò)誤，請(qǐng)參考能力調(diào)用文檔 |
| 12004 |
transId 或 appid 或 token 鑒權(quán)失敗 |
| 12009 |
卡號(hào)鑒權(quán)失敗，不屬于此用戶(hù) |
| 12010 |
卡號(hào)鑒權(quán)失敗，不存在本系統(tǒng) |
| 12021 |
token 過(guò)期，重新獲取的 token 會(huì)立馬更新 |
| 443 |
客戶(hù)端錯(cuò)誤: 無(wú)效的appid |
| 12022 |
appid 或 password 鑒權(quán)不通過(guò) |
| 12034 |
群組 ID 不屬于本企業(yè) |
| 446 |
客戶(hù)端錯(cuò)誤: 未設(shè)置時(shí)間戳 |
| 12089 |
該卡片不是待激活、已激活、已停機(jī)，無(wú)法進(jìn)行操作 |
| 12098 |
當(dāng)前停機(jī)原因不符合自主發(fā)起復(fù)機(jī)操作要求,只有主動(dòng)申請(qǐng)停機(jī)的 才允許自主復(fù)機(jī) |
| 12099 |
卡片主套餐超出有效期，無(wú)法復(fù)機(jī) |
| 12100 |
卡片所屬套餐的用量已達(dá)量 |
| 12010 |
卡片所屬流量池可用量已達(dá)量 |
| 19010 |
其他錯(cuò)誤，聯(lián)系管理員 |
1. 認(rèn)證接口
1.1 認(rèn)證服務(wù)接口
token（令牌）獲取接口
1.1.1 認(rèn)證服務(wù)接口
服務(wù)地址 :
http://sz.cotonda.com/iotManage/api/getToken
業(yè)務(wù)描述：
集團(tuán)客戶(hù)從自服務(wù)平臺(tái)獲取 appid 和 password 進(jìn)行認(rèn)證服務(wù)校驗(yàn)，成功則返回鑒權(quán)標(biāo)識(shí) token。該接口 用于用戶(hù)獲取 token，客戶(hù)和 OneLink 能力開(kāi)放平臺(tái)同 時(shí)緩存該 token，token 過(guò)期則平臺(tái)返回錯(cuò)誤 碼，用戶(hù)重新調(diào)用 token 獲取接口獲 取 token，token 過(guò)期時(shí)間為 2 小時(shí)。OneLink 能力開(kāi)放平臺(tái)業(yè) 務(wù)接口需要對(duì) token 校驗(yàn)，校驗(yàn)通過(guò)則完成身份驗(yàn)證。
請(qǐng)求參數(shù)說(shuō)明
| 參數(shù) |
是否必須 |
類(lèi)型 |
含義 |
| appid |
是 |
String |
應(yīng)用編碼，第三方應(yīng)用唯一標(biāo)識(shí)。由物聯(lián)集 團(tuán)客戶(hù)向科通達(dá)提出 API 接入申請(qǐng)，科通達(dá) 物聯(lián)網(wǎng)全網(wǎng)管理員在 物聯(lián)云網(wǎng)智慧云平臺(tái) 能力開(kāi)放 平臺(tái)上分配并展示給集團(tuán)戶(hù)， appid 樣例：202105242146195403 |
| password |
是 |
String |
API 接入秘鑰，由科通達(dá)物聯(lián)網(wǎng)提供，集團(tuán) 客戶(hù)從自服務(wù)平臺(tái)獲?。ㄎ锫?lián)云網(wǎng)智慧云 平 臺(tái)上 API 使用說(shuō)明下），token 過(guò)期時(shí)間暫 定為 2 小時(shí)。 |
| timeStamp |
是 |
String |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
URL :
http://sz.cotonda.com/iotManage/api/getToken?appid=xxxx&password=xxxx&timeStamp=xxxx
返回參數(shù)說(shuō)明
| 參數(shù) |
是否必須 |
默認(rèn)值 |
含義 |
| success |
是 |
boolean |
請(qǐng)求是否成功。true - 成功 false - 失敗 |
| errorCode |
是 |
int |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包 含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） 此處為 token 的值，需要保存起 來(lái)，一小時(shí)后過(guò)期 |
返回報(bào)文舉例
成功：
{
"success": true，
"errorCode": 0，
"errorMsg": "",
"data": "token": "d362fc0cfe91e3b1263abec0b44869d8065f3b8cbe974b8805bfa7b4435b83da"
}
失?。?{
"success": flase，
"errorMsg":"PASSWORD 鑒權(quán)不通過(guò)",
"data":{},
"errorCode":12022
}
2. 物聯(lián)卡管理類(lèi)
2.1 復(fù)機(jī)
服務(wù)地址：
http://sz.cotonda.com/iotManage/api/activationCard
業(yè)務(wù)描述：
集團(tuán)客戶(hù)可以通過(guò)卡號(hào) iccid 變更集團(tuán)歸屬物聯(lián)卡的狀態(tài)（同一卡號(hào) 3 分鐘內(nèi) 不能通過(guò)此類(lèi)接口重復(fù)辦理業(yè)務(wù)）。
請(qǐng)求參數(shù)說(shuō)明：
| 參數(shù) |
是否必填 |
類(lèi)型 |
含義 |
| transId |
是 |
String |
事務(wù)編碼，由物聯(lián)卡集團(tuán)客戶(hù)按照相應(yīng)規(guī)則自 主生成，生成規(guī)則：yyyyMMddHHmmss+APPID+ 八 位 隨 機(jī) 數(shù) ， appid 樣 例 ： 2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通過(guò)指定接口獲取。 |
| iccid |
是 |
String |
集成電路卡識(shí)別碼，IC 卡的唯一識(shí)別號(hào)碼，共 有 20 位字符組成，舉例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/activationCard?transId=xxxx&token=xxxx&icci d=xxxx
返回參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
默認(rèn)值 |
含義 |
| suceess |
是 |
boolean |
請(qǐng)求是否成功。true - 成功 false - 失敗 |
| errorCode |
是 |
int |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包 含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） 此處為 iccid 的值 |
返回報(bào)文舉例
成功：
{
"success": true，
"errorCode": 0，
"errorMsg": "",
"data": "898600D6991330004146"
}
失?。?{
"success": flase，
"errorMsg":"TOKEN 不存在或已過(guò)期，請(qǐng)重新獲取",
"data":{},
"errorCode":12022
}
2.2 停機(jī)
服務(wù)地址：
http://sz.cotonda.com/iotManage/api/stopCard
業(yè)務(wù)描述：
集團(tuán)客戶(hù)可以通過(guò)卡號(hào) iccid 變更集團(tuán)歸屬物聯(lián)卡的狀態(tài)
請(qǐng)求參數(shù)說(shuō)明:
| 參數(shù) |
是否必須 |
類(lèi)型 |
含義 |
| transId |
是 |
String |
事務(wù)編碼，由物聯(lián)卡集團(tuán)客戶(hù)按照相應(yīng)規(guī)則自 主生成，生成規(guī)則：yyyyMMddHHmmss+APPID+ 八 位 隨 機(jī) 數(shù) ， appid 樣 例 ： 2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通過(guò)指定接口獲取。 |
| iccid |
是 |
String |
集成電路卡識(shí)別碼，IC 卡的唯一識(shí)別號(hào)碼，共 有 20 位字符組成，舉例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/stopCard?transId=xxxx&token=xxxx&iccid=xxxx
返回參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
默認(rèn)值 |
含義 |
| suceess |
是 |
boolean |
請(qǐng)求是否成功。true - 成功 false - 失敗 |
| errorCode |
是 |
int |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包 含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） 此處為 iccid 的值 |
返回報(bào)文舉例
成功：
{
"success": true，
"errorCode": 0，
"errorMsg": "",
"data": "898600D6991330004146"
}
失敗： {
"success": flase，
"errorMsg":"TOKEN 不存在或已過(guò)期，請(qǐng)重新獲取",
"data":{},
"errorCode":12022
}
3. 物聯(lián)卡查詢(xún)類(lèi)
3.1 查詢(xún)卡狀態(tài)
服務(wù)地址：
http://sz.cotonda.com/iotManage/api/getCardStatus
業(yè)務(wù)描述：
集團(tuán)客戶(hù)可以通過(guò)卡號(hào) iccid 查詢(xún)集團(tuán)歸屬物聯(lián)卡的狀態(tài)
請(qǐng)求參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
類(lèi)型 |
含義 |
| transId |
是 |
String |
事務(wù)編碼，由物聯(lián)卡集團(tuán)客戶(hù)按照相應(yīng)規(guī)則自 主生成，生成規(guī)則：yyyyMMddHHmmss+APPID+ 八 位 隨 機(jī) 數(shù) ， appid 樣 例 ： 2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通過(guò)指定接口獲取。 |
| iccid |
是 |
String |
集成電路卡識(shí)別碼，IC 卡的唯一識(shí)別號(hào)碼，共 有 20 位字符組成，舉例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/getCardStatus?transId=xxxx&token=xxxx&icci d=xxxx
返回參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
默認(rèn)值 |
父級(jí) |
含義 |
| suceess |
是 |
boolean |
無(wú) |
請(qǐng)求是否成功。true - 成功 false - 失 敗 |
| errorCode |
是 |
int |
無(wú) |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
無(wú) |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
無(wú) |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） |
| activateTime |
是 |
String |
data |
第一次激活時(shí)間 |
| status |
是 |
int |
data |
卡片狀態(tài)（1：待激活 2：已激活 3：已停機(jī) 4：已失效 5：測(cè)試卡 6：已銷(xiāo)戶(hù) 7：庫(kù)存 ） |
| iccid |
是 |
String |
data |
iccid |
返回報(bào)文舉例
成功：
{
"data": {
"activateTime": "2020-10-24 11:37", 第一次激活的時(shí)間
"cardStatus": 2,
"iccId": "898600D6991330004146"
},
"errorCode": 0,
"errorMsg": "",
"success": true
}
失?。?{
"success": flase，
"errorMsg":"TOKEN 不存在或已過(guò)期，請(qǐng)重新獲取",
"data":{},
"errorCode":12022
}
3.2 查詢(xún)卡用量
服務(wù)地址：
http://sz.cotonda.com/iotManage/api/getCardDosage
業(yè)務(wù)描述：
集團(tuán)客戶(hù)可以通過(guò)卡號(hào) iccid 查詢(xún)集團(tuán)歸屬物聯(lián)卡的狀態(tài)
請(qǐng)求參數(shù)說(shuō)明:
| 參數(shù) |
是否必須 |
類(lèi)型 |
含義 |
| transId |
是 |
String |
事務(wù)編碼，由物聯(lián)卡集團(tuán)客戶(hù)按照相應(yīng)規(guī)則自 主生成，生成規(guī)則：yyyyMMddHHmmss+APPID+ 八 位 隨 機(jī) 數(shù) ， appid 樣 例 ：2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通過(guò)指定接口獲取。 |
| iccid |
是 |
String |
集成電路卡識(shí)別碼，IC 卡的唯一識(shí)別號(hào)碼，共 有 20 位字符組成，舉例：898600D6991330004146 |
URL:
http://sz.cotonda.com/iotManage/api/getCardStatus?transId=xxxx&token=xxxx&icci d=xxxx
返回參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
默認(rèn)值 |
父級(jí) |
含義 |
| suceess |
是 |
boolean |
無(wú) |
請(qǐng)求是否成功。true - 成功 false - 失 敗 |
| errorCode |
是 |
int |
無(wú) |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
無(wú) |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
無(wú) |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） |
| updateTime |
是 |
String |
data |
最近更新時(shí)間 |
| dosage |
是 |
double |
data |
卡片用量 |
| iccid |
是 |
String |
data |
iccid |
返回報(bào)文舉例
成功：
{
"data": {
"dosage": 0,
"updateTime": "2021-05-11 18:15"
},
"errorCode": 0,
"errorMsg": "卡片狀態(tài)為 1",
"success": true
}
失敗：
{
"success": flase，
"errorMsg":"TOKEN 不存在或已過(guò)期，請(qǐng)重新獲取",
"data":{},
"errorCode":12022
}
3.3 查詢(xún)?nèi)航M信息
服務(wù)地址：
http://sz.cotonda.com/iotManage/api/getCardDosage
業(yè)務(wù)描述：
集團(tuán)客戶(hù)可以通過(guò)卡號(hào) iccid 查詢(xún)集團(tuán)歸屬物聯(lián)卡的狀態(tài)
請(qǐng)求參數(shù)說(shuō)明:
| 參數(shù) |
是否必須 |
類(lèi)型 |
含義 |
| transId |
是 |
String |
事務(wù)編碼，由物聯(lián)卡集團(tuán)客戶(hù)按照相應(yīng)規(guī)則自 主生成，生成規(guī)則：yyyyMMddHHmmss+APPID+ 八 位 隨 機(jī) 數(shù) ， appid 樣 例 ：2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通過(guò)指定接口獲取。 |
URL:
:http://sz.cotonda.com/iotManage/api/queryGroupInfo?transId=xxxx&token=xxxx
返回參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
默認(rèn)值 |
父級(jí) |
含義 |
| suceess |
是 |
boolean |
無(wú) |
請(qǐng)求是否成功。true - 成功 false - 失 敗 |
| errorCode |
是 |
int |
無(wú) |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
無(wú) |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
無(wú) |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） |
| name |
是 |
String |
data |
群組名稱(chēng) |
| flowPoolId |
是 |
String |
data |
群組 id |
返回報(bào)文舉例
成功：
{
"data": [
{
"name": "流量池 30G",
"flowPoolId": "splitNum00014508"
}
],
"errorCode": 0,
"errorMsg": "",
"success": true
}
失?。?
{
"success": flase，
"errorMsg":"TOKEN 不存在或已過(guò)期，請(qǐng)重新獲取",
"data":{},
"errorCode":12022
}
3.4 查詢(xún)?nèi)航M信息
服務(wù)地址：
http://sz.cotonda.com/iotManage/api/getCardDosage
業(yè)務(wù)描述：
集團(tuán)客戶(hù)可以通過(guò)卡號(hào) iccid 查詢(xún)集團(tuán)歸屬物聯(lián)卡的狀態(tài)
請(qǐng)求參數(shù)說(shuō)明:
| 參數(shù) |
是否必須 |
類(lèi)型 |
含義 |
| transId |
是 |
String |
事務(wù)編碼，由物聯(lián)卡集團(tuán)客戶(hù)按照相應(yīng)規(guī)則自 主生成，生成規(guī)則：yyyyMMddHHmmss+APPID+ 八 位 隨 機(jī) 數(shù) ， appid 樣 例 ：2021051317190020210430105318808600000000 |
| token |
是 |
String |
令牌，通過(guò)指定接口獲取。 |
| flowPoolId |
是 |
String |
群組 id |
URL:
http://sz.cotonda.com/iotManage/api/stopCard?queryGroupData=xxxx&token=xxxx& flowPoolId=xxxx
返回參數(shù)說(shuō)明：
| 參數(shù) |
是否必須 |
默認(rèn)值 |
父級(jí) |
含義 |
| suceess |
是 |
boolean |
無(wú) |
請(qǐng)求是否成功。true - 成功 false - 失 敗 |
| errorCode |
是 |
int |
無(wú) |
錯(cuò)誤碼。0-成功 非 0-失敗 |
| errorMsg |
是 |
String |
無(wú) |
時(shí)間戳 yyyyMMddHHmmss+10 個(gè)隨機(jī)數(shù) |
| data |
是 |
Object |
無(wú) |
返回結(jié)果集（errorCode 為“0”時(shí)，data 包含正確的結(jié)果數(shù)據(jù)；errorCode 為“非 0”時(shí)， data 為空） |
| name |
是 |
String |
data |
群組名稱(chēng) |
| flowPoolId |
是 |
String |
data |
群組 id |
| quantity |
是 |
int |
data |
總卡數(shù) |
| activateNum |
是 |
int |
data |
激活卡數(shù) |
| stopNum |
是 |
int |
data |
停機(jī)卡數(shù) |
| totalFlow |
是 |
double |
data |
可用總流量 |
| dosage |
是 |
double |
data |
已用量 |
| surplus |
是 |
double |
data |
剩余量 |
| numberSements |
是 |
List |
data |
包含流量池的所屬號(hào)段 |
| startIccId |
是 |
String |
numberSements |
某一號(hào)段開(kāi)始的 iccId |
| endIccId |
是 |
String |
numberSements |
某一號(hào)段結(jié)束的 iccId |
返回報(bào)文舉例
成功：
{
"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 不存在或已過(guò)期，請(qǐng)重新獲取",
"data":{},
"errorCode":12022
}