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

神州物联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

接口校验数据方式

  1. 用户登录不受限

  2. 用户有api调用权限

  3. 用户请求ip地址在用户层级注册过的ip地址范围内

  4. 签名正确

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 签名

签名方式

  1. 按照此顺序连接数据值:orderNo、tradeNo、iccid、productUid、price、result、resultMessage、remoteCode、remoteMessage、username、key

  2. 对连接后的数据做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 签名

签名方式

  1. 按照此顺序连接数据值:id、iccid、type、result、resultMessage、remoteMessage、username、key

  2. 对连接后的数据做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

设备相关接口

  1. 用户登录不受限

  2. 用户有api调用权限

  3. 用户请求ip地址在用户层级注册过的ip地址范围内

  4. 签名正确

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"
   }

返回:参考前例
点赞 收藏

发表评论

共有 3 条评论