综览

产品概述

飞鱼短信是飞鱼云通信为用户提供的一种云通信服务，帮助广大开发者便捷、灵活接入高质量的短信服务。

支持国内短信、国际及港澳台短信，其中，国际及港澳台短信覆盖全球200+国家及地区。常见应用场景：验证码短信（账号注册、登录验证、找回密码、安全提醒等场景），系统通知短信（故障告警、状态提醒、价格调整等场景），会员服务短信（活动通知、业务促销、新品上线、会员关怀等场景）。

使用流程

使用规范

您保证向用户发送的短信内容真实、准确、合法，您不得利用本平台提供的通信服务从事任何违反法律规定的服务内容，包括但不限于：

• 反对宪法所确定的基本原则的信息；
• 危害国家安全，泄露国家秘密，颠覆国家政权，破坏国家统一的信息；
• 损害国家荣誉和利益的信息；
• 煽动民族仇恨、民族歧视，破坏民族团结的信息；
• 破坏国家宗教政策，宣扬邪教和封建迷信的信息；
• 散布谣言，扰乱社会秩序，破坏社会稳定的信息；
• 假冒银行或银联名义进行诈骗或者敲诈勒索公私财物的信息；
• 散布淫秽、色情、赌博、暴力、凶杀、恐怖内容或者教唆犯罪、传授犯罪方法的信息；
• 非法销售枪支、弹药、爆炸物、走私车、毒品、迷魂药、淫秽物品、假钞假发票或明知是犯罪所得赃物的信息；
• 侮辱或者诽谤他人，侵害他人合法权益的信息；
• 发布可能产生重大负面社会影响的信息；
• 未经他人同意传递商业等信息；
• 发布假中奖、假婚介、假招聘，或者引诱、介绍他人卖淫嫖娼的信息；
• 多次发送干扰他人正常生活的，以及含有其他违反宪法、法律、行政法规禁止性规定内容的信息；
• 从事欺骗或诈骗行为；
• 其他违反国家法律、行政法规和行业政策的行为；

术语解释

短信类别

根据短信的应用场景、用途不同，区分为验证码、通知短信、会员服务短信；

短信内容

短信内容由短信签名、短信正文两部分组成，其中，短信签名需在发送前报备，在发送时使用即可；

短信签名

短信签名是具体要发送的短信内容的组成部分之一，一般放在短信正文前面，用于标识企业主体或产品业务；用户可以根据账号主体所属机构的业务需求创建符合自身属性的、个性化短信签名；

下行(MT)

下行(Message Terminal)是指手机用户收到的短消息；

上行(MO)

上行(Message Original)是指手机用户发送的回复内容；

状态报告

状态报告是指运营商返回的发送结果；

使用指南

获取状态报告方法：

• 请提供推送地址，平台在收到状态报告后会立即推送到指定地址
• 通过调用接口主动获取

短信内容长度计算规则

国内短信

• 国内短信长度（签名+正文）不超过70字时，按照1条短信计费；超过70字即为长短信时，按67字/条分隔成多条计费，但会在1条短信内呈现 例如，短信长度为150字，则按照67字/67字/16字分隔成3条计费
• 单次发送的短信长度最长不允许超过500字
• 国内短信必须携带签名，签名符号为【】

国际短信

纯英文短信

• GSM 标准字符按1个字计算，GSM 扩展字符按2个字计算

• 当短信长度不超过160字时，按照1条短信计费。超过160字时为长短信，按153字/条分隔成多条计费。 例如，短信长度为320字，则按照153字/153字/14字分隔成3条计费。

非纯英文短信

• 汉字、字母、数字、标点符号（不区分全角/半角）以及空格等，都按1个字计算
• 当短信长度不超过70字时，按照1条短信计费。超过70字时为长短信，按67字/条分隔成多条计费 例如，短信长度为150字，则按照67字/67字/16字分隔成3条计费

常见问题汇总

更新日志

发送短信

接口说明

• Content-Type: application/json;charset=utf-8
• 编码: UTF-8
• 请求地址: https://api.aiofish.com/rest/sms/sendSms
• 请求方式: POST

请求样例

  {
      "account": "xxxxxx",
      "password": "aa6f32c0d19832a228ae2c72471c6a49",
      "smsType": "cs",
      "mobile": "12312345678",
      "content": "【飞鱼短信】您的验证码是123456，5分钟内有效。",
      "subCode": "11"
  }   

请求参数说明

响应数据说明

{
    "code": 200,
    "smsId": "e4aaea7fb95d40159d1e325df01d9e72",
    "subStat": "r:000",
    "subStatDes": "处理成功",
    "resDetail": [
        {
            "phoneNumber": "12312345678",
            "stat": "r:000",
            "statDes": "提交成功"
        }
    ]
}

发送接口(号码加密)

接口说明

• Content-Type: application/json;charset=utf-8
• 编码: UTF-8
• 请求地址: https://api.aiofish.com/rest/sms/sendSmsByEncrypt
• 请求方式: POST

请求样例

  {
      "account": "xxxxxx",
      "password": "aa6f32c0d19832a228ae2c72471c6a49",
      "mobile": "e86deeb2e7ea254ef1494b83657b01fd",
      "content": "【飞鱼短信】您的验证码是123456，5分钟内有效。",
      "subCode": "11"
  }   

请求参数说明

响应数据说明

{
    "code": 200,
    "smsId": "e4aaea7fb95d40159d1e325df01d9e72",
    "subStat": "r:000",
    "subStatDes": "处理成功",
    "resDetail": [
        {
            "phoneNumber": "e86deeb2e7ea254ef1494b83657b01fd",
            "stat": "r:000",
            "statDes": "提交成功"
        }
    ]
}

发送接口(加密版)

接口说明

• Content-Type: application/json;charset=utf-8
• 编码: UTF-8
• 请求地址: https://api.aiofish.com/rest/sms/sendSms/encryption
• 请求方式: POST

请求样例

  {
    "account": "api003",
    "ts": "1698632973036",
    "bizContent": "10e18d2ebaebdb485cae33dca2604e10706cfa2ba255ba0bedb7ec9f7099",
    "sign": "1f55c5a8b38bc37706bbed532940ae4190814a5c96fe2c3"
}

请求参数说明

原始数据

原始数据样例

{
  "mobile": "12312345678",
  "content": "您的验证码为：703319，有效期5分钟",
  "subCode": "11"
}   

原始数据说明

数字签名

数字签名实现

import com.google.common.base.Joiner;
import org.apache.commons.codec.digest.DigestUtils;

public static String generateSign(String account, String ts, String  bizContent, 
                                            String appSecret) throws Exception {
    Map<String, String> params = new TreeMap<>();
    params.put("account", account);
    params.put("appSecret", appSecret);
    params.put("ts", ts);
    params.put("bizContent", bizContent);

    String str = Joiner.on("&").withKeyValueSeparator("=").join(params);
    return DigestUtils.sha256Hex(str);
}

数字签名样例

原始内容拼接：

account=api003&appSecret=ba92fa4836984eb98156e6ec8a6b2454&bizContent=10e18d2ebaebdb485cae33dca2&ts=1698632973036

签名结果：

1f825da81826e47c4dbff9a5c785cb8c141dcb1a5343d3650bfe6794879ef400

响应数据说明

{
    "code": 200,
    "smsId": "e4aaea7fb95d40159d1e325df01d9e72",
    "subStat": "r:000",
    "subStatDes": "处理成功"
}

批量发送短信

接口说明

• Content-Type: application/json;charset=utf-8
• 编码: UTF-8
• 请求地址: https://api.aiofish.com/rest/sms/batchSendSms
• 请求方式: POST

请求样例

{
"account": "ZNRX7j",
"password": "14fa0b773a0ca9ca66a9db8fcf1d25",
"mobiles": [
  {
    "mobile": "13000000000",
    "content": "【测试】您的验证码是123456。",
    "templateId": "123"
  },
  {
    "mobile": "13000000001",
    "content": "【测试】您的验证码是654321。",
    "templateId": "123"
  }
],
"subCode": "12",
"smsId": "f5e08fb8d073c7b536f7ccaa9f07e1",
"sendTime": null
} 

请求参数说明

SendObj说明

响应数据说明

{
  "code": 200,
  "smsId": "e4aaea7fb95d40159d1e325df01d9e72",
  "subStat": "r:000",
  "subStatDes": "处理成功"
}

批量发送接口(加密版)

接口说明

• Content-Type: application/json;charset=utf-8
• 编码: UTF-8
• 请求地址: https://api.aiofish.com/rest/sms/batchSendSms/encryption
• 请求方式: POST

请求样例

  {
    "account": "api003",
    "ts": "1698632973036",
    "bizContent": "10e18d2ebaebdb485cae33dca2604e10706cfa2ba255ba0bedb7ec9f7099",
    "sign": "1f55c5a8b38bc37706bbed532940ae4190814a5c96fe2c3"
}

请求参数说明

原始数据

{
"mobiles": [
  {
    "mobile": "13000000000",
    "content": "【测试】您的验证码是123456。"
  },
  {
    "mobile": "13000000001",
    "content": "【测试】您的验证码是654321。"
  }
],
"subCode": "12",
"smsId": "f5e08fb8d073c7b536f7ccaa9f07e1",
"sendTime": null
} 

原始数据说明

SendObj说明

数字签名

数字签名实现

import com.google.common.base.Joiner;
import org.apache.commons.codec.digest.DigestUtils;

public static String generateSign(String account, String ts, String  bizContent, 
                                            String appSecret) throws Exception {
    Map<String, String> params = new TreeMap<>();
    params.put("account", account);
    params.put("appSecret", appSecret);
    params.put("ts", ts);
    params.put("bizContent", bizContent);

    String str = Joiner.on("&").withKeyValueSeparator("=").join(params);
    return DigestUtils.sha256Hex(str);
}

数字签名样例

原始内容拼接：

account=api003&appSecret=ba92fa4836984eb98156e6ec8a6b2454&bizContent=10e18d2ebaebdb485cae33dca2&ts=1698632973036

签名结果：

1f825da81826e47c4dbff9a5c785cb8c141dcb1a5343d3650bfe6794879ef400

响应数据说明

{
  "code": 200,
  "smsId": "e4aaea7fb95d40159d1e325df01d9e72",
  "subStat": "r:000",
  "subStatDes": "处理成功"
}

查询余额接口

接口说明

• 请求地址: https://api.aiofish.com/rest/sms/getBalance
• 请求方式: GET

请求样例

https://api.aiofish.com/rest/sms/getBalance?account=J10003&password=26dad7f364507df1

响应样例

{
    "revStat": "r:000",
    "revStatDes": "您的短信余额为：2670 条",
    "code": 200,
    "demo": null
}

获取状态报告接口

接口说明

• 请求地址: https://api.aiofish.com/rest/sms/getReport
• 请求方式: GET

请求样例:

https://api.aiofish.com/rest/sms/getReport?account=J10003&password=26dad7f364507df18f3841c

响应样例

{
    "subStat": "r:000",
    "subStatDes": "获取状态报告记录数:1",
    "code": 200,
    "resDetail": [
        {
            "smsId": "e4aaea7fb95d40159d1e325df01d9e72",
            "phoneNumber": "12312345678",
            "stat": "r:004",
            "statDes": "REJECTD",
            "revTime": 1636429743000
        }
    ]
}

获取上行接口

接口说明

• 请求地址: https://api.aiofish.com/rest/sms/getReply
• 请求方式: GET

请求样例:

 https://api.aiofish.com/rest/sms/getReply?account=J10003&password=26dad7f364507df18f3841cc

响应样例

{
    "revStat": "r:000",
    "revStatDes": "获取上行短信条数:1",
    "code": 200,
    "resDetail": [
        {
            "phoneNumber": "12312345678",
            "content": "收到",
            "subCode": "11",
            "revTime": 1616429743000,
            "demo": null
        }
    ]
}

推送状态/上行

推送说明

• Content-Type: application/x-www-form-urlencoded
• 编码: UTF-8
• 推送地址: 客户需提供状态报告以及上行推送地址
• 推送频次: 推送失败将会在5分钟、10分钟和1小时后再次尝试推送
• 推送结果: 客户正常处理后返回0。返回其他任何数据系统都会识别为推送失败
• 推送方式: 单条推送

状态报告(Report)参数

上行(Deliver)参数

推送状态/上行(号码加密)

推送说明

• Content-Type: application/x-www-form-urlencoded
• 编码: UTF-8
• 推送地址: 客户需提供状态报告以及上行推送地址
• 推送频次: 推送失败将会在1分钟、5分钟、10分钟和1小时后再次尝试推送
• 推送结果: 客户正常处理后返回0。返回其他任何数据系统都会识别为推送失败
• 推送方式: 单条推送

状态报告(Report)参数

上行(Deliver)参数

推送状态/上行(加密版)

推送说明

• Content-Type: application/json;charset=utf-8
• 编码: UTF-8
• 推送地址: 客户需提供状态报告以及上行推送地址
• 推送频次: 推送失败将会在1分钟、5分钟、10分钟和1小时后再次尝试推送
• 推送结果: 客户正常处理后返回0。返回其他任何数据系统都会识别为推送失败
• 推送方式: 单条推送

请求样例

  {
    "account": "api003",
    "ts": "1698632973036",
    "bizContent": "10e18d2ebaebdb485cae33dca2604e10706cfa2ba255ba0bedb7ec9f7099",
    "sign": "1f55c5a8b38bc37706bbed532940ae4190814a5c96fe2c3"
}

请求参数说明

数字签名

数字签名实现

import com.google.common.base.Joiner;
import org.apache.commons.codec.digest.DigestUtils;

public static String generateSign(String account, String ts, String  bizContent, 
                                            String appSecret) throws Exception {
    Map<String, String> params = new TreeMap<>();
    params.put("account", account);
    params.put("appSecret", appSecret);
    params.put("ts", ts);
    params.put("bizContent", bizContent);

    String str = Joiner.on("&").withKeyValueSeparator("=").join(params);
    return DigestUtils.sha256Hex(str);
}

数字签名样例

原始内容拼接：

account=api003&appSecret=ba92fa4836984eb98156e6ec8a6b2454&bizContent=10e18d2ebaebdb485cae33dca2&ts=1698632973036

签名结果：

1f825da81826e47c4dbff9a5c785cb8c141dcb1a5343d3650bfe6794879ef400

原始数据

状态报告(Report)参数

{
    "stat": 6,
    "smsId": "03e2c9e81a54416ba2a046eac6f52b63",
    "phoneNumber": "17530663764",
    "statDes": "REJECTD",
    "revTime": 1698636405820
}

上行(Deliver)参数

{
    "phoneNumber": "17530663764",
    "content": "R",
    "subCode": "123",
    "smsId": "8b8a8939d5424bd0ad60aea59e995434"
}

提交响应错误码

接入说明

接口说明

• Content-Type: application/json;charset=utf-8

公共参数说明

• appKey: 接入账号，系统平台提供。
• appSecret: 接入密钥，系统平台提供。
• ts: 当前时间戳，精确到毫秒。

身份信息验证

• 所有接口请求的header中必须包含签名字段：x-sign,该字段使用相关参数按照指定拼接规则通过MD5摘要算法得到。

 String sign = MD5(String.format("%s,%s,%s",appKey,ts,appSecret));

提交模板接口

接口说明

• 请求地址: https://api.aiofish.com/rest/vsms/v1/tpl
• 请求方式: POST
• Content-Type: multipart/form-data
• 以http表单形式单次上传多个附件，key为表单的“file“字段。除了文件数据外的请求参数转换为Json字符串，key为表单的“data“字段

字段说明

数据模型

ContentList

Curl样例

 curl  --request POST 'https://api.aiofish.com/rest/vsms/v1/tpl' 
 --header 'x-sign: 39dd91319d32b36def6272e1b9' 
 --form 'data="{\"appKey\":\"xxxxx\",\"ts\":\"1638805414651\",\"title\":\"测试\",\"content\":[{\"orderBy\":1,\"frameIndex\":1,\"extType\":2,\"text\":\"aaa.jpg\"},{\"orderBy\":2,\"frameIndex\":1,\"extType\":1,\"text\":\"【测试】内容测试\"}]}"' 
 --form 'file=@"aaa.jpg"'

响应字段

查询模板状态接口

接口说明

• 请求地址: https://api.aiofish.com/rest/vsms/v1/tpl/status
• 请求方式: GET

请求参数

Curl样例

curl  --request GET 'https://api.aiofish.com/rest/vsms/v1/tpl/status?appKey=test11&ts=1638805414651&tplId=4176a024bf6a381e5a38fe5f866' \
 --header 'x-sign: 39dd91319d32b36def6272e1b9'

响应字段

发送短信

接口说明

• 请求地址: https://api.aiofish.com/rest/vsms/v1/message
• 请求方式: POST

请求参数

Curl样例

curl  --request POST 'https://api.aiofish.com/rest/vsms/v1/message' \
--header 'x-sign: 39dd91319d32b36def6272e1b9' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "test11",
    "ts": "1638805414651",
    "tplId": "4176a024bf6a381e5a38fe5f866",
    "mobiles": [
        "180******43"
    ]
}'

响应字段

发送变量消息接口

接口说明

• 请求地址: https://api.aiofish.com/rest/vsms/v1/message/vars
• 请求方式: POST

请求参数

数据模型

SendVar

Curl样例

curl --request POST 'https://api.aiofish.com/rest/vsms/v1/message/vars' \
--header 'x-sign: 39dd91319d32b36def6272e1b9' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "test11",
    "ts": "1638805414651",
    "tplId": "4176a024bf6a381e5a38fe5f866",
    "mobiles": [
        {
            "phone": "180****43",
            "vars": [
                "test"
            ]
        }
    ]
}'

响应字段

推送状态报告

推送说明

• Content-Type: application/json
• 编码: UTF-8
• 推送地址: 客户需提供状态报告、上行推送以及模板状态推送地址
• 推送频次: 推送失败将会在5分钟、10分钟和1小时后再次尝试推送
• 推送结果: 客户正常处理后返回字符串0。返回其他任何数据，系统会识别为推送失败
• 推送方式: 单条推送

状态报告推送参数

{
    "msgId":"88f07db153f24a638779",
    "phone":"18000000000",
    "state":0,
    "statDes":"DELIVRD",
    "revTime":"2021-12-06T19:00:00"
}

模板状态推送参数

{
   "tplId":"88f07db153f24a638779",
   "state":200,
   "reason":"ok"
}

提交响应错误码

接入说明

接口说明

• Content-Type: application/json;charset=utf-8

公共参数说明

• appKey: 接入账号，系统平台提供。
• appSecret: 接入密钥，系统平台提供。
• ts: 当前时间戳，精确到毫秒。

身份信息验证

• 所有接口请求的header中必须包含签名字段：x-sign,该字段使用相关参数按照指定拼接规则通过MD5摘要算法得到。

 String sign = MD5(String.format("%s,%s,%s",appKey,ts,appSecret));

发送短信

接口说明

• 请求地址: https://api.aiofish.com/rest/isms/sendIsms
• 请求方式: POST

请求参数

Curl样例

curl  --request POST 'https://api.aiofish.com/rest/isms/sendIsms' \
--header 'x-sign: 39dd91319d32b36def6272e1b9' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "test11",
    "ts": "1638805414651",
    "content": "hello! test sms",
    "mobiles": [
        "86180******43"
    ]
}'

响应字段

推送状态报告

推送说明

• Content-Type: application/json
• 编码: UTF-8
• 推送地址: 客户需提供状态报告、上行推送以及模板状态推送地址
• 推送频次: 推送失败将会在5分钟、10分钟和1小时后再次尝试推送
• 推送结果: 客户正常处理后返回字符串0。返回其他任何数据，系统会识别为推送失败
• 推送方式: 单条推送

状态报告推送参数

{
    "msgId":"88f07db153f24a638779",
    "mobile":"85212341234",
    "state":0,
    "statDes":"DELIVRD",
    "revTime":"2021-12-06 19:00:00"
}

提交响应错误码