注册送短信

API: aim/shorturl - 生成短链接


概览


aim/shorturl 是 SUBMAIL AIM阅信的生成短网址 API。



URL


https://api-v4.mysubmail.com/aim/shorturl


接口响应数据格式


格式URL
jsonhttps://api-v4.mysubmail.com/aim/shorturl.json(默认)
xmlhttps://api-v4.mysubmail.com/aim/shorturl.xml
yamlhttps://api-v4.mysubmail.com/aim/shorturl.yaml


http 请求方式


请求方式content-type设置
postmultipart/form-data、x-www-form-urlencoded、application/json


是否需要授权


参阅 API 授权和验证机制


请求参数


参数类型必需/可选默认描述
appidstring必填在 SUBMAIL 应用集成中创建的短信应用ID
templateIdstring必填模板ID
aimCodeTypeint必填阅信编码类型
1:群发(即相同短链下发多个号码)
2:个性化(即每个短链下发一个号码,如下发多个号码也只能被一个号码解析)
paramListjson array必填参数对象集合,接收阅信的手机号/用户ID和动态参数对象列表,最大为1万个
1、没有动参的时候,dyncParams中VALUE为空
2、oppo模板一次最多只能申请10个
smsSignsarray必填应与实际下发短信原文中签名保持一致,否则手机终端无法解析阅信链接<br/> 1.当前单次生成短链操作仅支持使用一个签名,否则会引起模板内【短信签名】不一致情况
2.VIVO模板的短链签名需和创建模板时使用的签名一致,否则无法解析
签名内容不包括前后中英文括号
showTimesint必填群发单个阅信短链短信给N个号码的场景,防止展示次数超过预期带来安全风险,指定此阅信短链最大成功展示次数。
考虑到异常解析、网络异常、手机终端重置操作、SIM卡换机等操作,需要适当放大展示次数的限定值。如:预计群发消息为100W条,参考设置目标解析次数为110W次
阅信短链个性化发送,即一个短链对应一个发送号码的场景,此字段标识一个短链的尝试展示次数。考虑到异常解析、网络异常、手机终端重置操作、SIM卡换机等操作,展示次数的参考值为10次。
expireTimesint可选7短链失效时间 (默认7天)
个性化短链最大值为7天,群发短链最大值为60天
timestampint可选UNIX 时间戳,结果以秒为单位,使用加密鉴权方式,此参数必填
signTypestring可选normalAPI 鉴权模式,可选参数normal、sha256
signaturestring必需鉴权签名:
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

参数类型必需/可选默认值描述
custFlagstring必需客户标识,如手机号、用户ID等,长度不超过64个字符
此字段不做手机号校验,可填写1,2,3...
custIdstring可选自定义消息 ID,短信在客户业务系统内的标识。
最大长度不超过 64个字符。
dyncParamsmap<string>string必需动态参数,模板动态参数集体,KEY为参数名(KEY前缀为param),VALUE为参数值,长度最大100个字符。
如果无动参,value为空。群发短链建议填写固定值:
{}
customUrlstring可选自定义跳转地址,长度不超过128个字符
未填时,用户点击短信原文中的短链,跳转至阅信卡片的H5页
已填时,用户点击短信原文中的短链,跳转填写的自定义链接落地页
1.填写时必须为http或https做为前缀。
2.如要填写此项,请提前联系支撑人员添加自定义跳转地址白名单,否则无法成功生成短链

代码示例


发送一封测试短信


POST URL
https://api-v4.mysubmail.com/aim/shorturl


POST DATA
{
    "appid":"your_app_id",
    "signature":"your_app_key",
    "templateId": "RVrYrm",
    "showTimes": 10000,
    "aimCodeType": 1,
    "paramList": [{
        "custFlag": "1",
        "custId": "",
        "dyncParams": {
            "param1": "",
            "param2": ""
        },
        "customUrl": ""
    }]
}


响应参数

参数类型必需/可选默认描述
statusstring必填成功返回success,失败返回error
messagestring必填描述信息
datajson object必填请求成功返回的数据

data 数据结构

参数类型必需/可选默认描述
tplIdstring必填模板ID
paramListjson array必填参数对象集合

paramList 数据结构

参数类型必需/可选默认描述
custFlagstring必填客户标识
custIdstring可选自定义消息 ID
dyncParamsmap<string>string可选动态参数
aimUrlstring必填带URL地址的阅信短链,短链7天内有效
aimCodestring必填即aimUrl去掉前缀,目前不使用
extDatastring可选保留参数

成功返回
{
    "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"  //失败信息描述
}