短信接口

签名计算方式

string strAppKey = "5f03a35d00ee52a21327ab048186a2c4"; //sdkappId 对应的 appKey，需要业务方高度保密 string strRand = "7226249334"; //url 中的 random 字段的值 string strTime = "1457336869111"; //unix 时间戳(毫秒) string sig = sha256(appKey=5f03a35d00ee52a21327ab048186a2c4&random=7226249334&time=1457336869111) = 6c08a825fbce5743dbfe7520774e1aea43db1583f07a41932f2aa7c25b480fa0;

短信模板新增接口

描述：可以新增短信模板

接口地址

POST https://smsapi.icsoc.net/tpl/v1/add_template?appId=xxxxx&random=xxxx

请求参数

{
  "tplText": "xxx ${value1}, xxx ${value2}",
  "tplType": 1,
  "tplTitle": "afae",
  "remark": "aegrh",
  "sig": "c13e54f047ed75e821e698730c72d030dc30e5b510b3f8a0fb6fb7605283d7df",
  "time": 1457336869111,
  "state": -1,
  "signText": "TEST"
}

参数	是否必填	类型	描述
sig	是	string	app凭证，有一定的计算方式，具体参考下注
time	是	number	unix时间戳,精确到毫秒，如果和系统时间相差超过4小时则会返回失败
tplText	是	string	模板内容，${value}为模板待填充占位符
remark	否	string	模板备注
`tplType`	是	number	模板类型 1验证码 2通知 3营销
`tplTitle`	是	string	模板名称
state	否	number	默认0待审核,传其它无效
signText	否	string	短信签名信息不带【】

响应内容

{
  "code": 0,
  "msg": "",
  "tplId": 123
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	错误码详细信息
tplId	是	int	返回的模板id

短信模板获取接口

描述：可以获取公司的短信模板ID、短信模板内容、短信模板状态；

接口地址

POST https://smsapi.icsoc.net/tpl/v1/get_template?appId=xxxxx&random=xxxx

请求参数

{
  "sig": "c13e54f047ed75e821e698730c72d030dc30e5b510b3f8a0fb6fb7605283d7df",
  "time": 1457336869111,
  "tplId": [
    123,
    124
  ],
  "tplPage": {
    "max": 10,
    "offset": 0
  },
  "vccId": 123
}

参数	是否必填	类型	描述
sig	是	string	app凭证，有一定的计算方式，具体参考下注
time	是	number	unix时间戳,精确到毫秒，如果和系统时间相差超过4小时则会返回失败
tplId	否	array	待查询的模板 id 数组；不可与tplPage同时出现
tplPage	否	object	待分页查询模板id信息；不可与tplId同时出现
vccId	否	number	企业id；传了会忽略appId,查出企业下所有模板,适用于一个企业包含多个appId的模板的情况

参数 tplPage

参数	必选	类型	描述
max	是	num	一次拉取的条数，最多 50条；
offset	是	num	拉取模板在模板列表中的开始数字，从第几条模板开始拉取；

响应内容

{
  "code": 0,
  "msg": "",
  "count": 3,
  "data": [
    {
      "id": 123,
      "state": 0,
      "reason": "xxxxx",
      "tplTitle": "短信验证码",
      "tplText": "xxxxx",
      "remark": "xxxxx",
      "tplType": 0,
      "signText": "TEST"
    }
  ]
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	错误码详细信息
count	是	number	返回的信息条数，信息内容在 data 字段中
data	是	array	返回的信息详情

数组data元素参数

参数	必选	类型	描述
id	是	number	模板 id
state	是	number	模板状态 0待审核 1审核通过 2审核不通过
reason	是	string	审核不通过的原因
tplTitle	是	string	模板名称
tplText	是	string	模板内容
remark	是	string	模板备注信息
tplType	是	number	短信类型，1验证码 2通知 3营销
signText	是	string	模板绑定的短信签名

短信签名新增

描述：新增短信签名

接口地址

POST https://smsapi.icsoc.net/sign/v1/add_sign?appId=xxxxx&random=xxxx

请求参数

{
  "pic": "xxxxx",
  "remark": "xxxxx",
  "sig": "ee92bac01ec1e59bc8d6d33e5f506517cbc71c1e8ebcac4a80ca4ae32d84ab13",
  "signText": "xxxxx",
  "time": 1525004550111,
  "state": -1
}

参数	必选	类型	描述
sig	是	string	App 凭证，具体计算方式同上
signText	是	string	短信签名信息不带【】
time	是	number	请求发起时间，unix 时间戳（单位：秒）精确到毫秒，如果和系统时间相差超过4小时则会返回失败
pic	否	string	签名对应的资质证明图片进行 base64 编码格式转换后的字符串 base64 编码格式工具: http://base64.xpcha.com/indexie.php ，注意编译后去掉字符串前面的前缀：“data:image/jpeg;base64,”,编码之后的字符串不能超过1024长度
remark	否	string	签名备注，比如申请原因，使用场景等
state	否	number	默认0待审核,其它无效

响应内容

{
  "code": 0,
  "msg": "OK",
  "signId": 123
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	错误码详细信息
`signId`	是	number	签名id

短信签名查询

描述：查询签名；

接口地址

POST https://smsapi.icsoc.net/sign/v1/get_sign?appId=xxxxx&random=xxxx

请求参数

{
  "sig": "c13e54f047ed75e821e698730c72d030dc30e5b510b3f8a0fb6fb7605283d7df",
  "time": 1457336869111,
  "signId": [
    123,
    124
  ],
  "signPage": {
    "max": 10,
    "offset": 0
  }
}

参数	是否必填	类型	描述
sig	是	string	app凭证，有一定的计算方式，具体参考下注
time	是	number	unix时间戳,精确到毫秒，如果和系统时间相差超过4小时则会返回失败
signId	否	array	待查询的模板 id 数组；不可与signPage同时出现
signPage	否	object	待分页查询模板id信息；不可与signId同时出现

参数 tplPage

参数	必选	类型	描述
max	是	num	一次拉取的条数，最多 50条；
offset	是	num	拉取模板在模板列表中的开始数字，从第几条模板开始拉取；

响应内容

{
  "code": 0,
  "msg": "",
  "count": 3,
  "data": [
    {
      "signId": 123,
      "reason": "xxxxx",
      "state": 0,
      "text": "xxxxx"
    }
  ]
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	错误码详细信息
count	是	number	返回的信息条数，信息内容在 data 字段中
data	是	array	返回的信息详情

数组data元素参数

参数	必选	类型	描述
id	是	number	模板 id
state	是	number	模板状态 -1草稿 0待审核 1审核通过 2审核不通过
`reason`	是	string	审核不通过的原因
`text`	是	string	签名内容

直接发送接口

描述：传送短信内容发送

接口地址

POST https://smsapi.icsoc.net/sms/v1/send_sms?appId=xxxxx&random=xxxxx

请求参数

{
  "sig": "ee92bac01ec1e59bc8d6d33e5f506517cbc71c1e8ebcac4a80ca4ae32d84ab13",
  "smsExt": "ext arg",
  "exten": "2",
  "mobiles": [
    "17090132516"
  ],
  "time": 1525004550111,
  "smsText": "你好张三，您的验证码是1234",
  "signText": "ICSOC"
}

参数	必选	类型	描述
sig	是	string	App 凭证，具体计算方式同上
smsExt	否	string	用户的 session 内容，系统回包中会原路返回，不需要的话可以不填。
exten	否	string	短信码号扩展号，格式为纯数字串，其他格式无效。可填或不填，默认为空
signText	是	string	短信签名信息
mobiles	是	array	string数组，群发时一次最多不要超过 200 个手机号
time	是	number	请求发起时间，unix 时间戳（单位：秒）精确到毫秒，如果和系统时间相差超过4小时则会返回失败
smsText	是	string	短信内容

响应内容

{
  "smsExt": "",
  "code": 0,
  "msg": "OK",
  "data": [
    {
      "smsFee": 1,
      "mobile": "13788888888",
      "smsId": "xxxxxxx"
    },
    {
      "smsFee": 1,
      "mobile": "13788888888",
      "smsId": "xxxxxxx"
    }
  ]
}

参数	必选	类型	描述
smsExt	否	string	用户的 session 内容，系统回包中会原路返回，不需要的话可以不填。
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	错误码详细信息
data	是	array	结果详细数据

数组**data**元素参数：

参数	必选	类型	描述
smsFee	否	number	短信计费的条数，
mobile	是	string	手机号码
smsId	否	string	本次发送标识 id，标识一次短信下发记录

指定模板单条发送接口

使用指定短信模板给单个用户发送短信。

接口地址

POST https://smsapi.icsoc.net/sms/v1/send_single?appId=xxxxx&random=xxxxx

请求参数

{
  "smsExt": "ext arg",
  "exten": "2",
  "smsParams": [
    "验证码",
    "1234"
  ],
  "sig": "ee92bac01ec1e59bc8d6d33e5f506517cbc71c1e8ebcac4a80ca4ae32d84ab13",
  "mobile": "8617090132516",
  "time": 1525004550111,
  "tplId": 1,
  "signText": "ICSOC"
}

或

{
  "smsExt": "ext arg",
  "exten": "2",
  "smsParams": {
    "name": "张三",
    "content": "1234"
  },
  "sig": "ee92bac01ec1e59bc8d6d33e5f506517cbc71c1e8ebcac4a80ca4ae32d84ab13",
  "mobile": "8617090132516",
  "time": 1525004550111,
  "tplId": 1,
  "signText": "ICSOC"
}

参数	必选	类型	描述
sig	是	string	App 凭证，具体计算方式同上
smsExt	否	string	用户的 session 内容，系统回包中会原路返回，不需要的话可以不填。
exten	否	string	短信码号扩展号，格式为纯数字串，其他格式无效。可填或不填，默认为空
signText	是	string	短信签名信息
mobile	是	string	电话号码，格式如：13711112222 为手机号；可兼容+86
tplId	是	number	模板 ID，审核通过的模板 ID
smsParams	是	array	模板参数，若模板没有参数，请提供为空数组
time	是	number	请求发起时间，unix 时间戳（单位：秒）精确到毫秒，如果和系统时间相差超过4小时则会返回失败

响应内容

{
  "mobile": "8617090132516",
  "code": 0,
  "msg": "OK",
  "smsFee": 1,
  "smsId": "xxxxxxx"
}

参数	必选	类型	描述
mobile	否	string	电话号码
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	结果消息详情
smsFee	否	number	短信计费的条数
smsId	否	string	本次发送标识 id，标识一次短信下发记录

指定模板批量发送接口

使用短信模板给多个用户发送相同内容的短信。（单次提交不超过 200 个手机号，内容长度不超过 400 字）

接口地址

POST https://smsapi.icsoc.net/sms/v1/send_batch?appId=xxxxx&random=xxxxx

请求参数

{
  "smsExt": "",
  "exten": "",
  "smsParams": [
    "验证码",
    "1234",
    "4"
  ],
  "sig": "be66bb4aeb54701ed0637d0996a0b75111d5b8eda9b3a71bdc579a3d26f3edfb",
  "signText": "ICSOC",
  "mobiles": [
    "13788888888",
    "13788888889"
  ],
  "time": 1457336869111,
  "tplId": 19
}

或

{
  "smsExt": "",
  "exten": "",
  "smsParams": {
    "text": "验证码",
    "content": "1234"
  },
  "sig": "be66bb4aeb54701ed0637d0996a0b75111d5b8eda9b3a71bdc579a3d26f3edfb",
  "signText": "ICSOC",
  "mobiles": [
    "13788888888",
    "13788888889"
  ],
  "time": 1457336869111,
  "tplId": 19
}

参数	必选	类型	描述
sig	是	string	App 凭证，具体计算方式见下注
smsExt	否	string	用户的 session 内容，系统回包中会原路返回，不需要的话可以不填。
exten	否	string	短信码号扩展号，格式为纯数字串，其他格式无效。默认没有扩展码；如需扩展码，请联系系统
smsParams	是	array	模板参数，若模板没有参数，请提供为空数组
signText	是	string	短信签名，如果使用默认签名，该字段可缺省
tplId	是	number	模板 ID，审核通过的模板 ID
mobiles	是	array	群发号码数组，群发时一次最多不要超过 200 个手机号
time	是	number	请求发起时间，unix 时间戳（单位：秒），精确到毫秒，如果和系统时间相差超过4小时则会返回失败

响应参数

{
  "smsExt": "",
  "code": 0,
  "msg": "OK",
  "data": [
    {
      "smsFee": 1,
      "mobile": "13788888888",
      "smsId": "xxxxxxx"
    },
    {
      "smsFee": 1,
      "mobile": "13788888888",
      "smsId": "xxxxxxx"
    }
  ]
}

参数	必选	类型	描述
smsExt	否	string	用户的 session 内容，系统回包中会原路返回，不需要的话可以不填。
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	错误码详细信息
data	是	array	结果详细数据

数组**data**元素参数：

参数	必选	类型	描述
smsFee	否	number	短信计费的条数，
mobile	是	string	手机号码
smsId	否	string	本次发送标识 id，标识一次短信下发记录

上传文件发送

接口地址

POST https://smsapi.icsoc.net/sms/v1/send_file?appId=xxxxx&random=xxxxx

请求参数 postform

smsExt:egehe smsParams:验证码 smsParams:1234 exten:2 sig:ee92bac01ec1e59bc8d6d33e5f506517cbc71c1e8ebcac4a80ca4ae32d84ab13 time:1525004550111 tplId:1 signText:ICSOC mobiles: <file>

响应内容

{
  "code": 0,
  "msg": "OK"
}

文件发送中间状态回调

{
  "mobile": "xxxafae",
  "smsId": "xxxxxxdfff",
  "smsText": "xaxaxaxax",
  "time": 1525004550111,
  "smsExt": "egehe"
}

模板格式

17090132516 param param   说明  列间隔符 空格 第一列手机号 必填 第二列之后为参数，优先级大于外层的参数，param参数需要URIEncode

短信下发状态推送接口

短信下发给用户后，系统可以实时通过回调业务 url 的方式，通知业务方短信下发的状态。

接口地址

POST 客户配置回调url

推送数据格式

{
  "timeDelivered": 1525274940333,
  "exten": "00122",
  "mobile": "13xxxxxxxxx",
  "state": "SUCCESS",
  "errmsg": "OK",
  "smsId": "xxxxxxx",
  "smsExt": "xxxx",
  "smsFee": 1
}

参数	必选	类型	描述
exten		string	通道号扩展码，返回业务方设定的扩展码
timeDelivered	是	string	用户实际接收到短信的时间
mobile	是	string	手机号码
state	是	string	调用平台成功，送SENDED到回调收到短信回执，送SUCCESS到回调实际是否收到短信接收状态，SUCCESS（接收成功）、FAIL（接收失败）
errmsg	是	string	用户接收短信状态码错误信息
smsId	是	string	本次发送标识 id
smsExt	否	string	用户的 session 内容，系统回包中会原路返回，不需要的话可以不填。
smsFee	是	number	计费条数
channelType	是	int	实际发送短信的通道类型；
errType	是	int	错误类型0 无错误1 系统错误2 网络错误3 平台错误4 回执错误
errCode	是	string	短信通道返回的真实错误代码

响应参数注意：有一部分公共的错误代码是我们自己定义的，比如调用第三方接口失败，可能和第三方的errcode冲突，可以通过errmsg区分

{
  "code": 0,
  "msg": "OK"
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功（计费依据），非 0 表示失败
msg	是	string	错误消息，code 非 0 时的具体错误信息

短信回复推送接口

用户收到短信后，回复短信，以回调方式通知业务方用户回复了短信。

接口地址

POST 客户配置回调url

推送数据格式

{
  "exten": "扩展码",
  "mobile": "13xxxxxxxxx",
  "smsText": "用户回复的内容",
  "timeDelivered": 1457336869
}

参数	必选	类型	描述
exten	否	string	通道扩展码，默认没有开通（需要填空）
mobile	是	string	手机号码
smsText	是	string	用户回复的内容
timeDelivered	是	number	用户短信到达的时间，unix 时间戳（单位：秒），精确到毫秒

响应参数

{
  "code": 0,
  "msg": "OK"
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
msg	是	string	消息详情；

短信下发状态拉取接口

拉取短信状态。拉取过的内容不会再重复返回，可以理解为消息队列机制。

接口地址

POST https://smsapi.icsoc.net/pull/v1/down_status?appId=xxxxx&random=xxxxx

请求参数

{
  "max": 10,
  "sig": "c13e54f047ed75e821e698730c72d030dc30e5b510b3f8a0fb6fb7605283d7df",
  "time": 1457336869098
}

参数	必选	类型	描述
sig	是	string	App 凭证，具体计算方式见下注
max	是	number	拉取最大条数，最多 100
time	是	number	请求发起时间，unix 时间戳（单位：秒）精确到毫秒，如果和系统时间相差超过4小时则会返回失败

响应参数

{
  "count": 3,
  "data": [],
  "exten": "00122",
  "msg": "ok",
  "code": 0
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
count	是	number	code 为 0 时有效，返回的信息条数
data	是	array	具体内容见短信下发状态
msg	是	string	短信下发状态错误码说明

data详情

参数	必选	类型	描述
timeDelivered	是	string	用户实际接收到短信的时间，unix时间戳
exten	否	string	通道号扩展码，返回业务方设定的扩展码
mobile	是	string	手机号码
state	是	string	调用平台成功，送SENDED到回调收到短信回执，送SUCCESS到回调实际是否收到短信接收状态，SUCCESS（接收成功）、FAIL（接收失败）
errmsg	是	string	用户接收短信状态码错误信息
smsId	是	string	本次发送标识 id
errType	是	int	错误类型0 无错误1 系统错误2 网络错误3 平台错误4 回执错误
errCode	是	string	短信通道返回的真实错误代码
channelType	是	int	实际发送短信的通道类型；

短信回复拉取接口

拉取短信回复内容。拉取过的内容不会再重复返回，可以理解为消息队列机制。

接口地址

POST https://smsapi.icsoc.net/pull/v1/up_status?appId=xxxxx&random=xxxxx

请求参数

{
  "max": 10,
  "sig": "c13e54f047ed75e821e698730c72d030dc30e5b510b3f8a0fb6fb7605283d7df",
  "time": 1457336869789
}

参数	必选	类型	描述
sig	是	string	App 凭证，具体计算方式见下注
max	是	number	拉取最大条数，最多 100
time	是	number	请求发起时间，unix 时间戳（单位：秒）精确到毫秒，如果和系统时间相差超过4小时则会返回失败

响应参数

{
  "count": 3,
  "data": [],
  "msg": "ok",
  "code": 0
}

参数	必选	类型	描述
code	是	number	错误码，0 表示成功，非 0 表示失败
count	是	number	code 为 0 时有效，返回的信息条数
data	是	array	具体内容见短信回复
msg	是	string	code 的具体信息描述

data详情

参数	必选	类型	描述
exten	否	string	通道扩展码，默认没有开通（需要填空）
mobile	是	string	手机号码
smsText	是	string	用户回复的内容
timeDelivered	是	number	用户短信到达的时间，unix 时间戳（单位：秒）

短信发送接口错误码

错误码	原因	解决方案
1001	sig校验失败	请核对 API 的sig格式说明
1002	appId 不存在
1003	appId 已禁用	此 appId 禁止提供服务，如有需要请联系系统供应商
1004	请求没有 appId 字段或 sig 为空	请遵守 API 接口说明规范
1005	请求包解析失败，通常情况下是由于没有遵守 API 接口说明规范导致的
1006	请求没有权限	请查看错误提示语说明，如还有问题请提供失败手机号联系系统供应商
1007	不支持该请求
1008	其他错误	请查看错误提示语说明，如还有问题请提供失败手机号联系系统供应商
1009	请求发起时间不正常，通常是由于您的服务器时间与系统供应商服务器时间差异超过 10 分钟导致的	请核对服务器时间及 API 接口中的时间字段是否正常
1010	请求下发短信超时	出现概率很低，可重试解决
1011	不存在该 REST API 接口	请核查 REST API 接口说明
1012	手机号格式错误	请核查下发短信/语音的用户手机号格式是否正确
1013	手机号码数量超过限制	单次提交手机号码数量超过200
1014	请求的短信内容太长	短信内容长度超过400个字符限制，请调整短信长度
1015	请求的模板参数异常
1016	请求的公司短信模板ID不存在或未审核通过
1017	没有找到短信通道	建议联系系统供应商处理
1018	签名不存在	短信签名不存在
1019	路由不存在	通道路由不存在
1020	数据不能为空，请检查请求参数必填字段	请检查请求参数必填字段
1021		请检查文件类型
1022	exten扩展码格式错误	0-9字符串

文件类型不为txt或csv，请检查文件类型

签名计算方式​

短信模板新增接口​

接口地址​

请求参数​

响应内容​

短信模板获取接口​

接口地址​

请求参数​

响应内容​

短信签名新增​

接口地址​

响应内容​

短信签名查询​

接口地址​

请求参数​

响应内容​

直接发送接口​

接口地址​

请求参数​

响应内容​

指定模板单条发送接口​

接口地址​

请求参数​

响应内容​

指定模板批量发送接口​

接口地址​

请求参数​

响应参数​

上传文件发送​

接口地址​

请求参数 postform​

响应内容​

文件发送中间状态回调​

模板格式​

短信下发状态推送接口​

接口地址​

推送数据格式​

短信回复推送接口​

接口地址​

推送数据格式​

响应参数​

短信下发状态拉取接口​

接口地址​

请求参数​

响应参数​

短信回复拉取接口​

接口地址​

请求参数​

响应参数​

短信发送接口错误码​

签名计算方式

短信模板新增接口

接口地址

请求参数

响应内容

短信模板获取接口

接口地址

请求参数

响应内容

短信签名新增

接口地址

响应内容

短信签名查询

接口地址

请求参数

响应内容

直接发送接口

接口地址

请求参数

响应内容

指定模板单条发送接口

接口地址

请求参数

响应内容

指定模板批量发送接口

接口地址

请求参数

响应参数

上传文件发送

接口地址

请求参数 postform

响应内容

文件发送中间状态回调

模板格式

短信下发状态推送接口

接口地址

推送数据格式

短信回复推送接口

接口地址

推送数据格式

响应参数

短信下发状态拉取接口

接口地址

请求参数

响应参数

短信回复拉取接口

接口地址

请求参数

响应参数

短信发送接口错误码