接口文档

  • 余额查询
  • 群发短信
  • 批量群发短信
  • 状态报告查询
  • 批量报告查询
  • 状态报告推送
  • 常见问题分析

接口说明


  • 一、名称:天一泓国际短信IMFS接口说明
  • 二、接口协议:HTTP
  • 三、编码格式:UTF8
  • 四、请求方法:GET、POST
  • 五、Content-Type:application/json;charset=UTF-8
  • 六、Sign签名生成方法:将账号、API秘钥、请求时间拼成字符串,做MD5加密,MD5使用32位小写
  • 示例:
参数 方法 Sign
account:test
password:123456
datetime:20190101120000
MD5(test12345620190101120000) 6ac4928d8d0c3c5ba75981b539c52152
  • 注:API秘钥(password)为认证秘钥,非登录密码,可登录天一泓短信系统查询获取;请求时间(datetime)需传GMT+8当前半小时内时间,格式为年月日时分秒,而非时间戳。

余额查询


  • 一、接口名称:getbalanceV2
  • 二、接口说明:本接口用于查询账户余额信息
  • 三、请求方法:GET
  • 四、调用方式:http://sms.skylinelabs.cc:20003/getbalanceV2?account=***&sign=***&datetime=***
  • 五、请求参数说明:
参数 说明 是否必填 类型
version 协议版本号 否(默认1.0) String
account 账号 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"}
  • 注:POST请求account、sign、datetime参数需放在URL中,不可放在json中提交
  • 六、请求参数说明:
参数 说明 是否必填 类型
version 协议版本号 否(默认1.0) String
account 账号 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 账号 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 账号 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 账号 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