神州物联卡API文档对接详情

物联网卡 2020-11-27 11:10:00 131 0

神州物联IOT平台对下接口文档

对下接口

RESTFUL API方式请求，采用http/https协议，json格式（POST）进行交互，对所有请求使用key进行md5校验，请妥善保存您的加密key，我们推荐您定期联系我们的客服，对key进行升级。另外我们的接口采用IP地址白名单策略，请告诉我们的客服您请求接口的ip地址，否则会提示ip地址不正确。
请注意所有请求请加入下面的http header(请求头):Content-Type 为 application/json;charset=UTF-8
我们启用了基于HTTPS的HTTP/2支持，可以基于HTTP 2.0客户端进行优化。

签名方式

调用平台的参数中需要提供签名
签名方法: timestamp、username、key的值按照此顺序连接成的字符串做 SHA256 哈希

key双方各自保密, 所以传输过程种不可能出现欺诈行为.

实例:

属性名	实例值
timestamp	1550493607884
username	cat
key	dYybWZV8Gj5MxrwiwyUUVs9uLzjrvuh8VegGMu6T

String text = "1550493607884catdYybWZV8Gj5MxrwiwyUUVs9uLzjrvuh8VegGMu6T";
String signature = DigestUtils.sha256Hex(text);
签名：1a54ce7a36aa73647cfb2f3236803056a59acf6ff5158e8668fd7640171c6869

接口校验数据方式

用户登录不受限
用户有api调用权限
用户请求ip地址在用户层级注册过的ip地址范围内
签名正确

1. 获取个人信息接口

网址:

POST /api/uc/user/info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	用户信息，code为0时才有数据，code不为0时为空

data结构:

序号	属性名	必填	交易说明
1	balance	Y	账户余额
2	name	Y	客户名称
3	apiIpList	Y	允许的IP地址, 半角逗号分隔

实例:

提交: POST /api/uc/user/info
{
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "balance" : 100,
      "name" : "Mr.Wealthy",
      "apiIpList" : "210.221.43.11,211.142.54.23"
    }
}

2. 客户产品列表

网址:

POST /api/uc/user/product-list

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间，精确到秒的毫秒数字，和服务器当前时间差距不可以超过60s
3	signature	Y	签名

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	产品列表信息的数组，code为0时才有数据，code不为0时为空

data结构(数组):

序号	属性名	必填	交易说明
1	name	Y	产品名称
2	productUid	Y	产品的唯一ID
3	productType	Y	产品类型，大分类：pkg1(流量包)，pkg2(叠加包)，msg(短信产品)，nbiot(NBIOT)，pkg3(虚拟流量包)
4	monthFlag	Y	是否月包：true，false
5	periodDays	Y	周期时间，整数
6	productSpecType	Y	s(定向)，n(非定向)
7	spec	Y	流量规格
8	countValue	Y	sms & nbiot的次数，整数
9	costPrice	Y	产品成本价
10	price	Y	产品价格
11	productStatus	Y	产品状态：on(上线)，off(下线）；必须是on才能下单，off的时候下单会失败
12	tag	Y	产品标签
13	content	Y	产品详细描述
14	maxRechargeCount	Y	对当月充值次数(客户往我们平台充值)。是这个产品，对于一张卡，每个月可以充值的次数。比如，我的手机号码订购了一个产品，70元/月不限量的，这个场景下再订购一个70元/月不限量就是不可以的

实例:

提交: POST /api/uc/user/product-list
{
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2"
}

返回:
没有可用产品时:
{
  "code" : 24,
  "message" : "",
  "data" : null
}
有可用产品时
{
  "code" : 0,
  "message" : "",
  "data" : [
    {
      "name" : "test 包月0",
      "productUid" : "5769af88ac924cfa84ac0836eb1b747f",
      "productType" : "pkg1",
      "monthFlag" : true,
      "periodDays" : 30,
      "productSpecType" : "s",
      "spec" : "25M",
      "countValue" : 20,
      "costPrice" : 20.00,
      "price" : 20.00,
      "productStatus" : "on",
      "tag" : "test tag",
      "content" : "test product content",
      "maxRechargeCount" : 1
    },
    {
      "name" : "test 包月1",
      "productUid" : "56cd2418e0f0433d920817626e167a4d",
      "productType" : "pkg2",
      "monthFlag" : false,
      "periodDays" : 30,
      "productSpecType" : "n",
      "spec" : "30M",
      "countValue" : 40,
      "costPrice" : 22.00,
      "price" : 25.00,
      "productStatus" : "on",
      "tag" : "test tag",
      "content" : "test product content",
      "maxRechargeCount" : 1
    } ]
}

可能返回的错误码

错误码	描述
24	没有可用产品

3. 下单接口(对应平台回调接口 1)

请注意日包产品下单，生效类型只能是tm(本月)；nm(下月)，仅针对月包产品有效。

网址:

POST /api/uc/order/create

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	tradeNo	Y	交易号,客户提交的
5	iccid	Y	卡的iccid
6	productUid	Y	产品的uid
7	effectiveType	Y	生效类型：tm(本月)，nm(下月:仅针对月包产品有效)
8	periodCount	Y	订购周期，月包可以订购多少个月。请注意必须是月包否则订购多月会失败
9	url	Y	回调网址
10	tel	Y	下单用户的电话号码
11	customerName	N	下单用户的姓名
12	idCardNo	N	下单用户的身份证

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	下单信息，code为0时才有数据，code不为0时为空

data结构:

序号	属性名	必填	交易说明
1	orderNo	Y	平台订单号
2	tradeNo	Y	交易号,客户提交的
3	iccid	Y	卡的iccid
4	productUid	Y	产品的uid
5	price	Y	价格
6	result	Y	本次下单结果(并非最终结果)
7	resultMessage	Y	本次下单结果信息
8	remoteCode	Y	远程调用结果,在本次调用返回时一定是空的
9	remoteMessage	Y	远程调用信息,在本次调用返回时一定是空的

实例:

提交: POST /api/uc/order/create
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" :"21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "tradeNo" : "987654321",
  "iccid" : "ic13802",
  "productUid" : "00c64f401a364ab58b7074fea582bf2e",
  "effectiveType" : "nm",
  "url" : "http://210.32.134.11:9000/callback",
  "tel" : "18910224083",
  "customerName" : "张三",
  "idCardNo" : "210202198903212266"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "orderNo" : "123456789",
      "tradeNo" : "987654321",
      "iccid" : "ic13802",
      "productUid" : "00c64f401a364ab58b7074fea582bf2e",
      "price" : 143.21,
      "result" : null,
      "resultMessage" : null,
      "remoteCode" : null,
      "remoteMessage" : null
    }
}

可能返回的错误码见错误码列表

4. 未通知订单列表

网址:

POST /api/uc/order/unnotified-list

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	未通知订单数组，code为0时才有data数据，code不为0时data为空

data结构(数组):

序号	属性名	必填	交易说明
1	orderNo	Y	平台订单号
2	tradeNo	Y	交易号,客户提交的
3	iccid	Y	卡的iccid
4	productUid	Y	产品的uid
5	price	Y	价格
6	result	Y	s成功，f失败
6	resultMessage	Y	本次下单结果信息
6	remoteCode	Y	远程调用结果,结果是错误的时候可能有值
6	remoteMessage	Y	远程调用信息,结果是错误的时候可能有值

实例:

提交: POST /api/uc/order/unnotified-list
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" :"21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : [
    {
      "orderNo" : "123456789",
      "tradeNo" : "987654321",
      "iccid" : "ic13802",
      "productUid" : "00c64f401a364ab58b7074fea582bf2e",
      "price" : 143.21,
      "result" : "s",
      "resultMessage" : "回调成功",
      "remoteCode" : null,
      "remoteMessage" : null
    },
    {
      "orderNo" : "124421212",
      "tradeNo" : "543456542",
      "iccid" : "ic13801",
      "productUid" : "nweinf92487bw298392723b8bf8322sd",
      "price" : 120.00,
      "result" : "f",
      "resultMessage" : "错误信息",
      "remoteCode" : null,
      "remoteMessage" : null
    }]
}

5. 卡产品列表

网址:

POST /api/uc/card/product-list

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址，此接口无回调地址

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码
2	message	Y	状态信息
3	data	Y	卡产品数组，code为0时才有data数据，code不为0时data为空

data结构(数组):

序号	属性名	必填	交易说明
1	name	Y	产品名称
2	productUid	Y	产品的唯一ID
3	productType	Y	产品类型，大分类：pkg1(流量包)，pkg2(叠加包)，msg(短信产品)，nbiot(NBIOT)，pkg3(虚拟流量包)
4	monthFlag	Y	是否月包：true，false
5	periodDays	Y	周期时间，整数
6	productSpecType	Y	产品指定类型：s(定向)，n(非定向)
7	spec	Y	流量规格
8	countValue	Y	sms & nbiot的次数，整数
9	costPrice	Y	产品成本价
10	price	Y	产品价格
11	productStatus	Y	产品状态：on(上线)，off(下线）；必须是on才能下单，off的时候下单会失败
12	tag	Y	产品标签
13	content	Y	产品详细描述
14	maxRechargeCount	Y	当月充值次数(客户往我们平台充值)。是这个产品，对于一张卡，每个月可以充值的次数。比如，我的手机号码订购了一个产品，70元/月不限量的，按照道理你再订购一个70元/月不限量就是不可以的

实例:

提交: POST /api/uc/card/product-list
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : null
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : [
    {
      "name" : "test 包月1",
      "productUid" : "56cd2418e0f0433d920817626e167a4d",
      "productType" : "pkg2",
      "monthFlag" : false,
      "periodDays" : 30,
      "productSpecType" : "n",
      "spec" : "30M",
      "countValue" : 40,
      "costPrice" : 22.00,
      "price" : 25.00,
      "productStatus" : "on",
      "tag" : "test tag",
      "content" : "test product content",
      "maxRechargeCount" : 1
    },
    {
      "name" : "test 包月2",
      "productUid" : "22849vibwcdy92hdaiqa9yd9923jqwwq",
      "productType" : "pkg2",
      "monthFlag" : true,
      "periodDays" : 30,
      "productSpecType" : "n",
      "spec" : "30M",
      "countValue" : 40,
      "costPrice" : 23.00,
      "price" : 27.00,
      "productStatus" : "on",
      "tag" : "test tag",
      "content" : "test product content",
      "maxRechargeCount" : 1
    }]
}

可能返回的错误码

错误码	描述
24	没有可用产品
25	没有可用卡
26	卡所有权错误

6. 卡状态查询(实名制状态，本月使用量)

网址:

POST /api/uc/card/info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址，此接口无回调地址

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	卡产品数组，code为0时才有data数据，code不为0时data为空

data结构:

序号	属性名	必填	交易说明
1	iccid	Y	卡的iccid
2	cardProductType	Y	卡产品类型：pkg(流量包)，msg(短信产品)，nbiot(NBIOT)，vpkg(虚拟流量包)
3	productSpecType	Y	是否定向：s(定向)，n(非定向)
4	cardStatus	Y	卡业务状态：w(待激活)，a(已激活)，d(已断网)，p(停机保号)，o(拆机)
5	cardTransferStatus	Y	卡流转状态：w(待分配)，a(已分配)，wr(待回收)，r(已回收)
6	activated	Y	状态:true(激活)，false(禁用)
7	remoteStatus	Y	远程状态
8	speedLimitingFlag	Y	是否已限速：true,false，为true时limitingSpeed字段和speedLimitingTime字段才有意义
9	limitingSpeed	Y	限制的速度，整数
10	speedLimitingTime	Y	限速时间
11	channelVerifiedFlag	Y	通道是否实名制：true,false
12	verifiedFlag	Y	本地是否实名制：true,false
13	total	Y	当月总流量（或者sms&nbiot次数），当卡为客户控制卡的时候，total为0
14	used	Y	当月已使用流量（或者sms&nbiot次数）
15	detailList	N	数组：当前的未到期的日包和月包产品列表以及详情

detailList结构：
|序号|属性名|必填|交易说明|
|------:|:-------:|:-------:|:---------|
|1|id|Y|记录ID，仅供出现错误情况的时候参考|
|2|productName|Y|产品名称|
|3|productUid|Y|产品唯一编号|
|4|period|N|多月包的情况(monthFlag:true)，总共订购了几个月。|
|5|periodIndex|N|月包的情况(monthFlag:true)，当前执行次数。用于显示多月包情况下执行到第几个月。|
|6|amount|Y|产品包含的流量(M)|
|7|used|Y|产品使用量(M)|
|7|monthKey|Y|当前月份|
|7|monthFlag|Y|是否是月包产品|
|7|startDate|Y|生效日期|
|9|endDate|Y|结束日期|
|9|usedRate|Y|当前使用比例|

实例:

提交: POST /api/uc/card/info
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : null
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "iccid" : "ic13802",
      "cardProductType" : "pkg",
      "productSpecType" : "s",
      "cardStatus" : "d",
      "cardTransferStatus" : "wr",
      "activated" : true,
      "remoteStatus" : "下线",
      "limitingSpeed" : 10,
      "speedLimitingTime" : "2019-2-14 12:13:14",
      "channelVerifiedFlag" : false,
      "verifiedFlag" : true,
      "total" : 1,
      "used" : 0
      "detailList" : [
            {
                "id":471443,
                "productName":"15G（电信-神洲卡）",
                "productUid":"a3b80129cb5d42ecb64915b649f999ea",
                "period":1,
                "periodIndex":3,
                "amount":15360,
                "used":343.325,
                "monthKey":201908,
                "monthFlag":true,
                "startDate":"2019-08-11T15:29:42",
                "endDate":"2019-09-09T23:59:59",
                "usedRate":2.2351888020833335
            }
        ]
    }
}

可能返回的错误码

错误码	描述
25	没有可用卡
26	卡所有权错误

7. 机卡重绑操作(对应平台回调接口 2)

网址:

POST /api/uc/card/perform-rebind

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	平台操作号，在本接口操作中唯一，回调时利用操作号索引到某次操作

实例:

提交: POST /api/uc/card/perform-rebind
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : "http://210.32.134.11:9000/callback"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : 341
}

可能返回的错误码

错误码	描述
25	没有可用卡
26	卡所有权错误
41	通道不可用
42	机卡重绑次数受限

8. 恢复上网操作(对应平台回调接口 2)

网址:

POST /api/uc/card/perform-restore

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	平台操作号，在本种类操作中唯一，回调时利用操作号索引到某次操作

实例:

提交: POST /api/uc/card/perform-restore
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : "http://210.32.134.11:9000/callback"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : 341
}

可能返回的错误码

错误码	描述
25	没有可用卡
26	卡所有权错误
41	通道不可用

9. 限速操作(对应平台回调接口 2)

网址:

POST /api/uc/card/perform-speed-limiting

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址
6	limitingFlag	Y	限速:true，取消限速:false
7	mark	Y	备注
8	limitingSpeed	Y	速度，单位kb，整数

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	平台操作号，在本种类操作中唯一，回调时利用操作号索引到某次操作

实例:

提交: POST /api/uc/card/perform-speed-limiting
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : "http://210.32.134.11:9000/callback",
  "limitingFlag" : true,
  "mark" : "",
  "limitingSpeed" : 20
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : 341
}

可能返回的错误码

错误码	描述
23	提交的数据格式错误
25	没有可用卡
26	卡所有权错误
41	通道不可用

10. 复网操作(对应平台回调接口 2)

注意本接口仅针对客户控制卡的情况，具体请在接入时候咨询。

网址:

POST /api/uc/card/perform-reconnect

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	平台操作号，在本种类操作中唯一，回调时利用操作号索引到某次操作

实例:

提交: POST /api/uc/card/perform-reconnect
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : "http://210.32.134.11:9000/callback"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : 341
}

可能返回的错误码

错误码	描述
25	没有可用卡
26	卡所有权错误
41	通道不可用

11. 断网操作(对应平台回调接口 2)

注意本接口仅针对客户控制卡的情况，具体请在接入时候咨询。

网址:

POST /api/uc/card/perform-disconnect

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	卡的iccid
5	callbackUrl	Y	回调地址

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	平台操作号，在本种类操作中唯一，回调时利用操作号索引到某次操作

实例:

提交: POST /api/uc/card/perform-disconnect
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" : "21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid" : "ic13802",
  "callbackUrl" : "http://210.32.134.11:9000/callback"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" : 341
}

可能返回的错误码

错误码	描述
25	没有可用卡
26	卡所有权错误
41	通道不可用

12. 获取虚拟池信息接口

网址:

POST /api/uc/virtual-pool/info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	用户信息，code为0时才有数据，code不为0时为空

data结构:

序号	属性名	必填	交易说明
1	monthKey	Y	当前月份, 201910
2	totalCardCount	Y	计费的总卡数,包含所有虚拟池
3	totalUsedAmount	Y	计费的卡本月当前使用的总流量（单位：MB）,包含所有虚拟池
4	totalPrice	Y	计费的卡本月当前使用的总费用(单位:元),包含所有虚拟池
5	details	Y	当前虚拟池列表

details结构:

序号	属性名	必填	交易说明
1	name	Y	名称
2	totalCardCount	Y	当前虚拟池内的卡数

实例:

提交: POST /api/uc/virtual-pool/info
{
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "monthKey" : 201910,
      "totalCardCount" : 20000,
      "totalUsedAmount" : 500000.00,
      "totalPrice" : 2200,
      "details" : [{
        "name" : "虚拟池1",
        "totalCardCount" : 12000,
      },{
        "name" : "虚拟池2",
        "totalCardCount" : 8000,
      }]
    }
}

可能返回的错误码

错误码	描述
3	客户没有虚拟池权限

状态码code

状态码	描述
0	成功
1	没有这个客户账户
2	客户账户不可用（可能是登录受限）
3	客户账户无权限（可能是没有api访问权限）
4	客户账户IP地址错误
5	客户账户余额不足
21	请求数据校验失败
22	提交的数据时间戳不正确（和服务器当前时间误差过大）
23	提交的数据格式错误
24	没有可用产品
25	没有可用卡
26	卡状态错误
27	卡所有权错误
28	请求的号码在黑名单中
29	提交的客户订单号(tradeNo)当日重复
41	通道不可用
42	机卡重绑次数受限
61	没有这个订单号
62	没有这个手机号
999	未知错误

回调接口（全部为GET方法回调）

回调网址响应头都要加上 content-type:text/plain; 返回纯文本的true之后停止回调尝试，否则目前会定期尝试回调约24小时（这个时间不保证，未来可能修改）
例:

平台	添加响应头
Java	response.setContentType("text/plain");
C#	response.Content.Headers.ContentType = new MediaTypeHeaderValue("text/plain");
Asp.net	context.Response.ContentType = "text/plain";
PHP	header('Content-type: text/plain');

1. 下单回调(对应接口 3)

提交参数:

序号	属性名	交易说明
1	orderNo	平台订单号
2	tradeNo	对下接口交易号
3	iccid	卡的iccid
4	productUid	卡产品的uid
5	price	价格
6	result	下单结果
7	resultMessage	下单结果信息(url当中为转义编码)
8	remoteCode	远程状态码(url当中为转义编码)
9	remoteMessage	远程状态信息(url当中为转义编码)
10	signature	签名

签名方式：

按照此顺序连接数据值：orderNo、tradeNo、iccid、productUid、price、result、resultMessage、remoteCode、remoteMessage、username、key
对连接后的数据做SHA256哈希，得到signature

签名实例：

序号	属性名	实例值
1	orderNo	123456789
2	tradeNo	987654321
3	iccid	ic13802
4	productUid	4223
5	price	120.00
6	result	s
7	resultMessage	字符串"订购成功"
8	remoteCode	字符串"成功"
9	remoteMessage	字符串"远程下单成功"
10	username	cat
11	key	dYybWZV8Gj5MxrwiwyUUVs9uLzjrvuh8VegGMu6T

String string = "123456789987654321ic138024223120.00s订购成功成功远程下单成功catdYybWZV8Gj5MxrwiwyUUVs9uLzjrvuh8VegGMu6T";
String signature = DigestUtils.sha256Hex(string);
签名结果：c4b02716c29675a57ab9512f9ae7f2dd3ab588ff837c9e76f5276b4178bee02f

实例：

对下接口3中提供的回调url：http://210.31.34.11/callback
请求：GET http://210.31.34.11/callback?orderNo=123456789&tradeNo=987654321&iccid=ic13802&productUid=4223&price=120.00&result=SUCCESS&resultMessage=%E4%B8%8B%E5%8D%95%E6%88%90%E5%8A%9F&remoteCode=%E6%88%90%E5%8A%9F&remoteMessage=%E8%BF%9C%E7%A8%8B%E4%B8%8B%E5%8D%95%E6%88%90%E5%8A%9F&signature=c4b02716c29675a57ab9512f9ae7f2dd3ab588ff837c9e76f5276b4178bee02f
返回：header为text/plain;内容：true

2. 卡操作回调(对应接口 7、8、9、10、11)

提交参数:

序号	属性名	交易说明
1	id	对下接口7、8、9接口回复的操作号
2	iccid	卡的iccid
3	type	卡批量操作类型：speedLimiting(限速)、speedUnlimited(取消限速)、parking(停机保号)、unparking(停机保号恢复)、disconnect(断网)、reconnect(复网)、restore(恢复上网)、rebind(机卡重绑)、obsolet(拆机)
4	result	操作结果
5	resultMessage	操作结果信息
6	remoteMessage	远程操作结果信息
7	signature	签名

签名方式：

按照此顺序连接数据值：id、iccid、type、result、resultMessage、remoteMessage、username、key
对连接后的数据做SHA256哈希，得到signature

签名实例：

序号	属性名	实例值
1	id	121
2	iccid	ic13802
3	type	speedLimiting
4	result	SUCCESS
5	resultMessage	字符串"操作成功"
6	remoteMessage	字符串"远程操作成功"
7	username	cat
8	key	dYybWZV8Gj5MxrwiwyUUVs9uLzjrvuh8VegGMu6T

String string = "121ic13802speedLimitingSUCCESS操作成功远程操作成功catdYybWZV8Gj5MxrwiwyUUVs9uLzjrvuh8VegGMu6T";
String signature = DigestUtils.sha256Hex(string);
签名结果：2ddd31bbd8f3d37d5a47e5016bf065bed87c1dec6bc2cb2e0ad5c5ad68d78173

实例：

对下接口7(或8或9)中提供的回调url：http://210.31.34.11/callback
请求：GET http://210.31.34.11/callback?id=121&iccid=ic13802&type=speedLimiting&result=SUCCESS&resultMessage=%E6%93%8D%E4%BD%9C%E6%88%90%E5%8A%9F&remoteMessage=%E8%BF%9C%E7%A8%8B%E6%93%8D%E4%BD%9C%E6%88%90%E5%8A%9F&signature=2ddd31bbd8f3d37d5a47e5016bf065bed87c1dec6bc2cb2e0ad5c5ad68d78173
返回：header为text/plain;内容：true

设备相关接口

用户登录不受限
用户有api调用权限
用户请求ip地址在用户层级注册过的ip地址范围内
签名正确

1. 获取设备信息接口

网址:

POST /api/uc/device/endpoint/info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	设备的ICCID或者UID,服务端会自动适配

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	用户信息，code为0时才有数据，code不为0时为空

data结构:

序号	属性名	必填	交易说明
1	iccid	Y	设备ICCID
2	uid	Y	设备UID编号
3	endpointDeviceType	Y	设备类型，目前都是mifi
4	ssid	Y	WIFI名
5	wifiPassword	Y	WIFI密码
6	status	Y	状态（未激活/工作中/等待新卡分配/断网/定期释放/长时间无上报/无可用卡）
7	firmwareVersion	N	固件版本
8	lastRechargeTime	N	上次充电时间
9	client	N	当前连接的设备数
10	temp	N	当前温度
11	battery	N	当前电量
12	siglte	N	当前信号强度

实例:

提交: POST /api/uc/device/endpoint/info
{
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2",
  "iccid":"898604631119C0873401"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "iccid" : "898604631119C0873401",
      "uid" : "11000800",
      "endpointDeviceType" : "mifi",
      "ssid" : "xsd-1000800",
      "wifiPassword" : "1234567890",
      "status" : "工作中",
      "firmwareVersion" : null,
      "lastRechargeTime" : "2020-06-22 10:07:07",
      "client" : "3",
      "temp" : "44.5",
      "battery" : "4",
      "siglte" : "-89"
    }
}

2. 获取设备使用信息

网址:

POST /api/uc/device/endpoint/used-info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间，精确到秒的毫秒数字，和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	设备的ICCID或者UID,服务端会自动适配

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	数据结构

data结构(数组):

序号	属性名	必填	交易说明
1	iccid	Y	产品名称
2	used	Y	当前已用
3	left	Y	当前剩余
4	total	Y	总量
5	rate	Y	使用比例
6	details	Y	当前详情列表

details结构:

序号	属性名	必填	交易说明
1	id	Y	编号
2	productName	Y	产品名称
3	productUid	Y	产品uid
4	period	Y	总周期
5	periodIndex	Y	当前周期（执行到第几次）
6	amount	Y	总量
7	used	Y	已用量
8	monthKey	Y	月KEY：202009
9	monthFlag	Y	月包标志，false是日包
10	startDate	Y	开始时间
11	endDate	Y	结束时间

实例:

提交: POST /api/uc/device/endpoint/used-info
{
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2",
 "iccid":"898604631119C0873401"
}

返回:参考前例

3. 设备修改接口，更新设备wifi信息

请注意日包产品下单，生效类型只能是tm(本月)；nm(下月)，仅针对月包产品有效。

网址:

POST /api/uc/device/endpoint/update-wifi-info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间，精确到秒的毫秒数字，和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	设备的ICCID或者UID,服务端会自动适配
5	ssid	Y	新的wifi名称
6	wifiPassword	Y	新的wifi密码

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	下单信息，code为0时才有数据，code不为0时为空

data结构（同获取设备信息接口）:

序号	属性名	必填	交易说明
1	iccid	Y	设备ICCID
2	uid	Y	设备UID编号
3	endpointDeviceType	Y	设备类型，目前都是mifi
4	ssid	Y	WIFI名
5	wifiPassword	Y	WIFI密码
6	status	Y	状态（未激活/工作中/等待新卡分配/断网/定期释放/长时间无上报/无可用卡）
7	firmwareVersion	N	固件版本
8	lastRechargeTime	N	上次充电时间
9	client	N	当前连接的设备数
10	temp	N	当前温度
11	battery	N	当前电量
12	siglte	N	当前信号强度

实例:

提交: POST /api/uc/device/endpoint/update-wifi-info
    {
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2",
  "iccid":"898604631119C0873401",
  "ssid":"Starbucks",
  "wifiPassword":"123456768"
}

返回:参考前例

4. 获取设备可用运营商接口

网址:

POST /api/uc/device/telecom-operator-list

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	设备的ICCID或者UID,服务端会自动适配

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	数据结构

data结构:

序号	属性名	必填	交易说明
1	priorityTelecomOperatorId	Y	当前设置的编号（availableList的ID）, 空为智能选网
2	plmn	N	当前的plmn，如果有的话
3	availableList	Y	可切换的运营商列表，根据当前plmn对应的国家设定

availableList结构:

序号	属性名	必填	交易说明
1	id	Y	编号
2	title	Y	名称

实例:

提交: POST /api/uc/order/unnotified-list
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" :"21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid":"898604631119C0873401"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "priorityTelecomOperatorId" : "1",
      "plmn" : "46001",
      "availableList" : [
            {
                "id": 1,
                "title":"中国移动"
            },{
                "id": 2,
                "title":"中国电信"
            },{
                "id": 3,
                "title":"中国联通"
            }
      ],
    }
}

5. 运营商网络切换接口

网址:

POST /api/uc/device/update-priority-telecom-operator

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	设备的ICCID或者UID,服务端会自动适配
5	telecomOperatorId	N	指定运营商ID，如果是null，为智能选网

出参（同获取设备可用运营商接口）:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	数据结构

data结构:

序号	属性名	必填	交易说明
1	priorityTelecomOperatorId	Y	当前设置的编号（availableList的ID）, 空为智能选网
2	plmn	N	当前的plmn，如果有的话
3	availableList	Y	可切换的运营商列表，根据当前plmn对应的国家设定

availableList结构:

序号	属性名	必填	交易说明
1	id	Y	编号
2	title	Y	名称

实例:

提交: POST /api/uc/device/update-priority-telecom-operator
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" :"21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "iccid":"898604631119C0873401"
}

返回:
{
  "code" : 0,
  "message" : "",
  "data" :
    {
      "priorityTelecomOperatorId" : "1",
      "plmn" : "46001",
      "availableList" : [
            {
                "id": 1,
                "title":"中国移动"
            },{
                "id": 2,
                "title":"中国电信"
            },{
                "id": 3,
                "title":"中国联通"
            }
      ],
    }
}

6. 获取设备产品列表接口

网址:

POST /api/uc/device/product-list

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间，精确到秒的毫秒数字，和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	iccid	Y	设备的ICCID或者UID,服务端会自动适配

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	产品列表信息的数组，code为0时才有数据，code不为0时为空

data结构(数组):

序号	属性名	必填	交易说明
1	name	Y	产品名称
2	productUid	Y	产品的唯一ID
3	spec	Y	流量规格
4	price	Y	产品价格
5	monthFlag	Y	是否月包：true，false
6	periodDays	Y	周期时间，整数
7	periodMonths	Y	如果是月包，固定多少个月周期，相对于前台订购的时候选了多少个月。如果为null，不限制这个参数，整数
8	tag	Y	产品标签
9	content	Y	产品详细描述
10	maxRechargeCount	Y	对当月充值次数(客户往我们平台充值)。是这个产品，对于一张卡，每个月可以充值的次数。比如，我的手机号码订购了一个产品，70元/月不限量的，这个场景下再订购一个70元/月不限量就是不可以的

实例:

提交: POST /api/uc/device/product-list
{
  "username":"cat",
  "timestamp":"1550493607884",
  "signature":"3bf00bbff4aa340ecfe7cd9ecf39d6f7cae8bb26a9fc10f0aa2e924c45fe41e2"
}

返回:
没有可用产品时:
{
  "code" : 24,
  "message" : "",
  "data" : null
}
有可用产品时:参考前例

可能返回的错误码

错误码	描述
24	没有可用产品

7. 设备下单接口

请注意日包产品下单，生效类型只能是tm(本月)；nm(下月)，仅针对月包产品有效。

网址:

POST /api/uc/device/order/create

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	tradeNo	Y	交易号,客户提交的
5	iccid	Y	卡的iccid
6	productUid	Y	产品的uid
7	effectiveType	Y	生效类型：tm(本月)，nm(下月:仅针对月包产品有效)
8	periodCount	Y	订购周期，月包可以订购多少个月。请注意必须是月包否则订购多月会失败

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	下单信息，code为0时才有数据，code不为0时为空

data结构:

序号	属性名	必填	交易说明
1	orderNo	Y	平台订单号
2	tradeNo	Y	交易号,客户提交的
3	iccid	Y	卡的iccid
4	productUid	Y	产品的uid
5	price	Y	价格
6	effectiveType	Y	tm/nm，本月下月
7	refundStatus	N	退款状态：正在退款/退款成功/退款失败
8	refundCompletedTime	N	退款成功时间
9	periodCount	Y	周期
10	executedPeriodCount	Y	已执行周期
11	startTime	Y	开始时间
12	expiredDate	Y	过期时间
13	result	Y	本次下单结果
14	resultMessage	Y	本次下单结果信息

实例:

提交: POST /api/uc/order/create
{
  "username" : "cat",
  "timestamp" : 1550469094536,
  "signature" :"21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
  "tradeNo" : "987654321",
  "iccid" : "ic13802",
  "productUid" : "00c64f401a364ab58b7074fea582bf2e",
  "effectiveType" : "nm"
}

返回:参考前例

8. 获取设备订单接口

根据tradeNo查询

网址:

POST /api/uc/device/order/info

入参:

序号	属性名	必填	交易说明
1	username	Y	用户名
2	timestamp	Y	当前时间, 精确到秒的毫秒数字,和服务器当前时间差距不可以超过60s
3	signature	Y	签名
4	tradeNo	Y	交易号,客户提交的

出参:

序号	属性名	必填	交易说明
1	code	Y	状态码，code为0时data字段才有数据
2	message	Y	状态信息
3	data	Y	下单信息，code为0时才有数据，code不为0时为空

data结构:

序号	属性名	必填	交易说明
1	orderNo	Y	平台订单号
2	tradeNo	Y	交易号,客户提交的
3	iccid	Y	卡的iccid
4	productUid	Y	产品的uid
5	price	Y	价格
6	effectiveType	Y	tm/nm，本月下月
7	refundStatus	N	退款状态：正在退款/退款成功/退款失败
8	refundCompletedTime	N	退款成功时间
9	periodCount	Y	周期
10	executedPeriodCount	Y	已执行周期
11	startTime	Y	开始时间
12	expiredDate	Y	过期时间
13	result	Y	本次下单结果
14	resultMessage	Y	本次下单结果信息

实例:

提交: POST /api/uc/order/create
{
  "username" : "cat",
  "timestamp" : 1550469094536,

"signature" :"21a93b03c8fcae833c83de431de0a1caa1e243df7a3d2747a2789a89368e3208",
"tradeNo" : "987654321"
}

返回:参考前例

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。该文并不代表本站赞同其观点和对其真实性负责。如若内容侵犯了原著者的合法权益，可联系我们进行处理。

神州物联卡神州物联 API文档

神州物联卡API文档对接详情

神州物联IOT平台对下接口文档

对下接口

签名方式

接口校验数据方式

1. 获取个人信息接口

2. 客户产品列表

3. 下单接口(对应平台回调接口 1)

4. 未通知订单列表

5. 卡产品列表

6. 卡状态查询(实名制状态，本月使用量)

7. 机卡重绑操作(对应平台回调接口 2)

8. 恢复上网操作(对应平台回调接口 2)

9. 限速操作(对应平台回调接口 2)

10. 复网操作(对应平台回调接口 2)

11. 断网操作(对应平台回调接口 2)

12. 获取虚拟池信息接口

状态码code

回调接口（全部为GET方法回调）

1. 下单回调(对应接口 3)

2. 卡操作回调(对应接口 7、8、9、10、11)

设备相关接口

1. 获取设备信息接口

2. 获取设备使用信息

3. 设备修改接口，更新设备wifi信息

4. 获取设备可用运营商接口

5. 运营商网络切换接口

6. 获取设备产品列表接口

7. 设备下单接口

8. 获取设备订单接口

发表评论

共有 3 条评论

游客

关于我们

常见问题

合作&赞助

官方微信

关注公众号

神州物联IOT平台对下接口文档

对下接口

签名方式

接口校验数据方式

1. 获取个人信息接口

2. 客户产品列表

3. 下单接口(对应平台回调接口 1)

4. 未通知订单列表

5. 卡产品列表

6. 卡状态查询(实名制状态，本月使用量)

7. 机卡重绑操作(对应平台回调接口 2)

8. 恢复上网操作(对应平台回调接口 2)

9. 限速操作(对应平台回调接口 2)

10. 复网操作(对应平台回调接口 2)

11. 断网操作(对应平台回调接口 2)

12. 获取虚拟池信息接口

状态码code

回调接口（全部为GET方法回调）

1. 下单回调(对应接口 3)

2. 卡操作回调(对应接口 7、8、9、10、11)

设备相关接口

1. 获取设备信息接口

2. 获取设备使用信息

3. 设备修改接口，更新设备wifi信息

4. 获取设备可用运营商接口

5. 运营商网络切换接口

6. 获取设备产品列表接口

7. 设备下单接口

8. 获取设备订单接口

相关文章

发表评论

共有 3 条评论

游客

生成海报

会员登录

注册会员