第三方短信平台接口规范

更新时间:

为了在用户营销模块使用将第三方短信平台,当您进行第三方短信平台开发时,需要遵守下面的各功能模块接口规范。

短信请求通用参数

URL参数

含义

示例

timestamp

秒级时间戳

1631865523

nonce

32位随机字符串

2e6eceb5737b473284c930c8ef79090e

请求URL示例:

{第三方短信所有接口的url}?timestamp=1631865523&nonce=2e6eceb5737b473284c930c8ef79090e

Header

含义

说明

X-QA-Hmac-Signature

权鉴签名

开启权鉴时使用,权鉴方式见下文。

未开启权鉴时,该Header填空字符串""。

短信请求权鉴

若短信需要鉴权,请在配置第三方短信接口时开启权鉴并填写密钥,参见新建第三方短信平台接口

QuickAudience会根据用户填写的密钥与URL请求参数timestamp和nonce进行HmacSHA256Hex签名并生成signature,并将此signature通过Request Header传递。您的服务接收到请求后,同样根据URL参数与webhook通道配置的密钥进行HmacSHA256Hex算法加密。如果计算的值与从Request Header中传过来的signature相同,则可以确定是此请求是从QuickAudience发出的,鉴权成功。

参数

含义

示例

key

webhook配置的密钥

123456789

签名算法示例:

public String makeSignature(String key, String timestamp, String nonce) {
   String str = generateStr(key, timestamp, nonce);
    return HmacUtils.hmacSha256Hex(key, str.replaceAll("\\s+", ""));
} 

/**
 * 签名待处理的字符串拼接
 */
public static String generateStr(String key, String timestamp, String nonce){
    String[] array = new String[] { key, timestamp, nonce};
    StringBuffer sb = new StringBuffer();
    // 字符串排序
    Arrays.sort(array);
    for (int i = 0; i < 3; i++) {
        sb.append(array[i]);
    }
    return sb.toString();
}

短信模板审核接口

接口描述

短信模板审核

URL

${prefix}/sms/smsTemplate?timestamp=&nonce=

请求方式

post

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.remark

string

body

短信模板申请说明。请在申请说明中描述您的业务使用场景,长度为1~100个字符。

2.templateContent

string

模板内容,长度为1~500个字符。

3.templateName

string

模板名称,长度为1~30个字符。

4.templateSubject

string

模板主题,长度为1~20个字符。

5.templateType

integer(int32)

短信类型。

  • 0:验证码。

  • 1:短信通知。

  • 2:推广短信。

  • 3:国际/中国香港、中国澳门和中国台湾消息。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.platformName

string

短信服务方名称,与接口配置时填写的接口名称一致。

2.code

string

请求状态码,200或OK表示成功。

3.message

string

状态码描述。

4.requestId

string

请求ID。

5.templateCode

string

短信模板code,用于查看模板申请状态和结果。

示例

请求参数

-d '{"remark":"string","templateContent":"string","templateName":"string","templateSubject":"string","templateType":0}'

返回值

{"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"}

短信模板修改接口

接口描述

短信模板修改

URL

${prefix}/sms/smsTemplate/{templateCode}?timestamp=&nonce=

请求方式

put

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.remark

string

body

短信模板申请说明。请在申请说明中描述您的业务使用场景,长度为1~100个字符。

2.templateContent

string

模板内容,长度为1~500个字符。

3.templateName

string

模板名称,长度为1~30个字符。

4.templateSubject

string

模板主题,长度为1~20个字符。

5.templateType

integer(int32)

短信类型。

  • 0:验证码。

  • 1:短信通知。

  • 2:推广短信。

  • 3:国际/中国香港、中国澳门和中国台湾消息。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.platformName

string

短信服务方名称,与接口配置时填写的接口名称一致。

2.code

string

请求状态码,200或OK表示成功。

3.message

string

状态码描述。

4.requestId

string

请求ID。

5.templateCode

string

短信模板code,用于查看模板申请状态和结果。

示例

请求参数

-d '{"remark":"string","templateContent":"string","templateName":"string","templateSubject":"string","templateType":0}'

返回值

{"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"}

短信签名审核状态查询接口

接口描述

短信签名审核状态查询

URL

${prefix}/sms/smsSign/{signName}?timestamp=&nonce=

请求方式

get

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.signName

string

path

短信签名。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.platformName

string

短信服务方名称,与接口配置时填写的接口名称一致。

2.code

string

请求状态码,200或OK表示成功。

3.createDate

string

短信签名的创建日期和时间,如:2019-01-08 16:44:13。

4.message

string

状态码描述。

5.reason

string

审核备注。如果审核状态为审核通过或审核中,参数Reason显示为“无审核备注”;如果审核状态为审核未通过,参数Reason显示审核的具体原因。

6.requestId

string

请求ID。

7.signName

string

短信签名。

8.signStatus

integer(int32)

签名审核状态。

  • 0:审核中。

  • 1:审核通过。

  • 2:审核失败,请在返回参数Reason中查看审核失败原因。

示例

请求参数

无示例

返回值

{"reason":"string","code":"string","signName":"string","requestId":"string","signStatus":0,"platformName":"string","message":"string","createDate":"string"}

短信模板审核状态查询接口

接口描述

短信模板审核状态查询

URL

${prefix}/sms/smsTemplate/{templateCode}?timestamp=&nonce=

请求方式

get

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.templateCode

string

path

模板code。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.platformName

string

服务方名称,与接口配置时填写的接口名称一致。

2.code

string

请求状态码,200或OK表示成功。

3.createDate

string

模板的创建日期和时间,如:2019-01-08 16:44:13。

4.message

string

状态码描述。

5.reason

string

审核备注。如果审核状态为审核通过或审核中,参数Reason显示为“无审核备注”;如果审核状态为审核未通过,参数Reason显示审核的具体原因。

6.requestId

string

请求ID。

7.templateCode

string

模板code。

8.templateContent

string

模板内容。

9.templateName

string

模板名称。

10.templateStatus

integer(int32)

模板审核状态。

  • 0:审核中。

  • 1:审核通过。

  • 2:审核失败,请在返回参数Reason中查看审核失败原因。

11.templateType

integer(int32)

短信模板类型。

  • 0:验证码。

  • 1:短信通知。

  • 2:推广短信。

  • 3:国际/中国香港、中国澳门和中国台湾消息。

示例

请求参数

无示例

返回值

{"templateStatus":0,"templateType":0,"reason":"string","code":"string","templateName":"string","requestId":"string","templateContent":"string","platformName":"string","templateCode":"string","message":"string","createDate":"string"}

短信发送接口(单条发送)

接口描述

单条短信发送

URL

${prefix}/sms/send?timestamp=&nonce=

请求方式

post

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.limit

integer(int64)

body

发送人数限制。

2.outId

string

外部流水扩展字段。

3.phoneNumbers

string

接收短信的手机号码。

国内短信:11位手机号码,例如159********;国际/中国香港、中国澳门和中国台湾消息:国际区号+号码,例如85200******。

4.signName

string

短信签名名称。

5.templateCode

string

模板code。

6.templateParam

string

短信模板变量对应的实际值,JSON格式。例如:[{"name":"TemplateParamJson","age":"age"}],和 phoneNumbers 的数量保持一致,数量不一致会报错。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.bizId

string

发送回执ID。

2.platformName

string

服务方名称,与接口配置时填写的接口名称一致。

3.code

string

请求状态码,200或OK表示成功。

4.message

string

状态码描述。

5.requestId

string

请求ID。

示例

请求参数

-d '{"limit":0,"outId":"string","phoneNumbers":"string","signName":"string","templateCode":"string","templateParam":"string"}'

返回值

{"bizId":"string","platformName":"string","code":"string","message":"string","requestId":"string"}

短信发送接口(批量发送)

接口描述

大量短信发送

URL

${prefix}/sms/sendBatch?timestamp=&nonce=

请求方式

post

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.limit

integer(int64)

body

发送人数限制。

2.outId

string

外部流水扩展字段。

3.phoneOssUrl

string

接收短信的手机号码文件所在的OSS路径。文件格式txt。

国内短信:11位手机号码,例如159********;国际/中国香港、中国澳门和中国台湾消息:国际区号+号码,例如85200******。每个号码一行。变量短信会在每行手机号后面加上变量名称与替换值内容。例如:{"name":"TemplateParamJson","age":"age"}

4.signName

string

短信签名名称。

5.templateCode

string

模板code。

6.isVariable

integer(int64)

是否是变量短信。

  • 0:不是变量短信。

  • 1:是变量短信。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.bizId

string

发送回执ID。

2.platformName

string

服务方名称,与接口配置时填写的接口名称一致。

3.code

string

请求状态码,200或OK表示成功。

4.message

string

状态码描述。

5.requestId

string

请求ID。

示例

请求参数

-d '{"limit":0,"outId":"string","phoneOssUrl":"string","signName":"string","templateCode":"string","isVariable":"string"}'

返回值

{"bizId":"string","platformName":"string","code":"string","message":"string","requestId":"string"}

短信发送明细查询接口

接口描述

短信发送明细查询

URL

${prefix}/sms/sendDetails?timestamp=&nonce=

请求方式

post

请求类型

application/json

返回类型

*/*

参数名

数据类型

参数类型

是否必填

说明

1.outId

string

body

外部流水扩展字段。

2.currentPage

integer(int64)

分页查看发送记录,指定发送记录的当前页码。

3.pageSize

integer(int64)

分页查看发送记录,指定每页显示的短信记录数量。取值范围为1~1000。

4.startDate

string

起始时间,与结束时间的跨度不能超出30天,格式yyyy-MM-dd HH:mm:ss。

5.endDate

string

结束时间,与起始时间的跨度不能超出30天,格式yyyy-MM-dd HH:mm:ss。

状态码

描述

说明

200

OK

请求成功。

401

Unauthorized

请求未经授权。

403

Forbidden

请求被拒绝。

404

Not Found

请求的资源不存在。

返回属性名

类型

说明

1.platformName

string

短信服务方名称,与接口配置时填写的接口名称一致

2.code

string

请求状态码,200或OK表示成功。

3.message

string

状态码描述。

4.requestId

string

请求ID。

5.sendDetailDTOs

array:SmsSendDetailDTO

短信发送明细。

5.1.content

string

短信内容。

5.2.errCode

string

运营商短信状态码。短信发送成功:DELIVERED。短信发送失败:给出错误码。

5.3.outId

string

外部流水扩展字段。

5.4.phoneNum

string

接收短信的手机号码。

5.5.receiveDate

string

短信接收日期和时间。

5.6.sendDate

string

短信发送日期和时间。

5.7.sendStatus

integer(int64)

短信发送状态。

  • 1:发送失败。

  • 2:发送成功。

5.8.templateCode

string

短信模板ID。

6.totalCount

integer(int32)

短信发送总条数。

示例

请求参数

-d '{"outId":"string","currentPage":0,"pageSize":0,"startDate":"string","endDate":"string"}'

返回值

{"platformName":"string","code":"string","message":"string","totalCount":0,"requestId":"string","sendDetailDTOs":[{"content":"string","errCode":"string","outId":"string","phoneNum":"string","receiveDate":"string","sendDate":"string","sendStatus":0,"templateCode":"string"}]}