Api说明-技术圈

通用

请求域名

https://uni.apistd.com

公共参数

公共参数为调用 API 请求时必须携带的参数，统一使用 URL Query 参数传输。

参数名	类型	是否必填	描述	示例值
action	string	是	接口名	sms.message.send
accessKeyId	string	是	请求 AccessKey ID	rQJEk4mz6gZzTC9X8XHfpQ1Vt

访问鉴权

UniSMS 提供以下两种鉴权方式共开发者选择，可在控制台-凭证管理中设置，默认为简易模式。

简易模式 [默认]：此模式仅核验 AccessKey ID，不对请求参数进行验签，方便开发者快速接入。
HMAC模式：此模式要求使用 AccessKey Secret 对请求参数进行验签，以加强保障请求的安全与真实性。

简易模式

使用简易模式完成访问认证，仅需将从控制台-凭证管理中获得 AccessKey ID 值传入 URL Query 参数 accessKeyId 即可完成鉴权。

HMAC模式

使用 HMAC 模式完成访问认证，需将所有 URL Query 参数按字典顺序排列作为待签文本串，并根据指定签名哈希算法进行签名。

新增所须公共参数 (Query) 如下：

参数名	类型	是否必填	描述	示例值
algorithm	string	是	签名哈希算法，目前仅支持 `hmac-sha256`	hmac-sha256
timestamp	number	是	时间戳 (ms)，接受容差时间 10 分钟	1620243278785
nonce	string	是	随机字符串，接受 8-64 个字符间的随机字符串	d7041f4746a09b10
signature	string	是	签名串	xvv9UjzOrQFWe7fFS5IUU9iqIZrncvF093SqXsnfcK8=

签名生成步骤

1. 提取请求中所有 URL Query 参数对，根据参数 Key 按字典顺序排序 (正序)，以=连接 Key-Value，以&连接参数对组成待签文本串，示例如下：

accessKeyId=rQJEk4mz6gZzTC9X8XHfpQ1Vt&action=sms.message.send&algorithm=hmac-sha256&nonce=d7041f4746a09b10×tamp=1620269782258

2. 使用 HmacSHA256 算法，以 AccessKey ID 对应的 AccessKey Secret 作为签名秘钥，对待签文本串生成签名，输出为 Base64 (或 Hex) 字符串，示例如下：

xvv9UjzOrQFWe7fFS5IUU9iqIZrncvF093SqXsnfcK8=

3. 将签名串作为 signature 的值增加到请求 URL Query 参数中发送请求，最终完整的请求 URL 示例如下：

https://uni.apistd.com/?action=sms.message.send&accessKeyId=rQJEk4mz6gZzTC9X8XHfpQ1Vt&algorith

发送短信

使用该接口发送文本短信至一个或多个收件人。阅读本文档前请先阅读 API 通用说明。

接口定义

接口名：sms.message.send
HTTP Method：POST
Content-Type：application/json

请求参数 (Body)

参数名	类型	是否必填	描述	示例值
to	string \| string[]	是	收件手机号，国际手机号使用 E.164 格式	18688061234
signature	string	是	短信签名，2-16 个字符	合一短信
content	string	否	短信正文文本，`templateId`或`content`二选一	您的验证码是9153，15分钟内有效。
templateId	string	否	短信模板 ID 或自定义模板码，`templateId`或`content`二选一	login_notify
templateData	JSON	否	模板变量	{"code": "9153", "ttl": "15"}

* 注：为帮助开发者快速迁移，UniSMS支持使用 content 参数直接传入文本，新接入用户建议优先使用 templateId 传参

请求示例

curl -X POST 'https://uni.apistd.com/?action=sms.message.send&accessKeyId=YOUR_ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{
  "to": "1860571xxxx",
  "signature": "合一短信",
  "templateId": "signup",
  "templateData": {"code": "3241", "ttl": "10"}
}'

响应参数 (Body)

参数名	类型	描述	示例值
code	string	返回码	105400
message	string	返回信息	InsufficientFunds
data	JSON	返回结果

返回结果 (data)

参数名	类型	描述	示例值
status	string	发送状态	sent
recipients	integer	收件人个数	1
messageCount	integer	计费消息总条数	1
totalAmount	number	总消费金额	0.045
payAmount	number	支付消费金额	0.045
virtualAmount	number	虚拟消费金额	0
messages	JSON[]	发送消息报告

发送消息报告 (data.messages)

参数名	类型	描述	示例值
id	string	消息标识	7cf4b5c12c5ad49379ce07290d9b00bb
to	string	收件人手机号 (E.164)	+8618688061234
regionCode	string	国际代码	CN
countryCode	string	国际电话区号	86
messageCount	integer	计费消息总条数	1
status	string	发送状态	sent
upstream	string	短信上游	emay.standard
price	string	消费金额	0.040000

响应示例

成功响应示例

Status Code: 200, Response Body:

{
  "code": "0",
  "message": "Success",
  "data": {
    "recipients": 2,
    "messageCount": 2,
    "totalAmount": "0.187500",
    "payAmount": "0.187500",
    "virtualAmount": "0",
    "messages": [
      {
        "id": "4e88293e50aac21d027a9d6c0f33661e",
        "to": "+8618688061234",
        "regionCode": "CN",
        "countryCode": "86",
        "messageCount": 1,
        "status": "sent",
        "upstream": "emay.standard",
        "price": "0.050000"
      },
      {
        "id": "ce02a6c4195c6f8c4b6a7250ccb3b0a1",
        "to": "+12894260331",
        "regionCode": "CA",
        "countryCode": "1",
        "messageCount": 1,
        "status": "sent",
        "upstream": "emay.intl.standard",
        "price": "0.137500"
      }
    ]
  }
}

失败响应示例

Status Code: 400, Response Body:

{
  "code": "105400",
  "message": "InsufficientFunds"
}

语音验证码

使用该接口发送语音验证码 (拨打电话) 至一个接收人。阅读本文档前请先阅读 API 通用说明。