API: aim/shorturl - 生成短链接
概览
aim/shorturl 是 SUBMAIL AIM阅信的生成短网址 API。
URL
https://api-v4.mysubmail.com/aim/shorturl
接口响应数据格式
| 格式 | URL |
|---|---|
json | https://api-v4.mysubmail.com/aim/shorturl.json（默认） |
xml | https://api-v4.mysubmail.com/aim/shorturl.xml |
yaml | https://api-v4.mysubmail.com/aim/shorturl.yaml |
http 请求方式
| 请求方式 | content-type设置 |
|---|---|
post | multipart/form-data、x-www-form-urlencoded、application/json |
是否需要授权
是
参阅 API 授权和验证机制
请求参数
| 参数 | 类型 | 必需/可选 | 默认 | 描述 |
|---|---|---|---|---|
appid | string | 必填 | 无 | 在 SUBMAIL 应用集成中创建的短信应用ID |
templateId | string | 必填 | 无 | 模板ID |
aimCodeType | int | 必填 | 无 | 阅信编码类型 1：群发（即相同短链下发多个号码） 2：个性化（即每个短链下发一个号码,如下发多个号码也只能被一个号码解析） |
paramList | json array | 必填 | 无 | 参数对象集合，接收阅信的手机号/用户ID和动态参数对象列表，最大为1万个 1、没有动参的时候，dyncParams中VALUE为空 2、oppo模板一次最多只能申请10个 |
smsSigns | array | 必填 | 无 | 应与实际下发短信原文中签名保持一致，否则手机终端无法解析阅信链接<br/> 1.当前单次生成短链操作仅支持使用一个签名，否则会引起模板内【短信签名】不一致情况 2.VIVO模板的短链签名需和创建模板时使用的签名一致，否则无法解析 签名内容不包括前后中英文括号 |
showTimes | int | 必填 | 无 | 群发单个阅信短链短信给N个号码的场景，防止展示次数超过预期带来安全风险，指定此阅信短链最大成功展示次数。 考虑到异常解析、网络异常、手机终端重置操作、SIM卡换机等操作，需要适当放大展示次数的限定值。如：预计群发消息为100W条，参考设置目标解析次数为110W次 阅信短链个性化发送，即一个短链对应一个发送号码的场景，此字段标识一个短链的尝试展示次数。考虑到异常解析、网络异常、手机终端重置操作、SIM卡换机等操作，展示次数的参考值为10次。 |
expireTimes | int | 可选 | 7 | 短链失效时间 (默认7天) 个性化短链最大值为7天，群发短链最大值为60天 |
timestamp | int | 可选 | 无 | UNIX 时间戳，结果以秒为单位，使用加密鉴权方式，此参数必填 |
signType | string | 可选 | normal | API 鉴权模式，可选参数normal、sha256 |
signature | string | 必需 | 无 | 鉴权签名: 1. 当signType为sha256时，将以下参数拼接appid+appkey+appid=12345&signType=sha256& timestamp=1712122221+appid+appkey ,“+”号为链接符号，不参与拼接用sha256将以上拼接字符串加密作为鉴权参数 2.当signType为normal时，appkey即是signature的值。 |
paramList 数据结构
注：paramList参数中不得出现以下关键字，或包含关键字的单词或短语句子onmouseover,onmouseout,onmousedown,onmouseup,onmousemove,onclick,ondblclick,onkeypress,onkeydown,onkeyup,ondragstart,onerrorupdate,onhelp,onreadystatechange,onrowenter,onrowexit,onselectstart,onload,onunload,onbeforeunload,onblur,onerror,onfocus,onresize,onscroll,oncontextmenu,alert,<script,</script,<marquee,</marquee
| 参数 | 类型 | 必需/可选 | 默认值 | 描述 |
|---|---|---|---|---|
custFlag | string | 必需 | 无 | 客户标识，如手机号、用户ID等，长度不超过64个字符 此字段不做手机号校验，可填写1,2,3... |
custId | string | 可选 | 无 | 自定义消息 ID，短信在客户业务系统内的标识。 最大长度不超过 64个字符。 |
dyncParams | map<string>string | 必需 | 无 | 动态参数，模板动态参数集体，KEY为参数名（KEY前缀为param），VALUE为参数值，长度最大100个字符。 如果无动参，value为空。群发短链建议填写固定值： {} |
customUrl | string | 可选 | 无 | 自定义跳转地址，长度不超过128个字符 未填时，用户点击短信原文中的短链，跳转至阅信卡片的H5页 已填时，用户点击短信原文中的短链，跳转填写的自定义链接落地页 1.填写时必须为http或https做为前缀。 2.如要填写此项，请提前联系支撑人员添加自定义跳转地址白名单，否则无法成功生成短链 |
代码示例
发送一封测试短信
POST URL
https://api-v4.mysubmail.com/aim/shorturlPOST DATA
{
"appid":"your_app_id",
"signature":"your_app_key",
"templateId": "RVrYrm",
"showTimes": 10000,
"aimCodeType": 1,
"paramList": [{
"custFlag": "1",
"custId": "",
"dyncParams": {
"param1": "",
"param2": ""
},
"customUrl": ""
}]
}响应参数
| 参数 | 类型 | 必需/可选 | 默认 | 描述 |
|---|---|---|---|---|
status | string | 必填 | 无 | 成功返回success，失败返回error |
message | string | 必填 | 无 | 描述信息 |
data | json object | 必填 | 无 | 请求成功返回的数据 |
data 数据结构
| 参数 | 类型 | 必需/可选 | 默认 | 描述 |
|---|---|---|---|---|
tplId | string | 必填 | 无 | 模板ID |
paramList | json array | 必填 | 无 | 参数对象集合 |
paramList 数据结构
| 参数 | 类型 | 必需/可选 | 默认 | 描述 |
|---|---|---|---|---|
custFlag | string | 必填 | 无 | 客户标识 |
custId | string | 可选 | 无 | 自定义消息 ID |
dyncParams | map<string>string | 可选 | 无 | 动态参数 |
aimUrl | string | 必填 | 无 | 带URL地址的阅信短链，短链7天内有效 |
aimCode | string | 必填 | 无 | 即aimUrl去掉前缀，目前不使用 |
extData | string | 可选 | 无 | 保留参数 |
成功返回
{
"status": "success",
"message": "成功",
"data": {
"tplId": "RVrYrm",
"paramList": [{
"custFlag": "13000000000",
"custId": "500000000001",
"dyncParams": {
"param1": "参数1",
"param2": "参数2"
},
"aimUrl": "https://rcs.10086.cn/dsfw3d",
"aimCode": "dsfw3d",
"extData": ""
},
{
"custFlag": "13000000001",
"custId": "500000000002",
"dyncParams": {
"param1": "参数1",
"param2": "参数2"
},
"aimUrl": "https://rcs.10086.cn/fsdfws",
"aimCode": "fsdfws",
"extData": ""
}
]
}
}失败返回
{
"status":"error", //请求状态
"msg":"error message" //失败信息描述
}