物聯(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

 }