Http接入协议

版本 制定者 更改内容 修改时间 变更原因
V1.0.0 frank 1．定义了短信提交接口测试
2．定义了回执主动推送接口		 2018-4-27 增加接口

一、短信下行

1. 请求

属性 类型 约束 说明
tradeNo String 必选 交易唯一流水号，请求方生成，最大60位; 如:当前时间戳+六位随机数; 注:该字段是本次交易的唯一标识
appid String 必选 帐号-6位，如：100000
mobile String 必选 发送手机号码，支持多号码，号码之间用英文逗号隔开，最多1000个。如：单个号码 13900000000 , 多个号码 13900000000,13900000001
content String 必选 【签名】+ 短信内容，UTF-8编码，短信内容最长500个字（包括英文字母），其中签名2-12个字（包括英文字母）
extno String 可选 自扩展端口,1－4位，只能为数字，可以为空(注：请先询问当前账号是否支持自扩展端口，如果不支持，请填空)
xid String 可选 用户透传ID， 随状态报告返回，最长60位
sign String 必选 动态签名：把mobile，content字段的值和平台分配的appkey值，一起用MD5加密，得到一个32位的加密签名。
算法如下：sign=MD5(mobile+content+appkey)，如：3bc0cc96e65f4f202a562a05bce37532

注：

①extno字段用于客户传送由客户自行分配给子客户的扩展端口，用于上行短信回来与之对应。
如：某客户下有A、B、C三个子客户，并且该客户获得某通道两位自扩展，分别对其子客户自行分配的扩展端口依次为子客户A：01，子客户B：02，子客户C:03。
若子客户A在发送下行短信时将该扩展端口01填入此字段即可，上行短信将会把此字段的扩展端口01发给客户，用于客户区分哪个子客户的上行短信，子客户A可根据上行短信中的电话号码对应之前的下行手机号码。

②xid字段是用户扩展字段，随状态报告带回，可用于传入用户自己平台的该短信交易的唯一号。

③sign字段把手机号码和短信内容一起加密，防止这2个字段值在传输过程中被篡改。

  1.  {
  2.     tradeNo:20180428130412000001,
  3.     appid:100000,
  4.     mobile:13800138000,13800138001,19800138002,19800138003,
  5.     content:【短信宝】您的验证码为：1234,
  6.     extno:01,
  7.     xid:00,
  8.     sign:3bc0cc96e65f4f202a562a05bce37532
  9.  }
包头/包体 实例 备注
Header POST /sms/submit HTTP/1.1
Accept-Encoding:identity
Content-Length:226
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分，保证路径正确,采用HTTP的POST方式发送；
Body {
“tradeNo”: “20180428130412000001”,
“appid”: “100000”,
“mobile”: “13800138000,13800138001,19800138002,19800138003”,
“content”: “【短信宝】您的验证码为1234”,
“extno”: “00”,
“xid”: “00”,
“sign”: “3bc0cc96e65f4f202a562a05bce37532”
}		 蓝色字体为可变部分

2. 响应

属性 类型 约束 说明
tradeNo String 必选 交易唯一流水号,与请求消息tradeNo字段的值一致。
该字段唯一确认该响应消息是对哪个请求消息的回应。
备注：客户端异步提交的时候可以通过该字段配对到具体的请求消息。
result String 必选 短信请求响应返回码，参考“请求响应返回码”定义的返回码
desc String 必选 短信请求响应返回中文描述，参考“请求响应返回码”定义的中文描述
taskId String 必选 短信任务号，本次请求分配的唯一编号(通过该字段匹配到状态报告)
群发的话 可以通过taskId+mobile确认唯一一条状态报告
errPhones String 可选 群发场景下提交失败的号码（一般是号码不正确）
多个号码用英文逗号隔开		 
  1.  {
  2.     tradeNo:20180428130412000001,
  3.     result:P00000,
  4.     desc:提交成功,
  5.     taskId:db6b7d847b8c4ca99f167bde211abbd2,
  6.     errPhones:
  7.  }
包头/包体 实例 备注
Header HTTP/1.1 200 OK
Accept-Encoding:identity
Content-Length:133
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分
Body {
“tradeNo”: “20180428130412000001”,
“result”: “P00000”,
“desc”: “提交成功”,
“taskId”: “db6b7d847b8c4ca99f167bde211abbd2”,
“errPhones”: “”
}		 蓝色字体为可变部分

二、短信状态报告－推送方式

1. 请求

属性 类型 约束 说明
taskId String 必选 短信下行的时候，平台分配的任务号
mobile String 必选 短信接收端手机号码
xid String 可选 用户透传ID，随状态报告返回
resultCode String 必选 状态报告指示短信发送结果，DEVILER（成功）/其他（失败）
resultDesc String 必选 状态报告结果描述
deliverTime Long 必选 状态报告时间,1970年1月1日零时以来的毫秒数
sendTime Long 可选 用户提交时间,1970年1月1日零时以来的毫秒数

注：

①taskId字段返回内容和第一章第2节响应中的“短信任务号”一致，用于与之前下行短信的发送记录相对应；

②xid字段返回内容和第一章第2节响应中的“用户透传ID”一致，用于客户自定义扩展；

③resultCode表示短信是否成功投递到手机，“DELIVER”表示投递成功，其他表示失败;

④resultDesc字段是对resultCode结果值的具体描述。
通过taskId和mobile两字段可确定是哪个手机的下行短信状态报告；
通过resultCode和resultDesc字段可确定手机是否收到下行短信，并清楚下行短信投递状态；
通过deliverTime字段可确定下行短信的到达时间。

  1. [
  2.   {
  3.     taskId:6df59d3c15914bbfbb6616baaeee8242,
  4.     mobile:13800138000,
  5.     xid:00,
  6.     resultCode:DELIVRD,
  7.     resultDesc:消息投递成功,
  8.     deliverTime:
        1532603273000
        ,
    9. 
        
  9. 
            sendTime:
            1532603273000
    10. 
        
  10.   },
  11.   {
  12.     taskId:6df59d3c15914bbfbb6616baaeee8242,
  13.     mobile:13800138001,
  14.     xid:00,
  15.     resultCode:UNDELIV,
  16.     resultDesc:消息投递失败,
  17.     deliverTime:1532603273000,
  18.     sendTime:1532603273000
  19.   }
  20. ]
包头/包体 实例 备注
Header POST /xxx/xxx/xxx HTTP/1.1
Accept-Encoding:identity
Content-Length:407
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8		 蓝色字体为可变部分，保证路径正确,采用HTTP的POST方式发送；
Body
[{
“taskId”: “6df59d3c15914bbfbb6616baaeee8242”,
“mobile”: “13800138000”,
“xid”: “00”,
“resultCode”: “DELIVRD”,
“resultDesc”: “消息投递成功”,
“deliverTime”:1532603273000,
“sendTime”:1532603273000
},
{
“taskId”: “6df59d3c15914bbfbb6616baaeee8242”,
“mobile”: “13800138001”,
“xid”: “00”,
“resultCode”: “UNDELIV”,
“desc”: “消息投递失败”,
“deliverTime”:1532603273000,
“sendTime”:1532603273000
}]		 蓝色字体为可变部分

2. 响应

属性 类型 约束 说明
code String 必选 返回错误码，0：成功，其它失败
errmsg String 可选 返回错误详细描述 
  1. 成功：
  2.  {
  3.    code:0
  4.  }//成功
  6. 失败：
  7.  {
  8.    code:-1，
  9.    errmsg:ip limit
  10.  }//ip非法
包头/包体 实例 备注
Header HTTP/1.1 200 OK
Accept-Encoding:identity
Content-Length:13
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分
Body {“code”: “0”}
或
{“code”: “-1”，”errmsg”: “ip limit”}		 蓝色字体为可变部分

三、短信状态报告－拉取方式

1. 请求

注意：为了确保数据隐私和安全，用户需要通过HttpPost方式请求，消息格式：json表达式。

属性 类型 约束 说明
appid String 必选 帐号，6位，平台分配的appid
如：100000
sign String 必选 签名，平台分配的appkey 用MD5加密
如：81cefb4dbd7081baaaa92906514e708e		 
  1.   {
  2.     appid:100000,
  3.     password:81cefb4dbd7081baaaa92906514e708e
  4.   }
包头/包体 实例 备注
Header POST /report/100000/get HTTP/1.1
Accept-Encoding:identity
Content-Length:60
Host:ip:port
Accept:application/json
Content-Type:application/json;charset=utf-8		 蓝色字体为可变部分，保证路径正确,采用HTTP的POST方式发送；
Body {
“appid”: “100000”,
“sign”: “81cefb4dbd7081baaaa92906514e708e”
}		 蓝色字体为可变部分

2.响应

属性 类型 约束 说明
taskId String 必选 短信下行的时候，平台分配的任务号
mobile String 必选 短信接收端手机号码
xid String 可选 用户透传ID，随状态报告返回
resultCode String 必选 状态报告指示短信发送结果，DEVILER（成功）/其他（失败）
resultDesc String 必选 状态报告结果描述
deliverTime Long 必选 状态报告时间,1970年1月1日零时以来的毫秒数
sendTime Long 可选 用户提交时间,1970年1月1日零时以来的毫秒数 
  1. [
  2.   {
  3.     taskId:6df59d3c15914bbfbb6616baaeee8242,
  4.     mobile:13800138000,
  5.     xid:00,
  6.     resultCode:DELIVRD,
  7.     resultDesc:消息投递成功,
  8.     deliverTime:1532603273000,
  9.     sendTime:1532603273000
  10.   },
  11.   {
  12.     taskId:6df59d3c15914bbfbb6616baaeee8242,
  13.     mobile:13800138001,
  14.     xid:00,
  15.     resultCode:UNDELIV,
  16.     resultDesc:消息投递失败,
  17.     deliverTime:1532603273000,
  18.     sendTime:1532603273000
  19.   }
  20. ]
包头/包体 实例 备注
Header 请求成功：
HTTP/1.1 200 OK
Accept-Encoding:identity
Content-Length:407
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
请求失败：
HTTP/1.1 404
Accept-Encoding:identity
Content-Length:22
Host:IP:PORT
Accept:text/plain
Content-Type:text/plain;charset=utf-8
 蓝色字体为可变部分，保证路径正确,采用HTTP的POST方式发送；
Body 请求成功：
[{
“taskId”: “6df59d3c15914bbfbb6616baaeee8242”,
“mobile”: “13800138000”,
“xid”: “00”,
“resultCode”: “DELIVRD”,
“resultDesc”: “消息投递成功”,
“deliverTime”: “2016-04-28 13:04:18”,
“sendTime”: “2016-04-28 13:04:12”
},{
“taskId”: “6df59d3c15914bbfbb6616baaeee8242”,
“mobile”: “13800138001”,
“xid”: “00”,
“resultCode”: “UNDELIV”,
“desc”: “消息投递失败”,
“deliverTime”: “2016-04-28 13:04:13”,
“sendTime”: “2016-04-28 13:04:12”
}]
请求失败：传入参数sign错误		 蓝色字体为可变部分

四、上行短信推送方式

1. 请求

需要第三方自行配置URL地址，接受http post请求，消息格式：json表达式。
该接口一次最多推送1000条上行消息。

属性 类型 约束 说明
msg String 必选 上行的短信内容
mobile String 必选 上行手机号码
extno Long 可选 扩展号，用户下发时携带的参数
sendTime Long 可选 用户提交时间,1970年1月1日零时以来的毫秒数 
  1. [
  2.  {
  3.    msg:T,
  4.    mobile:13800138000,
  5.    extno:,
  6.    sendTime:1532603273000
  7.  }
  8.  {
  9.   msg:T,
  10.   mobile:13800138001,
  11.   extno:,
  12.   sendTime:1532603273000
  13.  }
  14. ]
包头/包体 实例 备注
Header POST /xxx/xxx/xxx HTTP/1.1
Accept-Encoding:identity
Content-Length:207
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分，
保证路径正确,采用HTTP的POST方式发送；
Body {
“msg”: “T”,”mobile”: “13800138000”,”extno”:””, “sendTime”: “1532603273000”},
{“msg”:”T,”mobile”:”13800138001“,”xid”:””,”sendTime”:1532603273000}]
}		 蓝色字体为可变部分

2. 响应

属性 类型 约束 说明
code String 必选 返回错误码，
0：成功，其它失败
errmsg String 可选 返回错误详细描述
 
  1. 成功：
  2. {
  3.   code:0
  4. }//成功
  6. 失败：
  7. {
  8.   code:-1，
  9.   errmsg:ip limit
  10. }//ip非法
包头/包体 实例 备注
Header HTTP/1.1 200 OK
Accept-Encoding:identity
Content-Length:13
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分
Body {
{“code”:” 0“}
或
{“code”:”-1“，”errmsg”:”ip limit“}
 蓝色字体为可变部分

五、上行短信-拉取方式

1. 请求

注意：为了确保数据隐私和安全，用户需要通过HttpPost方式请求，消息格式：json表达式。

属性 类型 约束 说明
appid String 必选 帐号，6位，平台分配的appid
如：100000
sign String 必选 签名，平台分配的appkey 用MD5加密，
如：81cefb4dbd7081baaaa92906514e708e
 
  1.  {
  2.   appid:100000,
  3.   password:81cefb4dbd7081baaaa92906514e708e
  4.  }
包头/包体 实例 备注
Header POST /report/100000/get HTTP/1.1
Accept-Encoding:identity
Content-Length:60
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分，
保证路径正确,采用HTTP的POST方式发送；
Body {
{“appid”:”100000“,”sign”:”81cefb4dbd7081baaaa92906514e708e“}
}		 蓝色字体为可变部分

2. 响应

属性 类型 约束 说明
msg String 必选 上行短信内容
mobile String 必选 上行手机号码
extno String 可选 扩展号，用户下发时携带的参数
sendTime String 可选 用户提交时间,1970年1月1日零时以来的毫秒数
 
  1. [{
  2.     msg: T,
  3.     mobile: 13800138000,
  4.     extno: ,
  5.     sendTime: 1532603273000
  6.   },
  7.   {
  8.     msg: T,
  9.     mobile: 13800138001,
  10.     extno: ,
  11.     sendTime: 1532603273000
  12.   }
  13. ]
包头/包体 实例 备注
Header 请求成功：
HTTP/1.1 200 OK
Accept-Encoding:identity
Content-Length:407
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
请求失败：
HTTP/1.1 404
Accept-Encoding:identity
Content-Length:22
Host:IP:PORT
Accept:text/plain
Content-Type:text/plain;charset=utf-8		 蓝色字体为可变部分
Body 请求成功：
[{“msg”:”T“}”,”mobile”:”13800138000“,”extno”:”00“,”sendTime”:”2016-04-28 13:04:12“},
{“msg”:”T“,”mobile”:”13800138001“,”extno”:”00“,”sendTime”:”2016-04-28 13:04:12“}]
请求失败
传入参数sign错误		 蓝色字体为可变部分

六、查询余额

1. 请求

注意：为了确保数据隐私和安全，用户需要通过Http Post方式请求，消息格式：json表达式。

属性 类型 约束 说明
tradeNo String 必选 交易唯一流水号，请求方生成，最大60位
如：当前时间戳+六位随机数
注：该字段是本次交易的唯一标识
appid String 必选 帐号，6位
如：100000
sign String 必选 签名 ，把appkey的值md5加密
算法如下：sign=MD5(appkey)
如：3bc0cc96e65f4f202a562a05bce37532
 
  1. {
  2.     tradeNo:20180428130412000001,
  3.     appid:100000,
  4.     sign:3bc0cc96e65f4f202a562a05bce37532
  5. }
包头/包体 实例 备注
Header POST /sms/getBalance HTTP/1.1
Accept-Encoding:identity
Content-Length:93
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分，
保证路径正确,采用HTTP的POST方式发送；
Body {
“tradeNo”: “20180428130412000001”,
“appid”: “100000”,
“sign”: “3bc0cc96e65f4f202a562a05bce37532”
}		 蓝色字体为可变部分

2. 响应

属性 类型 约束 说明
tradeNo String 必选 交易唯一流水号,与请求消息tradeNo字段的值一致。
该字段唯一确认该响应消息是对哪个请求消息的回应。
备注：客户端异步提交的时候可以通过该字段配对到具体的请求消息。
result String 必选 请求响应返回码，
参考“请求响应返回码”定义的返回码
desc String 必选 请求响应返回中文描述，
参考“请求响应返回码”定义的中文描述
balance Decimal(10,4) 必选 账号余额 
  1. {
  2.     tradeNo:20180428130412000001,
  3.     result:P00000,
  4.     desc:查询成功,
  5.     balance:1234.567
  6. }
包头/包体 实例 备注
Header HTTP/1.1 200 OK
Accept-Encoding:identity
Content-Length:133
Host:IP:PORT
Accept:application/json
Content-Type:application/json;charset=utf-8
 蓝色字体为可变部分
Body {
“tradeNo”: “20180428130412000001”,
“result”: “P00000”,
“desc”: “查询成功”,
“balance”: “1234.5670
}		 蓝色字体为可变部分

七、返回码定义

1. 请求返回码

返回码 描述 适用类型
P00000 提交成功/查询成功 短信下行，查询余额
P00001 参数错误 短信下行，查询余额
P00002 非法用户 短信下行，查询余额
P00003 鉴权失败 短信下行，查询余额
P00004 余额不足 短信下行
P00005 查询余额失败 查询余额
P00009 系统异常 短信下行，查询余额