短信接口_短信群发API接口

Slide
短信API

开发者所需的API专区

Slide

首页

帮助中心

短信API

签名鉴权

Sign签名生成方法:使用 api认证名+api认证密码+ Timestamp当前系统时间戳(秒),生成MD5-32位字符串(不区分大小写)作为签名

示例:

参数

api认证名:bDqJFiq9

api认证密钥:7bz1lzh9

Timestamp当前系统时间戳(秒):1630468800

方法

MD5(bDqJFiq97bz1lzh91630468800)

Sign

05d7a50893e22a5c4bb3216ae3396c7c

请求头参数:

header参数说明类型
Content-Typeapplication/json;charset=UTF-8String
Sign加密后签名String
Timestamp当前系统时间戳(秒),要求半个小时内String
Api-KeyApi认证名(页面账户管理-API管理-认证名)String

状态码

status:响应状态码说明

状态码参数说明
0success
-1认证错误
-2IP访问受限
-3短信内容含有敏感字符
-4短信内容为空
-5短信内容过长
-6不是模板的短信
-7号码个数过多
-8号码为空
-9号码异常
-10客户余额不足,不能满足本次发送
-11定时时间格式不对
-12由于平台的原因,批量提交出错,请与管理员联系
-13用户被锁定
-14Field为空或者查询id异常
-15查询过频繁
-16timestamp expires
-17短信模板不能为空
-18接口异常
-19认证完成后,需要联系商务经理为您开启短信之旅

短信发送

接口名称

sendSms

接口说明

提交短信接口,支持单个号码或多个号码发送

请求方法

支持GET或POST,GET方式一次最多提交100个号码,POST方式一次最多提交1000个号码

请求URL:

https://api.onbuka.com/v3/sendSms

请求参数说明:

参数说明是否必填类型
appId应用id(页面账户管理-应用管理-appId属性)String
numbers短信接收号码,多个号码之间以英文逗号分隔(get最多100个,post最多1000个)String
content发送内容,长度不能超过1024字符,get请求内容需要urlEncodeString
senderId发送的号码String

GET请求示例 发送 “hellow word”内容:

Request URL:https://api.onbuka.com/v3/sendSms?appId=4luaKsL2&numbers=91856321412,91856321413&content=hellow%20word&senderId=123 Request Method: GET Request Headers: Content-Type: application/json;charset=UTF-8 Sign: 05d7a50893e22a5c4bb3216ae3396c7c Timestamp: 1630468800 Api-Key: bDqJFiq9

POST请求示例 发送 “hellow word” 内容:

Request URL: https://api.onbuka.com/v3/sendSms Request Method:POST Request Headers: Content-Type: application/json;charset=UTF-8 Sign: 05d7a50893e22a5c4bb3216ae3396c7c Timestamp: 1630468800 Api-Key: bDqJFiq9 Request Body: { "appId":"4luaKsL2", "numbers":"91856321412,91856321413", "content":"hellow word", "senderId":"123" }

响应参数说明:

参数说明类型
status状态码,0成功,其他失败参见状态码说明String
reason失败原因说明String
success提交成功的号码个数String
fail提交失败的号码个数String
array提交成功的json集合JSONArray
msgId提交号码对应平台msgIdString
number提交号码String

注:提交发送成功后,系统会给每个提交成功的号码对应生成一个平台msgId,后续客户可以根据这个msgId来查询该号码的发送结果。

响应示例:

{ "status":"0", "reason":"success", "success":"2", "fail":"0", "array":[ { "msgId":"2108021054011000095", "number":"91856321412" }, { "msgId":"2108021059531000096", "number":"91856321413" } ] }

余额查询

接口名称

getBalance

接口说明

用于获取账户余额接口

请求方法

GET

请求URL:

https://api.onbuka.com/v3/getBalance

请求示例

Request URL: https://api.onbuka.com/v3/getBalance Request Method: GET Request Headers: Content-Type: application/json;charset=UTF-8 Sign: 05d7a50893e22a5c4bb3216ae3396c7c Timestamp: 1630468800 Api-Key: bDqJFiq9

响应参数说明:

参数说明类型
status状态码,0成功,其他失败参见状态码说明String
reason失败原因说明String
balance实际账户的余额String
gift赠送账户余额String

响应示例

{ "status":"0", "reason": "success", "balance": "99.990000", "gift": "50.00000" }

查询短信发送结果

接口名称

getReport

接口说明

查询指定msgId集合的发送结果

请求方法

GET

请求URL:

https://api.onbuka.com/v3/getReport?appId={appId}&msgIds={msgIds}

请求参数说明:

参数说明是否必填类型
appId应用id(页面账户管理-应用管理-appId属性)String
msgIdssendSms接口响应返回的平台id,多个用英文逗号分隔,单次查询最大200个msgIdString

请求示例:

Request URL:https://api.onbuka.com/v3/getReport?appId=4luaKsL2&msgIds=2108021054011000095,2108021059531000096 Request Method: GET Request Headers: Content-Type: application/json;charset=UTF-8 Sign: 05d7a50893e22a5c4bb3216ae3396c7c Timestamp: 1630468800 Api-Key: bDqJFiq9

响应参数说明:

参数说明类型
status状态码,0成功,其他失败参见状态码说明String
reason失败原因说明String
success发送成功的条数String
fail发送失败的条数String
sending正在发送的条数String
nofoundId未找到的条数String
array找到发送结果的json集合JSONArray
msgId提交号码对应平台msgIdString
number提交号码String
receiveTime发送时间,ISO8601标准时间格式(2021-02-12T09:30:03+08:00)String
status发送状态:0发送成功,-1:发送中,1:发送失败String

响应示例:

{ "status":"0", "reason":"success", "success":"2", "fail":"0", "sending":"0", "nofound":"0", "array":[ { "msgId":"2108021054011000095", "number":"91856321412", "receiveTime":"2021-02-12T09:30:03+08:00", "status":"0" }, { "msgId":"2108021059531000096", "number":"91856321413", "receiveTime":"2021-02-12T09:30:03+08:00", "status":"0" } ] }

查询时间段内发送的短信结果

接口名称

getSentRcd

接口说明

查询开始时间到结束时间这个时间段内已经发送完成的短信结果

请求方法

GET

请求URL:

https://api.onbuka.com/v3/getSentRcd?appId={appId}& startTime={startTime}&endTime={endTime}&startIndex={startIndex}

请求参数说明:

参数说明是否必填类型
appId应用id(页面账户管理-应用管理-appId属性)String
startTime查询起始时间,ISO8601标准时间格式UrlEncode(2021-02-12T00:00:00+08:00)String
endTime查询结束时间,ISO8601标准时间格式UrlEncode(2021-02-12T23:59:59+08:00)String
startIndex查询的起始下标(单次查询默认最多返回50000个结果,超过50000分多次查询时可用到此字段)否(默认0)Int

请求示例

Request URL:https://api.onbuka.com/v3/getSentRcd?appId=4luaKsL2&startTime=2021-02-12T00%3A00%3A00%2B08%3A00&endTime=2021-02-12T23%3A59%3A59%2B08%3A00&startIndex=0 Request Method: GET Request Headers: Content-Type: application/json;charset=UTF-8 Sign: 05d7a50893e22a5c4bb3216ae3396c7c Timestamp: 1630468800 Api-Key: bDqJFiq9

响应参数说明:

参数说明类型
status状态码,0成功,其他失败参见状态码说明String
reason失败原因说明String
success发送成功的条数String
fail发送失败的条数String
array找到发送结果的json集合JSONArray
msgId提交号码对应平台msgIdString
number提交号码String
receiveTime发送时间,ISO8601标准时间格式(2021-02-12T09:30:03+08:00)String
status发送状态:0发送成功,-1:发送中,1:发送失败String

响应示例:

{ "status":"0", "reason":"success", "success":"2", "fail":"0", "array":[ { "msgId":"2108021054011000095", "number":"91856321412", "receiveTime":"2021-02-12T09:30:03+08:00", "status":"0" }, { "msgId":"2108021059531000096", "number":"91856321413", "receiveTime":"2021-02-12T09:30:03+08:00", "status":"0" } ] }

平台主动推送状态报告

说明

当用户在账户管理-应用管理页面,配置了http推送地址后,平台会将http-api接入的短信,状态报告主动推送给用户配置地址

请求方式

POST

请求URL

用户配置的http推送地址

推送示例

Request URL:用户配置的https推送地址 Request Method: POST Request Headers: Content-Type: application/json;charset=UTF-8 Request Body: { "appId":"4luaKsL2", "msgid":"2108021059531000096", "mobile":"91856321413", "status":"0", "timestamp":"1629801177192" }

推送参数说明:

参数说明是否必填类型
appId应用id(页面账户管理-应用管理-appId属性)String
msgid提交号码对应平台msgidLong
mobile提交号码String
status发送状态说明:0发送成功,-1:发送中,1:发送失败Int
timestamp发送时间戳(毫秒)Long

响应示例:

Http响应200成功即可,平台不做响应内容校验

短信接口

天一泓国际短信IMFS接口说明

接口协议

HTTP

编码格式

UTF8

请求方法

GET、POST

Content-Type

application/json

charset=UTF-8

Sign签名生成方法

将账号、API秘钥、请求时间拼成字符串,做MD5加密,MD5使用32位小写

示例

参数方法Sign
account:test password:123456 datetime:20210402120000MD5(test12345620210402120000)c02190a4f5a4d2a266023f002011ca0a

注:API秘钥(password)为认证秘钥,非登录密码,可登录天一泓短信系统查询获取;请求时间(datetime)需传GMT+8当前半小时内时间,格式为年月日时分秒,而非时间戳。

余额查询

接口名称

getbalanceV2

接口说明

本接口用于查询账户余额信息

请求方法

GET

调用方式:

http://sms.skylinelabs.cc:20003/getbalanceV2?account=***&sign=***&datetime=***

请求参数说明:

参数说明是否必填类型
version协议版本号否(默认1.0)String
accountAPI密钥String
signMD5签名(详细说明见接口说明Sign签名生成方法)String
datetime时间字符串【年月日时分秒】,非时间戳String

接口成功返回示例:

{"status":0,"balance":"99.990000", "gift":"50.00000"}

返回参数说明:

参数说明类型
status查询状态 0:获取成功 -1:认证错误 -2:IP访问受限INT
balance账户余额String
gift账户赠送余额String

群发短信

接口名称

sendsmsV2

接口说明

本接口用于发送短信,可单条发送,也可批量号码发送同一内容,支持GET、POST方式提交

请求方法

GET、POST

调用方式1(GET):

URL:http://sms.skylinelabs.cc:20003/sendsmsV2?account=***&sign=***&datetime=***&senderid=***&numbers=8613611111111,8613722222222&content=***

调用方式2(POST):

URL:http://sms.skylinelabs.cc:20003/sendsmsV2?account=***&sign=***&datetime=***

POST请求使用json格式,参数如下:

{"content":"test","numbers":"8613611111111,8613722222222","senderid":"123 123"}

请求参数说明:

参数说明是否必填类型
version协议版本号否(默认1.0)String
accountAPI密钥String
signMD5签名(详细说明见接口说明Sign签名生成方法)String
datetime时间字符串【年月日时分秒】,非时间戳String
senderid发送方号码String
numbers短信接收号码,多个号码之间以英文逗号分隔(GET请求一次最多100个,POST请求一次最多1000个)String
content发送内容(GET方式提交需要做urlEncode),长度不能超过1024字节String

接口成功返回示例:

{"status":0, "success":2, "fail":0, "array":[[8613611111111,1901281451030204206], [8613722222222,1901281450470121055]]}

返回参数说明:

参数说明类型
status查询状态 0:获取成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足,不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因,批量提交出错,请与管理员联系 -13:用户被锁定 -16:超出时间范围限制 -17:短信模版不能为空INT
success提交成功的个数INT
fail提交失败的个数INT
array提交短信成功的数组,数组中依次包含“号码、号码的发送结果查询ID”,均为数字字符

批量群发短信

接口名称

batchsendsmsV2

接口说明

本接口用于批量发送短信,支持不同号码发送不同内容

请求方法

POST

调用方式:

POST /batchsendsmsV2?account=***&sign=***&datetime=**** HTTP/1.1 Host: http://sms.skylinelabs.cc:20003 Content-Type:application/json {"messages":[{"senderid":"0123456789","content":"%E5%85%BB%E8%80%81%E9%87%91%E8%","mobile":["8613611111111","8613722222222"],"smsid":"1"},{"content":"%E5%86%BB%E8%80%81%E9%87%91%E8%","mobile":["8613811111111"],"smsid":"2"}]}

注:POST请求account、sign、datetime参数需放在URL中,不可放在json中提交

请求参数说明:

参数说明是否必填类型
version协议版本号否(默认1.0)String
accountAPI密钥String
signMD5签名(详细说明见接口说明Sign签名生成方法)String
datetime时间字符串【年月日时分秒】,非时间戳String
senderid发送方号码String
mobile短信接收号码,多个号码之间以英文逗号分隔String
content发送内容(需要做urlEncode),长度不能超过1024字节String
smsid请求方自行定义的消息IDString

接口成功返回示例:

{"success": 1,"fail": 2,"array": [[0,"8613611111111","1",1901121607180200001],[9,"13722222222","1"],[9,"13811111111","2"]]}

返回参数说明:

参数说明类型
status查询状态 0:获取成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足,不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因,批量提交出错,请与管理员联系 -13:用户被锁定 -14:smsid为空INT
success提交成功的个数INT
fail提交失败的个数INT
array提交短信成功的数组 数组中依次包含:提交状态、号码、smsid、号码的发送结果查询ID(提交失败没有查询ID返回)

状态报告查询

接口名称

getreportV2

接口说明

本接口用于查询短信发送报告

请求方法

GET

调用方式:

http://sms.skylinelabs.cc:20003/getreportV2?account=***&sign=***&datetime=***&ids=1901281451030204206,1901281450470121055

请求参数说明:

参数说明是否必填类型
version协议版本号否(默认1.0)String
accountAPI密钥String
signMD5签名(详细说明见接口说明Sign签名生成方法)String
datetime时间字符串【年月日时分秒】,非时间戳String
ids指定查询发送结果的短信id(该id在提交时由系统返回) 多个号码之间以英文逗号分隔(最多200个)String

接口成功返回示例:

{"status":0, "success":1, "fail":1, "unsent":0, "sending":0, "nofound":0,"array":[[1901281451030204206,"86136****1111",20190128145103,0], [1901281450470121055,"8613722222222",20190128145047,3]]}

返回参数说明:

参数说明类型
status查询状态 0:获取成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足,不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因,批量提交出错,请与管理员联系 -13:用户被锁定 -14:查询id异常INT
success发送成功的个数INT
fail发送失败的个数INT
unsent未发送条数INT
sending正在发送的条数INT
nofoundId没有找到的条数INT
array短信发送结果的数组 数组中依次包含“号码的状态查询ID、号码、发送时间、状态”,均为数字字符 状态: 0:发送成功 1:未发送 2:正在发送 非012发送失败

批量报告查询

接口名称

getsentrcdV2

接口说明

本接口用于批量查询短信发送状态,查询开始时间到结束时间这个时间段内已发送完成的短信报告结果,查询频率最高允许每分钟1次查询,如超过频率,接口将返回-15。

请求方法

GET

调用方式:

http://sms.skylinelabs.cc:20003/getsentrcdV2?account=***&sign=***&datetime=***&date=***&begintime=***&endtime=***&startindex=***

请求参数说明:

参数说明是否必填类型
version协议版本号否(默认1.0)String
accountAPI密钥String
signMD5签名(详细说明见接口说明Sign签名生成方法)String
datetime时间字符串【年月日时分秒】,非时间戳String
date查询日期字符串【年月日】否(默认当天日期)String
begintime查询起始时间【时分秒】String
endtime查询结束时间【时分秒】否(默认开始时间后1小时时间)String
startindex查询的起始下标(单次查询默认最多返回50000个结果,超过50000分多次查询时可用到此字段)否(默认0)INT

接口成功返回示例:

{"status":0, "totalcnt":2, "retcnt":2, "success":1, "fail":1,"array":[[1902010000230228223,"86136****1111",1548950424,0], [1902010000470228227,"8613722222222",1548950448,3]]}

返回参数说明:

参数说明类型
status查询状态 0:获取成功 -1:认证错误 -2:IP访问受限 -13:用户被锁定 -14:查询id异常 -15:查询过频繁 -16:超出时间范围限制INT
success发送成功的个数INT
fail发送失败的个数INT
array短信发送结果的数组 数组中依次包含“号码的状态查询ID、号码、发送时间(时间戳)、状态”,均为数字字符 状态: 0发送成功,非0发送失败

状态报告推送

接口说明

本接口主动推送短信状态报告至发送方,短信发送完成时后,系统主动推送状态报告至发送方服务器,发送方需提供接受接口的URL,并在接收到推送后回复200 OK响应

请求方法

POST

推送消息JSON格式:

  • Content-Type:application/json
  • { "msgid":1903121607180200001, "mobile":"8613611111111", "status":0, "timestamp":1565222888000 }

请求参数说明:

参数说明类型
msgid短信消息ID,此ID为sendsms、batchsendsms接口返回的消息IDINT
mobile短信接收号码String
status短信状态: 0发送成功,非0发送失败INT
timestamp短信发送完成时间(时间戳)INT

常见问题分析

账号错误

{“status”:-1,”desc”:”user not exist”}

原因分析

1) 发送短信接口传入的账号错误,需核对账号是否正确。 2) POST提交未将account、sign、datetime放至URL中。

认证错误

{“status”:-1,”desc”:”auth failed”}

原因分析

1) 发送短信接口传入的密码错误,需核对密码是否正确,密码为认证秘钥,非登录密码,认证秘钥需登录天一泓短信系统获取。 2) 发送接口中传入的sign参数中使用的datetime与接口传入的datetime不一致。 3) http协议未启用,可登陆天一泓短信系统,我的设置-API设置 中启用。

时间过期

{“status”:-1,”desc”:”timestamp expires”}

原因分析

发送短信接口传入的datetime过期,datetime需使用GMT+8当前半小时内的时间,且时间格式是年月日时分秒,非时间戳,如请求服务器非GMT+8时区,注意需作时间转换。

号码错误

{“status”:-9}

原因分析

发送接口传入的号码错误,常见原因如下: 1) 接收号码未加国家码或国家码后面加了0,天一泓系统要求传入的号码为加上国家码的完整国际号码,正确示例:6281211111111,错误示例:81211111111、081211111111、62081211111111。 2) 接收号码未在商务合作范围内,例如商务只合作印尼,那此账户仅能发送印尼号码,其他国家号码会返回-9。 3) 接收号码在商务合作范围,且号码格式无误,那么此号码的号段未在天一泓系统的号段允许中,请确认号码是否存在,如确认存在,可联系天一泓商务添加。

频率限制

{“status”:-15,”desc”:”Frequent Queries “}

原因分析

getsentrcd接口查询频率超过限制,查询频率最高允许每分钟1次查询,需控制查询频率在允许范围内。