短信api接口文档

短信接口描述 / api错误代码 / 开发语言代码示例 / 注意事项 /

短信接口文档

测试时,请使用正式内容进行测试,请勿给同一手机号连续发送相同内容,运营商已进行规则调整以应对短信炸弹问题。

所有短信均有监控,请勿发送以下内容(营销广告、不合法,要挟、虚假、私人信息、滥发、邀请类)。

网页应用用于手机验证 ,请务必增加图形验证(以防止被人利用,被用于短信轰炸用途),否则不予以接入。

 

发送之前请务必仔细阅读内容审核的相关规则     点此查看

 

接口列表

地址 描述
http://sms-api.luosimao.com/v1/send.[json|xml] 发送单条短信 (验证码、触发类)
http://sms-api.luosimao.com/v1/send_batch.[json|xml] 批量发送(通知,提醒类)
http://sms-api.luosimao.com/v1/status.[json|xml] 账户信息(余额查询)

 

编码

统一使用 UTF-8 编码,请确保您的文件编码及传入参数的格式

 

接口通用信息

验证方式

Luosimao使用 HTTP Basic Auth 方式进行身份验证,使用api作为验证用户名,API key是验证密码,在管理中心->短信服务->触发发送下查看。

(请注意验证密码需在后台提取的API key之前加上 key-  请仔细查看下列示例)

 

验证示例
curl --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0

 

返回格式

luosimao api 支持xml、json格式的返回结果,请求时使用不同后缀名即可

 

不同返回格式请求url示例
json返回:
http://sms-api.luosimao.com/v1/send.json

xml返回:
http://sms-api.luosimao.com/v1/send.xml

 

短信签名

短信签名指附加在短信内容末尾的署名信息,使用发送者的公司名或产品名,格式为:【XXXXX】,签名体正文部分为3-8个汉字,请勿使用纯英文或中英文签名

例如一条完整的短信请求内容:您的验证码是123456,请尽快完成验证。【铁壳网络】
【铁壳网络】即为短信签名

 

应运营商要求,接收到的短信签名自动前置,接收到的实际短信为:
【铁壳网络】您的验证码是123456,请尽快完成验证。

 

短信签名可在管理中心 - 短信 - 签名管理 下面进行添加可查看

 

短信模板

短信模板指一个短信内容的范式,符合这个模板的内容免审核,否则将走审核流程,建议将常规事务性短信提前添加短信模板。

模板请登录管理中心 - 短信 - 短信模板处进行添加并管理,审核通过后即可使用。


一条完整的短信模板内容:
您的验证码是###,请尽快完成验证。【铁壳网络
 

API key的获取

登录后进入管理中心,在短信服务 -> 触发短信 下可查看自己的短信API KEY,并可进行更换

 

IP白名单

登录后进入管理中心,在短信服务 -> 触发短信 下可设置IP白名单,不在该IP白名单中的IP发起的接口请求将全部被拒绝。强烈建议设置!

返回示例:

{"error":-50,"msg":"Ip denied:222.72.169.63"}

 

发送短信接口详细

接口地址
http://sms-api.luosimao.com/v1/send.[json|xml]

 

HTTP请求方式

POST

 

请求参数
名称 类型 是否必须 示例值 描述
mobile String 13761428268 目标手机号码
message String 验证码:321123【铁壳测试】 短信内容

 

返回结果
名称 类型 是否必须 示例值 描述
error Number 0 错误码
msg String ok 错误码描述
batch_id String 09-B0966DD4-FD28-43C3-94A8-F762B2269B72 批次号,管理中心开启状态推送后,请返回此参数用于接收状态回执的对应
hit String 年化收益 敏感词,error为-31时会出现

 

返回示例
json格式:

{"error":0,"msg":"ok"}

xml格式:

<response>
<error>-10</error>
<msg>Auth failed.</msg>
</response>

 

错误码
错误码 错误描述 解决方案
-10 验证信息失败 检查api key是否和各种中心内的一致,调用传入是否正确
-11 用户接口被禁用 滥发违规内容,验证码被刷等,请联系客服解除
-20 短信余额不足 进入个人中心购买充值
-30 短信内容为空 检查调用传入参数:message
-31 短信内容存在敏感词 接口会同时返回  hit 属性提供敏感词说明,请修改短信内容,更换词语
-32 短信内容缺少签名信息 短信内容末尾增加签名信息eg.【公司名称】
-33 短信过长,超过300字(含签名) 调整短信内容或拆分为多条进行发送
-34 签名不可用 在后台 短信->签名管理下进行添加签名
-40 错误的手机号 检查手机号是否正确
-41 号码在黑名单中 号码因频繁发送或其他原因暂停发送,请联系客服确认
-42 验证码类短信发送频率过快 前台增加60秒获取限制
-50 请求发送IP不在白名单内 查看触发短信IP白名单的设置

 

状态回执(短信接收状态)

在后台可查看短信的接收状态,也可在推送设置中设置回执的推送地址

短信的接收状态将以GET请求的形式推送到指定的接口地址上,具体推送的参数如下

参数名 参数解释 示例
batch_id 发送批次号 09-B0966DD4-FD28-43C3-94A8-F762B2269B72
mobile 手机号 13761428267
status 接收状态 DELIVRD 接收成功 UNDELIV 接收失败(信号不良,关停机,黑名单等异常情况)

 

接收回执说明:

回执代码 描述
DELIVRD 成功接收
UNDELIV 接收失败

 

 

批量发送接口详细

接口地址
http://sms-api.luosimao.com/v1/send_batch.[json|xml]

 

HTTP请求方式

POST

 

请求参数
名称 类型 是否必须 示例值 描述
mobile_list String 13761428268,18521513391 目标手机号码列表,多个号码使用","分隔
message String 提醒:您的账号即将到期,请及时充值【铁壳测试】 短信内容
time String 2016-04-01 12:30:00 定时发送的时间,定时的发送任务可以在发送前10分钟在发送历史界面进行取消(仅限提交当天)

 

返回结果
名称 类型 是否必须 示例值 描述
error Number 0 错误码
msg String ok 错误码描述

 

返回示例
json格式:

{"error":0,"msg":"ok"}

xml格式:

<response>
<error>-10</error>
<msg>Auth failed.</msg>
</response>

 

错误码
错误码 错误描述 解决方案
-10 验证信息失败 检查api key是否和各种中心内的一致,调用传入是否正确
-20 短信余额不足 进入个人中心购买充值
-30 短信内容为空 检查调用传入参数:message
-31 短信内容存在敏感词 修改短信内容,更换词语
-32 短信内容缺少签名信息 短信内容末尾增加签名信息eg.【铁壳测试】
-34 签名不可用 在后台 短信->签名管理下进行添加签名
-40 错误的手机号 检查手机号是否正确
-43 号码数量太多 单次提交控制在10万个号码以内
-50 请求发送IP不在白名单内 查看IP白名单的设置
-60 定时时间为过去 检查定时的时间,取消定时或重新设定定时时间

 

查询账户余额

接口地址
http://sms-api.luosimao.com/v1/status.[json|xml]

 

HTTP请求方式

GET

 

请求参数

 

返回结果
名称 类型 示例值 描述
error Number 0 错误码
deposit Number 20 短信账户余额

 

错误码
错误码 错误描述 解决方案
-10 验证信息失败 检查api key是否和管理中心内的一致,调用传入是否正确

 

 

短信验证业务流程