Slide

首页

帮助中心

短信API

签名鉴权

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

示例:

参数

api认证名:bDqJFiq9

api认证密钥:7bz1lzh9

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

方法

MD5(bDqJFiq97bz1lzh91630468800)

Sign

05d7a50893e22a5c4bb3216ae3396c7c

请求头参数:

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

状态码

status:响应状态码说明

状态码 参数说明
0 success
-1 认证错误
-2 IP访问受限
-3 短信内容含有敏感字符
-4 短信内容为空
-5 短信内容过长
-6 不是模板的短信
-7 号码个数过多
-8 号码为空
-9 号码异常
-10 客户余额不足,不能满足本次发送
-11 定时时间格式不对
-12 由于平台的原因,批量提交出错,请与管理员联系
-13 用户被锁定
-14 Field为空或者查询id异常
-15 查询过频繁
-16 timestamp 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请求内容需要urlEncode String
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 提交号码对应平台msgId String
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
msgIds sendSms接口响应返回的平台id,多个用英文逗号分隔,单次查询最大200个msgId String

请求示例:

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
nofound Id未找到的条数 String
array 找到发送结果的json集合 JSONArray
msgId 提交号码对应平台msgId String
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 提交号码对应平台msgId String
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 提交号码对应平台msgid Long
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:20210402120000 MD5(test12345620210402120000) c02190a4f5a4d2a266023f002011ca0a

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

余额查询

接口名称

getbalanceV2

接口说明

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

请求方法

GET

调用方式:

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

请求参数说明:

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

接口成功返回示例:

{"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
account API密钥 String
sign MD5签名(详细说明见接口说明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
nofound Id没有找到的条数 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
account API密钥 String
sign MD5签名(详细说明见接口说明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接口返回的消息ID INT
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次查询,需控制查询频率在允许范围内。