接口说明文档

目录

1.概述

本文档定义了客户方与本平台的数据交互接口规范，包含数据格式，通讯协议，数据签名以及加解密规范。
本平台统一使用安全的超文本传输协议（https），并支持对敏感字段加密（支持AES算法以及国密算法SM4）

 

1.1 需要提供的信息

本平台提供客户接口调用地址(https://****)，应用号账号(appId)，以及应用号密钥(secretKey)，
客户可使用这些信息结合本文档接口说明调用服务接口。

客户可以主动发起请求，调用本平台拉取短信状态报告或者上行短信。
客户也可以按照接口规范定义服务接口，平台将主动调用接口推送状态报告以及上行短信。
此时需提供接口调用地址((https://****)和密码套件（SHA256_AES,SM3_SM4之一）给本平台人员配置。

 

1.2 接口说明

使用HTTPS协议,POST方式表单

(Content-Type:application/x-www-form-urlencoded)提交数据,返回值为json数据格式。

字符集编码统一使用UTF-8。

1.2.1 公共参数

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则

1.2.2 数据签名规则

签名算法取自encrypt字段：

   当取值为SHA256_AES时，使用HmacWithSHA256算法

   当取值为SM3_SM4时，使用HmacWithSM3算法

 

签名步骤：

1.加密之前，将原始数据除sign字段以外所有表单字段按key值升序排列

2.依次将字段以key:vale\n形式拼接，非必须字段若有值则按规则拼接，非
   必须字段若未传值则忽略拼接该字段，得到待签名数据data。

3.使用签名算法，Hmac(data,secretKey)计算出签名，使用hex编码表示。

1.2.3 数据加密规则

加密算法取自encrypt字段：

   当取值为SHA256_AES时，使用AES/ECB/PKCS5Padding

   当取值为SM3_SM4时，使用SM4/ECB/PKCS5Padding算法

加密步骤：

1.生成密钥：将应用账号，应用号密钥，时间戳三者拼接计算md5值作为
   密钥。sessionKey = MD5(appIdsecretKeytimestamp).

2.将需要加密的字段值value使用加密算法用sessionKey加密后得到密文，
   使用base64编码表示

服务端响应数据如有加密字段需要加密则也使用请求的加密算法和sessionKey进行加密

 

 

2.接口列表

 

2.1 用户提交

2.1.1 批量提交

可以提交相同内容一条或者多条目的号码的信息

请求路径:

xxxxxxxxxx
    
    

    

    

        

            

            

            
/sms/sendBatch
        
    
    
    
    
    
    

    

    
    
    

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则
mobiles	String	是	是	手机号 多个以逗号(,)分隔，最多1000个
content	String	是	是	短信内容
schTime	String	否	否	格式:yyyyMMddHHmmss 定时发送时间(选填，定时时间在90天之内) 如果不填，则为即时发送
batchId	String	是	否	客户定义消息ID 最长64位
addserial	String	否	否	扩展码(选填) 最长支持12位，如果最终号码长度超长，会截取扩展码，请根据我司建议位数提交

响应参数:

参数	类型	说明
code	String	code值为SUCCESS时说明提交成功，其他值请参考附录-提交响应错误码

返回示例:

xxxxxxxxxx
     
     

     

     

         

             

             

             
{
         
         
   "code": "SUCCESS",
         
   "data": 0
         
}
     
     
     
     
     
     

     

     
     
     

2.1.2 自定义提交

可以提交不同内容多条不同目的号码的信息

请求路径:

xxxxxxxxxx
    
    

    

    

        

            

            

            
/sms/send 
        
    
    
    
    
    
    

    

    
    
    

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则
msgs	String	是	是	Json数组字符串 形式[ {"mobile":"","content":""},…] 参考字段msgs数据
schTime	String	否	否	格式:yyyyMMddHHmmss 定时发送时间(选填，定时时间在90天之内) 如果不填，则为即时发送
batchId	String	是	否	客户定义消息ID 最长64位
addserial	String	否	否	扩展码(选填) 最长支持12位，如果最终号码长度超长，会截取扩展码，请根据我司建议位数提交

字段msgs数据:

参数	类型	说明
mobile	String	手机号
content	String	信息内容

响应参数:

参数	类型	说明
code	String	code值为SUCCESS时说明提交成功， 其他值请参考附录-提交响应错误码

 

2.2 获取状态报告

以下两种方式选择一种

2.2.1 客户发起HTTP请求来获取状态信息

请求路径:

xxxxxxxxxx
    
    

    

    

        

            

            

            
/sms/report
        
    
    
    
    
    
    

    

    
    
    

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则
number	Int	否	否	一次获取的数量，最大500. 未设置值时默认500

响应参数:

参数	类型	是否必须	是否加密	说明
code	String	是	否	code值为SUCCESS时说明请求成功 其他值请参考附录-提交响应错误码
data	String	是	是	data为json字符串加密的base64编码

data 中原始数据

参数	类型	说明
batchId	String	客户请求时提交的客户自定义消息ID
state	String	状态码DELIVRD表示成功 其余状态码请参考附录- 状态报告错误码
desc	String	说明描述
mobile	String	手机号
submitTime	String	提交时间
receiveTime	String	接收时间
addserial	String	用户扩展码

2.2.2 我方发起HTTP请求推送状态消息

接收推送状态报告需要提供接收状态的url地址，我方以POST方式推送状态，接收到状态报告数据处理成功后必须返回成功标识，否则我方会重复推送。

签名加密算法客户可以实现任意一种并告知本平台运营人员配置即可。

请求路径:

客户定义提供

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4 实现任意一种即可
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则
reports	String	是	是	json字符串加密的base64编码

reports 中原始数据

参数	类型	说明
batchId	String	客户请求时提交的客户自定义消息ID
state	String	状态码DELIVRD表示成功 其余状态码请参考附录- 状态报告错误码
desc	String	说明描述
mobile	String	手机号
submitTime	String	提交时间
receiveTime	String	接收时间
addserial	String	用户扩展码

响应参数:

参数	类型	说明
code	String	code值为SUCCESS时说 明请求成功

 

2.3 获取上行信息

以下两种方式选择一种

2.3.1 客户发起HTTP请求来获取上行信息

请求路径:

xxxxxxxxxx
    
    

    

    

        

            

            

            
/sms/mo
        
    
    
    
    
    
    

    

    
    
    

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则
number	Int	否	否	一次获取的数量，最大500. 未设置值时默认500

响应参数:

参数	类型	是否必须	是否加密	说明
code	String	是	否	code值为SUCCESS时说明请求成功 其他值请参考附录-提交响应错误码
data	String	是	是	data为json字符串加密的base64编码

data 中原始数据

参数	类型	说明
content	String	短信内容
mobile	String	手机号
moTime	String	上行时间
addserial	String	用户扩展码

2.3.2 我方发起HTTP请求推送上行消息

接收推送上行需要提供接收上行的url地址。我方以POST方式推送上行，接收到上行数据处理成功后必须返回成功标识，否则我方会重复推送。

签名加密算法客户可以实现任意一种并告知本平台运营人员配置即可。

请求路径:

客户定义提供

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4 实现任意一种即可
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则
mos	String	是	是	json字符串加密的base64编码

mos 中原始数据

参数	类型	说明
content	String	短信内容
mobile	String	手机号
moTime	String	上行时间
addserial	String	用户扩展码

响应参数:

参数	类型	说明
code	String	code值为SUCCESS时说 明请求成功

 

2.4 获取余额

请求路径:

xxxxxxxxxx
    
    

    

    

        

            

            

            
/sms/balance
        
    
    
    
    
    
    

    

    
    
    

请求参数:

参数名称	类型	是否必须	是否加密	说明
appId	String	是	否	用户应用账号，本平台提供给客户
timestamp	String	是	否	时间戳,取当前时间时间戳 格式：yyyyMMddHHmmss
encrypt	String	是	否	数据签名加密方式，从以下选项中选择 输入 SHA256_AES SM3_SM4
sign	String	是	否	请求数字签名 签名算法取决于encrypt所选择密码规 则 参考1.2.2 数据签名规则

响应参数:

参数	类型	说明
code	String	code值为SUCCESS时说明请求成功 其他值请参考附录-提交响应错误码
data	String	data为json字符串加密的base64编码

data 中原始数据

参数	类型	说明
balance	String	客户应用号余额

 

3.附录

 

3.1 提交响应错误码

错误码	描述
SUCCESS	成功
APPID_ERROR	请求APPID错误
PARAMS_ERROR	请求参数错误
IP_ERROR	不识别的IP
SPEED_ERROR	请求超速
MOBILE_ERROR	手机号为空、号码数量过多、手机号码错误
CONTENT_ERROR	短信内容错误，空或过长
SCHTIME_ERROR	定时时间过早或过久
BATCHID_ERROR	缺少自定义消息id、自定义消息ID过长
EXTCODE_ERROR	扩展码错误
BALANCE_ERROR	余额不足
TIMESTAMP_ERROR	时间戳错误
SIGN_ERROR	签名错误

 

3.2 状态报告错误码

状态码	描述
DELIVRD	成功
TIMEOUT	运营商状态报告超时
FAIL_BALANCE	余额不足
FAIL_MOBILE	手机号错误、手机号不支持
FAIL_MOBILE_EM	手机号重复
FAIL_AUDIT	审核拒绝
FAIL_BLACK	黑名单失败
FAIL_KEYWORD	关键字失败
FAIL_TD	用户退订
FAIL_WHITE	白名单失败
FAIL_REJECTD	拦截失败
FAIL_SIGN	签名错误
FAIL_SPEED	发送频率过快
FAIL_RESPONSE	运营商响应失败
FAIL_UNKNOW	未知失败