API帮助中心

HTTP API接口说明（HTTP）

注：本接口的编码格式：utf8

1. 查询余额getbalance

支持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″}

2. 群发短信 sendsms

支持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调用方式：(多个号码，单个短信内容)

http://Ip:20003/sendsms

body:{“account”:”chenkc”,”password”:”123456″,”content”:”test”,”smstype“:0,”mmstitle“:”mmstitle decs“，”numbers”:”123456″}

3、http post调用方式：(使用数组smsarray传递多个号码，多个短信内容)

http://Ip:20003/sendsms

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]]}

3. 查询短信发送结果 getreport

支持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限制

4. 接收短信 getsms

支持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, “********************************”]]}

5. 主动往客户的url推送发送报告

在系统上可以配置消费用户的推送报告的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”]]}

6. 创建短信任务发送短信

支持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方式请求。