HTTP API接口说明(HTTP)
注:本接口的编码格式:utf8
支持http get方式来获取系统中对应账号的余额。
查询到的数据(HTTP消息的body段)是由一个或者多个字段组成的JSON格式字符串。HTTP头参数“Content-Type”的值为“application/json;charset=utf-8”。
调用方式:
http://Ip:20003/getbalance?account=***&password=***
输入参数
参数 | 说明 | 是否必填 | 类型 |
version | 协议版本号 | 否(默认1.1) | String |
account | 帐号 | 是 | String |
password | 1、服务器不加密时,则为明文密码 2、服务器加密时,则为MD5密码 Md5值 = md5(用户名+明文密码+seq+time+协商key) 协商的key由服务端提供 | 是 | String |
seq | 序列号,每次请求递增,初始值为1 | 服务器要求加密时必填 | Int |
time | 请求发起的时间戳 | 服务器要求加密时必填 | Int |
输出参数:
参数 | 说明 | 类型 |
status | 查询状态 0:获取成功 -1:认证错误 -2:Ip访问受限 | INT |
balance | 实际账户的余额 | String |
gift | 赠送账户余额 | String |
回复示例:
{“status”:0, “balance”:”99.990000″, “gift”:”50.00000″}
支持http get或post方式来提交发送短信,get发送一次性最多提交100个号码,post方式一次性最多提交10000个号码。
提交的结果数据(HTTP消息的body段)是由一个或者多个字段组成的JSON格式字符串。HTTP头参数“Content-Type”的值为“application/json;charset=utf-8”。
1、http get调用方式:
http://Ip:20003/sendsms?account=***&password=***&smstype=0&numbers=10010,1008611&content=***&mmstitle=mmstitle_text
2、http post调用方式:(多个号码,单个短信内容)
body:{“account”:”chenkc”,”password”:”123456″,”content”:”test”,”smstype“:0,”mmstitle“:”mmstitle decs“,”numbers”:”123456″}
3、http post调用方式:(使用数组smsarray传递多个号码,多个短信内容)
body:{“account”:”chenkc”,”password”:”123456″,”smsarray”:[
{“content”:”***”,”smstype“:0,”mmstitle“:”***”,”numbers”:”***”,”sender”:”***”},
{“content”:”***”,”smstype“:0,”mmstitle“:”***”,”numbers”:”****,****”},
…
{“content1″:”***”,”smstype“:0,”mmstitle“:”***”,”numbers”:”****”}
]}
备注:需要把所有的参数以json的方式放在body中
输入参数:
参数 | 说明 | 是否必填 | 类型 |
version | 协议版本号 | 否(默认1.0) | String |
account | 帐号 | 是 | String |
password | 1、服务器不加密时,则为明文密码 2、服务器加密时,则为MD5密码 Md5值 = md5(用户名+明文密码+seq+time+协商key) 协商的key由服务端提供 | 是 | String |
seq | 序列号,每次请求递增,初始值为1 | 服务器要求加密时必填 | Int |
time | 请求发起的时间戳 | 服务器要求加密时必填 | Int |
smstype | 短信类型(0:普通短信,1:彩信) | 否(默认0) | Int |
mmstitle | 彩信标题(get方式需要做urlEncode) | 否 | String |
sender | 发件人 | 否 | String |
numbers | 短信接收号码,多个号码之间以英文逗号分隔(get最多100个,post最多10000个) | 和smsarray二选一 |
|
content | 发送内容(get方式需要做urlEncode) | 和smsarray二选一 | String 长度不能超过1024 |
sendtime | 定时发送时间(为空为立即发送) 比如:20171001123015,表示2017年10月1日12时30分15秒 | 和smsarray二选一 | String(14) |
smsarray | 一次提供多个号码多个内容的数组 | 否 |
|
数组smsarray参数:
参数 | 说明 | 是否必填 | 类型 |
smstype | 短信类型(0:普通短信,1:彩信) | 否(默认0) | Int |
mmstitle | 彩信标题(get方式需要做urlEncode) | 否 | String |
sender | 发件人 | 否 | String |
numbers | 短信接收号码,多个号码之间以英文逗号分隔 | 是 |
|
content | 发送内容(get方式需要做urlEncode) | 是 | String 长度不能超过1024 |
sendtime | 定时发送时间(为空为立即发送) 比如:20171001123015,表示2017年10月1日12时30分15秒 | 否 | String(14) |
输出参数:
参数 | 说明 | 类型 |
status | 发送提交状态 0:获取成功 -1:认证错误 -2:Ip访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足,不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因,批量提交出错,请与管理员联系 -13;用户被锁定 | INT |
success | 提交成功的次数 | INT |
fail | 提交失败的个数 | INT |
array | 提交短信成功的数组 数组中依次包含“号码、号码的发送结果查询ID”,数据均为数字字符 |
|
备注:提交发送短信成功后,系统会给提供成功的号码生成一个Id,以后客户可以根据这个Id来查询该短信的发送结果。
回复示例:
{“status”:0, “success”:2, “fail“:0, “array”:[[10010,1], [1008611,2]]}
支持http get方式来查询短信发送状态,get发送一次性最多提交200个号码。
备注:
2020年12月31日,添加支持送达报告的获取,可以通关过配置文件EIMS_HTTP_GET_DELIVER_REPORT这个选项关闭送达报告的功能
查询的结果数据(HTTP消息的body段)是由一个或者多个字段组成的JSON格式字符串。HTTP头参数“Content-Type”的值为“application/json;charset=utf-8”。
调用方式:
http://Ip:20003/getreport?account=***&password=***&ids=1,2
输入参数:
参数 | 说明 | 是否必填 | 类型 |
version | 协议版本号 | 否(默认1.0) | String |
account | 帐号 | 是 | String |
password | 1、服务器不加密时,则为明文密码 2、服务器加密时,则为MD5密码 Md5值 = md5(用户名+明文密码+seq+time+协商key) 协商的key由服务端提供 | 是 | String |
seq | 序列号,每次请求递增,初始值为1 | 服务器要求加密时必填 | Int |
time | 请求发起的时间戳 | 服务器要求加密时必填 | Int |
ids | 指定查询发送结果的短信id(该id在提交时由系统返回),多个号码之间以英文逗号分隔(最多200个) | 是 | String |
输出参数:
参数 | 说明 | 类型 |
status | 发送提交状态 | INT |
success | 发送成功的条数 | INT |
fail | 发送失败的条数 | INT |
unsent | 未发送条数 | INT |
sending | 正在发送的条数 | INT |
deliverSuc | 送达成功的条数 | INT |
deliverFail | 送达失败的条数 | INT |
deliverTimeout | 超时送达的条数 | INT |
nofound | Id没有找到的条数 |
|
array | 短信发送结果的数组 数组中依次包含“号码的状态查询ID(数字)、号码(字符串)、发送时间(数字)、发送状态(数字),送达时间(数字),送达状态(数字)” 发送状态: 0:发送成功, 1:未发送, 2:正在发送 其他:发送失败 送达状态: 0:不需要报告 1:已经发送但是还未送达 2:送达失败 3:送达成功 4:送达超时 5:其他未知状态 |
|
备注:提交发送短信成功后,系统会给提供成功的号码生成一个Id,以后客户可以根据这个Id来查询该短信的发送结果。
回复示例:
{“status”:0, “success”:1, “fail“:1, “unsent”:0, “sending”:0, “nofound”:0,
“array”:[[1,“10010”,20171001123015,0, 0,0],
[2,“1008611”,20171001123015,0,20171001123025,3]]}
备注:上述数组中的[1,10010,20171001123015,0],各个字段分别对应:号码的状态查询ID、号码、发送时间、状态。
状态编码 | 英文描述 | 中文描述 |
0 | success | 成功 |
1001 | NoRoute | 没有路由 |
1002 | NoChannel | 没有通道 |
1003 | NoBablance | 余额不足 |
1004 | Unkown | 未知 |
1005 | Send Refuse | 对端拒绝发送 |
1006 | Send Timeout | 对端发送超时 |
1007 | Server Timeout | 服务端发送超时 |
1008 | SupplierMccMncLimit | 供应商没有费率 |
1009 | ConsumerMccMncLimit | 消费用户没有费率 |
1010 | NoSupplier | 没有供应商 |
1011 | Black Number | 黑号码限制 |
1012 | Sensitive Words | 敏感词限制 |
1013 | Daliy Limit | 每天发送书限制 |
1014 | DestinationMccMncLimit | 号码MccMnc找不到 |
1016 | SMS Template Limit | 短信模块限制 |
1017 | SupplierNoBablance | 供应商余额不足 |
1018 | UserProfitLimit | 用户利润不足 |
1019 | ChannelProfitLimit | 通道利润不足 |
1020 | MccNumberLengthLimit | MccMnc号码长度限制 |
1021 | Job no found | 没找到任务 |
1022 | china sms limit | 中国短信受限 |
1023 | RouteMccMncLimit | 路由MccMnc限制 |
|
|
|
支持http get方式来查询系统接收到短信,get发送一次性最多查询50条接收短信。
查询的结果数据(HTTP消息的body段)是由一个或者多个字段组成的JSON格式字符串。HTTP头参数“Content-Type”的值为“application/json;charset=utf-8”。
调用方式:
http://Ip:20003/getsms?account=***&password=***&start_time=1543570302
输入参数:
参数 | 说明 | 是否必填 | 类型 |
version | 协议版本号 | 否(默认1.0) | String |
account | 帐号 | 是 | String |
password | 1、服务器不加密时,则为明文密码 2、服务器加密时,则为MD5密码 Md5值 = md5(用户名+明文密码+seq+time+协商key) 协商的key由服务端提供 | 是 | String |
seq | 序列号,每次请求递增,初始值为1 | 服务器要求加密时必填 | Int |
time | 请求发起的时间戳 | 服务器要求加密时必填 | Int |
start_time | 开始查询的时间戳 | 否 | INT |
输出参数:
参数 | 说明 | 类型 |
status | 查询请求状态 0:获取成功 -1:认证错误 -2:Ip访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足,不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因,提交出错,请与管理员联系 -13;用户被锁定 | INT |
cnt | 查询到的接收短信条数(一个get请求最多不会超多50条) | INT |
array | 提交短信成功的数组 数组中依次包含“id(系统中唯一的id),发送号码、接收号码、接收时间、短信内容”, 备注:短信内容需要做base64解码,才能得到正确的utf8编码的短信内容 ;若是有收到两条id相同的短信,则可认为是重复的接收短信,客户一旦查询过的接收短信,第二次查询不会重复返回。 |
|
回复示例:
{“status”:0, “cnt“:2,
“array”:[[1,“10010”,”123456“,20171001123015, “********************************”],
[2,”1008611″,”123456“,20171001123015, “********************************”]]}
在系统上可以配置消费用户的推送报告的url,系统发送完短信后,就会将短信的发送结果,以put的方式推送到客户指定的url,报告的内容以json的格式放在请求的body中。一次性最多推送50条发送报告。
Json消息格式
参数 | 说明 | 类型 |
type | 该消息的字符串类型,默认值:“report” | STRING |
cnt | 本次推送中包含的报告条数(一个请求最多不会超多50条) | INT |
array | 发送报告的数组 数组中依次包含 1、 id(发送时返回的id,整形) 2、 发送号码(字符串) 3、 发送时间(长整形) 4、 发送结果(整形,0成功,非0则失败) 5、 原因(字符串) | 数组 |
推送示例:
{“type”:”report”,”cnt”:2,”array”:[[1,”1234545456″,20180801123015,0,”success”],[2,”2356844545″,20180801223015, 1, “no balance”]]}
支持post方式来创建发送短信的任务。
提交的结果数据(HTTP消息的body段)是由一个或者多个字段组成的JSON格式字符串。HTTP头参数“Content-Type”的值为“application/json;charset=utf-8”。
Url: http://Ip:20003/smsjob
body示例:
1、创建一个立即短信任务,号码直接放在numbers字段中
body:{“account”:”chenkc”,”password”:”123456″,”job”:”job_with_number”,”numbersrc”:0,”numbers”:”123456,3444,54535″,”content”:”test”}
2、创建一个立即短信任务,numbers字段中存放的是一个号码文件的url
body:{“account”:”chenkc”,”password”:”123456″,”job”:”job_with_number”,”numbersrc”:1,”numbers”:”http://ip:port/sms.xls”,”content”:”test”}
3、创建一个周期为10次的每天9点触发的短信任务,numbers字段中存放的是一个号码文件的url
body:{“account”:”chenkc”,”password”:”123456″,”job”:”job_with_number”,”jobtype”:3,”period”:10,”hour”:9, “min”:0, “numbersrc”:1,”numbers”:”http://ip:port/sms.xls”,”content”:”test”}
备注:需要把所有的参数以json的方式放在body中,url文件仅支持xls,不支持xlsx
输入参数:
参数 | 说明 | 是否必填 | 类型 | 备注 |
version | 协议版本号 | 否 | String | 默认1.0 |
account | 帐号 | 是 | String |
|
password | 1、服务器不加密时,则为明文密码 2、服务器加密时,则为MD5密码 Md5值 = md5(用户名+明文密码+seq+time+协商key) 协商的key由服务端提供 | 是 | String |
|
seq | 序列号,每次请求递增,初始值为1 | 否 | Int | 服务器要求加密时必填 |
time | 请求发起的时间戳 | 否 | Int | 服务器要求加密时必填 |
job | 任务名称 | 是 | String |
|
jobtype | 任务类型 0:立即 1:定时 2:间隔 3:每天 4:每周 5:每月 | 否 | Int | 默认0 |
period | 周期任务的周期数 | 否 | Int | 1、该值只对任务类型大于2时生效; 2、周期任务若周期和计划结束时间都为空,那么默认周期数为1 |
interval | 间隔多久触发一次间隔的短信任务 | 否 | Int | 当任务类型为2间隔时为必填项; 时间单位:分钟 |
min | 分钟 | 否 | Int | 1、取值范围:0-59 2、当任务类型为2-5时为必填项 |
hour | 小时 | 否 | Int | 1、取值范围:0-23 2、当任务类型为2-5时为必填项 |
day | 天 | 否 | Int | 1、取值范围:1-31 2、当任务类型为2、3、5时为必填项 |
week | 周 | 否 | Int | 1、取值范围:1–7 2、当任务类型为4时为必填项 |
mon | 月 | 否 | Int | 1、取值范围:1–12 2、当任务类型为5时为必填项 |
planstarttm | 计划发送时间戳 | 否 | Int | 计划发送时间戳,为空表示立即发送 |
planendtm | 计划结束时间戳 | 否 | Int | 计划结束时间戳 |
retry | 重试次数 | 否 | Int | 短信发送失败的最大重试发送次数 默认0不重发 |
flash | 闪信 | 否 | Int | 是否为闪信,0:否 1:是 |
content | 短信内容 | 是 | String | 全局的短信内容 |
numbersrc | 号码来源 | 是 | INT | 0:numbers字段就是号码 1:numbers是个url(文件仅支持xls,不支持xlsx) |
numbers | 接收号码 | 是 | String | 短信的接受号码 1、长度不超时过4*1024 2、多个号码使用英文逗号分开; |
senderId | 发送者ID | 否 | String | 任务的senderId |
smstype | 短信类型 | 否 | Int | 0:普通短信,1:彩信 (默认0) |
mmstitle | 彩信标题 | 否 | String | 当短信类型是彩信是才必填 |
输出参数:
参数 | 说明 | 类型 |
status | 发送提交状态 0:成功 -1:认证错误 -2:Ip访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足,不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因,批量提交出错,请与管理员联系 -13:用户被锁定 -14:号码来源异常 -15:任务名称异常,为空或长短超过64 -16:短信任务类型异常 -17:其他错误 | INT |
jobid | 成功创建任务的Id值 | INT |
回复示例:
{“status”:0, “jobid“:2}
KawiFong cloud开放了丰富的接口,开发者可以借助接口能力,实现企业触达服务与PaaSoo的集成。支持的能力可通过目录导航快速预览,目录树按功能块聚合归类,如国际短信、国际彩信等。所有 REST API可以通过HTTPS及HTTP方式、JSON数据格式、UTF8编码请求。为了保证数据的隐私安全,我们强烈建议您使用HTTPS方式请求。