国际验证码/通知短信

1、单条短信发送

请求头Content-Type:application/x-www-form-urlencoded
请求方式:POST 返回值:JSON

备注:黑名单等拦截错误实时返回

地址:https://api.3yit.com/api/send-sms-single

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
mobile手机号176xxxxxxxx(支持md5和aes)
content短信内容【签名】验证码123(支持aes)
signature签名(和密码二选一即可,点击查看签名算法)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者,http接口文档中查看)
ext扩展号123


结果

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
msg_id消息id,用来获取状态报告时候匹配是哪条消息,成功返回17
data失败有返回,详情见错误表WL:NMLJ


postman-2.png

2、批量短信发送

请求头Content-Type:application/x-www-form-urlencoded
请求方式:POST   返回值:JSON

备注:黑名单等拦截错误实时返回,一次最多提交一万条

地址:https://api.3yit.com/api/send-sms-batch

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
mobiles手机号176xxxxxxxxx,171xxxxxxxxx
content短信内容【测试】验证码123
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者-http接口文档中查看)
ext扩展号123


结果

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
msg_id消息id,用来获取状态报告时候匹配是哪条消息,批量发送的时候msg_id和该批次中的手机号形成唯一标志,成功返回17
failed_data发送号码中失败的号码对应的错误码,全部成功则为空数组{"176xxxxxxxxx":"WL:CWHM","171xxxxxxxxx":"WL:CWHM"}


postman-3.png

3、变量短信发送

请求头Content-Type:application/x-www-form-urlencoded
请求方式:POST 返回值:JSON

备注:黑名单等拦截错误实时返回

地址:https://api.3yit.com/api/send-variable

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
params变量参数,多条短信以英文;分割,多个变量之间以英文,分割,变量前带上手机号176xxxxxxxxx,822233;175xxxxxxxxx,656552
content短信内容【测试】验证码${Text}
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者-http接口文档中查看)
ext扩展号123


结果

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
msg_id消息id,用来获取状态报告时候匹配是哪条消息,批量发送的时候msg_id和该批次中的手机号形成唯一标志,成功返回17
failed_data发送号码中失败的号码对应的错误码,全部成功则为空数组{"176xxxxxxxxx":"WL:CWHM","171xxxxxxxxx":"WL:CWHM"}


postman-4 (1).png

4、一对一批量发送

请求头Content-Type:application/x-www-form-urlencoded
请求方式:POST 返回值:JSON

备注:黑名单等拦截错误实时返回,一次最多提交一万条

地址:https://api.3yit.com/api/send-biunique

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
params一对一参数,json格式key是手机号,value是内容{"17655555555":"测试111","17666666666":"测试222"}
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者,http接口文档中查看)
ext扩展号123


结果

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
msg_id消息id,用来获取状态报告时候匹配是哪条消息,批量发送的时候msg_id和该批次中的手机号形成唯一标志,成功返回17
failed_data发送号码中失败的号码对应的错误码,全部成功则为空数组{"176xxxxxxxxx":"WL:CWHM","171xxxxxxxxx":"WL:CWHM"}


postman-5.png

5、获取状态报告

请求头Content-Type:application/x-www-form-urlencoded
请求方式:GET  返回值:JSON

备注:每条短信状态仅可获取一次,运营商返回某条短信状态后,此接口就能拉取到,之后调用此接口将不会返回此条短信的状态,所以调用者拉到数据后需要根据 手机号+msg_id 将状态存在本地

地址:https://api.3yit.com/api/report

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者,http接口文档中查看)


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
data扩展号,调用发送接口返回的msg_id,手机号,状态,时间,售价 字段以,分隔 多条记录以|分隔123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2|123,2,17862532xxxx,DELIVRD,2021-12-23 01:02:03,0.1

6、推送状态报告

每条仅推送一次

注意事项:

推送的是utf8原始字节流

推送格式:

扩展号,调用发送接口返回的msg_id,手机号,状态,时间,售价 字段以,分隔 多条记录以|分隔

内容示范:

123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2|123,2,17862532xxxx,DELIVRD,2021-12-23 01:02:03,0.1

7、获取用户上行回复

请求方式:GET 返回值:JSON

备注:比如退订等,每条短信状态仅可获取一次,手机回复上行后,此接口就能拉取到上行数据,每个上行数据只能拉取到一次,所以调用者拉到上行后,需要将上行的内容存在本地,然后自行根据 msg_id,手机号 等信息匹配具体哪条短信产生的上行回复

地址:https://api.3yit.com/api/get-reply

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者,http接口文档中查看)


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
dataurlencode后的内容,手机号,调用发送接口返回的msg_id,扩展号,时间 字段以,分隔多条记录以|分隔TD,158114xxxx,100000006,048842426601,20220325123304|退订,1891456xxxx,100000007,0615,20211115173903

8、推送用户上行回复

每条上行回复仅推送一次

注意事项:

推送的是utf8原始字节流

推送格式:

urlencode后的内容,手机号,扩展号,时间 字段以,分隔多条记录以|分隔

内容示范:

TD,158114xxxx,048842426601,20220325123304|退订,1891456xxxx,0615,20211115173903

9、获取余额

请求方式:GET 返回值:JSON

https://api.3yit.com/api/balance

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者,http接口文档中查看)


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
data余额{"balance": "99999.89"}

10、模板报备

请求头Content-Type:application/x-www-form-urlencoded
请求方式:POST 返回值:JSON

https://api.3yit.com/api/add-template

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者-http接口文档中查看)
template模板内容【测试】您的验证码是%不要告诉他人


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
data模板id{"temp_id":123456}

11、获取模板审核状态

请求头Content-Type:application/x-www-form-urlencoded
请求方式:GET 返回值:JSON

地址:https://api.3yit.com/api/get-template-status

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者-http接口文档中查看)
template模板内容【测试】您的验证码是%不要告诉他人


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
data"0"待审核 "1"审核通过 "2"被驳回{status: "1"}}

12、签名报备

请求头Content-Type:application/x-www-form-urlencoded
请求方式:POST 返回值:JSON

地址:https://api.3yit.com/api/add-sign

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者-http接口文档中查看)
sign签名内容【测试签名2】


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
data模板id{"sign_id": 285229

13、获取签名审核状态

请求方式:GET 返回值:JSON

地址:https://api.3yit.com/api/get-sign-status

参数

参数名参数介绍示例必填
sp_id产品sp_id5xxxxx(开发者-http接口文档中查看)
signature签名(和密码二选一即可)a92569901189fxxxxxxxx957c096c432e2d47635
password密码(和签名二选一即可),通过sp_id的密码进行md5处理xxxxxxxxxxx(32位,开发者-http接口文档中查看)
sign_id签名id285229


返回值

参数名参数说明示例
code详情见错误表0
msg成功-success 错误-其他提示success
data是否通过审核 "0"待审核 "1"审核通过 "2"审核未通过{status: "1"}}

14、错误码表

发送错误码

错误码说明
10000服务出错,请稍后再试
10001参数错误,请确认
10008账号被锁定,请联系管理员确认
10011余额不足,请尽快充值
10100签名校验失败
10101您的ip不在白名单内,请确认
10102密码错误,请确认
10200产品sp_id必须填写
10201手机号必须填写
10202短信内容必须填写
10203发送时间格式必须为UNIX时间戳
10208短信进拦截,具体原因参考data字段
10209触发防刷,请调整配置


发送状态错误码

错误码说明
WL:MBLJ短信内容匹配到了模板,并且此模板类型是拦截
WL:MBSH命中审核模板
WL:NMLJ短信内容没有匹配到模板,并且用户的模板审核方式是未匹配到就进拦截
WL:NMSH短信内容没有匹配到模板,并且用户的模板审核方式是未匹配到就进审核
WL:KHLJ命中空号,进拦截
WL:QHLJ命中用户签名黑名单,进拦截
WL:SHLJ命中用户SPID黑名单,进拦截
WL:CHLJ命中系统产品黑名单,进拦截
WL:CWHM错误号码
WL:QWBB签名未报备,进拦截
WL:MQM需要签名但没有,进拦截
WL:CS超过限速了
WL:ZJLJ不匹配任何模板,直接拦截
WL:CMT产品未配置相应通道,进拦截
WL:CDQC通道不支持该地区发送,进拦截
WL:CGMT产品通道池中没有相应通道,进拦截
WL:CNH所选的通道不健康,进拦截
WL:TCLJ不在发送时间段,进拦截
WL:TCSH不在发送时间段,进审核
WL:CPL超频限制


15、签名生成规则

第一步:准备QueryString

1、将所有参数(除了signature)按照key排序(顺序)

2、将排序好的参数key和值进行URLEncode,之后再增加三种字符替换:加号(+)替换成 %20、星号(*)替换成 %2A、%7E 替换回波浪号(~)

3、将格式化后的key和值按照key + "=" + 值进行拼接成字符串QueryString,多个参数间用&连接,例:”a=%E5%93%88%E5%93%88&b=haha”

4、在上一步得到的QueryString前拼接上请求方式,生成新的QueryString,HTTPMethod + "&" + URLEncode("/") + "&" + QueryString


第二步:准备signature

1、将所有参数(除了signature)按照key排序(顺序)

2、将排序好的参数key和值进行URLEncode,之后再增加三种字符替换:加号(+)替换成 %20、星号(*)替换成 %2A、%7E 替换回波浪号(~)

3、将格式化后的key和值按照key + "=" + 值进行拼接成字符串QueryString,多个参数间用&连接,例:”a=%E5%93%88%E5%93%88&b=haha”

4、在上一步得到的QueryString前拼接上请求方式,生成新的QueryString,HTTPMethod + "&" + URLEncode("/") + "&" + QueryString

16、AES加密规则

aes加密发送,需要同时分别加密手机号字段和内容字段

https://api.3yit.com/api/send-sms-single-aes

操作流程

1、发送地址在原来的地址加上-aes,地址:https://api.3yit.com/api/send-sms-single-aes

2、先向客服索要加密key,然后自行生成iv,用AES-128-CBC将手机号或者内容进行加密,并对加密的数据进行base64处理获得字符串s1

3、将生成的iv也进行base64处理生成字符串s2

4、将两个字符串进行json处理生成如下的json字符串s3:"{"iv":"s2","value":"s1"}"

5、将上述得到的s3进行base64处理,然后放入相应post数据字段中代替未加密的数据

 $cipher = 'AES-128-CBC';

        $iv = random_bytes(openssl_cipher_iv_length($cipher));

        $value = openssl_encrypt($value, $cipher, $key, 0, $iv);

        if ($value === false) {
            throw new RuntimeException('Could not encrypt the data.');
        }

        $iv = base64_encode($iv);

        $json = json_encode(compact('iv', 'value'), JSON_UNESCAPED_SLASHES);

        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new RuntimeException('Could not encrypt the data.');
        }

        return base64_encode($json);

17、SMPP提交教程

SMPP(Short Message Peer-to-Peer)是短消息点对点协议,又称之为端口对端口协议,是一个开放的国际行业标准协议,由SMS论坛制定。它旨在为外部短消息实体(ESME)、路由实体(RE)和消息之间的短消息数据传输提供灵活的数据通信接口中心(MC)。它是应用程序可以向移动设备发送和从移动设备接收SMS消息的一种方式。

SMPP协议主要用于国际短信上,在全球范围内被广泛应用于短信的接收和提交,具备较高的安全性,比起其他协议可能更规范和严谨。


一、前期准备工作

在开始使用SMPP协议进行短信服务之前,有几个关键的准备步骤需要完成。

1、首先,您需要在智慧云信短信平台注册一个账号。注册成功后,您还需要提交实名认证资料

2、接下来,在您的账号中,找到对应的产品国际短信/国际验证码短信,提交短信签名以及短信模版以供审核。


二、获取并配置连接参数

完成上述准备工作后,下一步是获取并配置SMPP连接参数。

1、请登录到智慧云信短信平台,并导航至【短信验证码】-开发者中心-SMPP接口参数部分。

image.png

2、在这里,您将看到一系列重要的连接参数,包括服务器IP、端口号、长号码、账号(SPID)、接口密码、流速以及最大链接数等。请注意,这些参数都是由系统自动生成的,如链接数、流速等不符合需求,可联系客服修改。

3、获取到这些参数后,您需要将它们配置到您的系统中。请根据您的系统开发文档或技术支持的指导进行配置,以确保一切设置正确无误。


三、查看与测试链接情况

配置完成后,下一步是查看和测试链接情况,以确保您的系统已经成功接入了智慧云信的短信网关。

1、当您完成配置并启动连接后,系统应该会显示链接成功的消息。如果链接成功,这意味着您的系统已经成功与智慧云信的短信网关建立了通信。

2、为了确保一切正常运行,建议您发送几条测试短信,检查是否能够正常接收和发送。如果遇到任何问题,智慧云信的技术支持团队将随时为您提供帮助和解决方案。

image.png

通过遵循以上步骤,您应该能够顺利地通过SMPP协议接入智慧云信的短信网关,并享受高效、稳定的短信服务。