批量短信下行发送 - nxtele/http-api-document GitHub Wiki

批量短信下行发送

  • URL：https://api2.nxcloud.com/v1/sms/multi/mt
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

鉴权机制

鉴权规则请参考地址：API接口调用约定


请求参数

header参数：

参数名 类型 必选 示例值 说明
accessKey String 是 fmexxx3ki 用户身份标识
ts String 是 1655710885431 当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType String 是 3 业务类型，取固定值"3"
action String 是 mtsend 业务操作，取固定值"mtsend"
sign String 是 6e95xxx826 API入参参数签名，签名算法

body参数：

参数名 类型 必选 说明
appKey String 是 短信应用appkey
items Array 是 批量短信发送列表，最多支持200条。每个元素包含以下字段：

items数组元素参数：

参数名 类型 必选 说明
phone String 是 被叫号码(国码+手机号，比如：8615088888888)
content String 是 短信内容，内容最长1000个字符
sourceAddress String 否 sourceaddress (必须为1-20位数字或英文字母)
sysMessageId String 否 用户自定义messageid，长度为10-50位之间，类型【0-9a-zA-Z-】。如果传入该字段，在响应中的messageid会使用该值；如果未传入，系统会自动生成
shortLink String 否 短链，数据来自于短链列表；如果此处赋值，短信内容里面必须包含#1#才能起作用，请注意
linkVerbose String 否 该参数设定的为是否收集用户点击行为，若选择收集用户点击行为，则可在控制台中查看点击了该短链接的号码信息。参数：1：收集；0：不收集。默认为收集
drUrl String 否 dr推送地址（如同时在短信应用上也配置有dr推送地址，优先推送dr给本接口配置的地址）
ext String 否 透传字段，该字段为自定义信息，在回执中会原样返回，仅支持http请求

请求示例

curl --location --request POST 'http://api2.nxcloud.com/api/sms/multi/mt' \
--header 'accessKey: asdfsdf' \
--header 'bizType: 3' \
--header 'action: mtsend' \
--header 'ts: 1683277109072' \
--header 'sign: 324324324234324' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "appKey",
    "items": [
        {
            "phone": "18651883168",
            "content": "content1",
            "sysMessageId": "msg001"
        },
        {
            "phone": "18651883279",
            "content": "content2",
            "sysMessageId": "msg002"
        }
    ]
}'

响应参数

参数名 类型 说明
code Integer 结果编码，参照响应码说明
message String 请求结果说明
data Array 批量发送结果列表

data数组元素参数：

参数名 类型 说明
phone String 手机号码
messageid String 系统返回的消息ID
status String 发送状态。Success：成功；Failure：失败
message String 失败原因（仅在status为Failure时返回）

响应示例

成功示例

{
    "code": 0,
    "message": "Success",
    "data": [
        {
            "phone": "8618651883168",
            "messageid": "msg001",
            "status": "Success"
        },
        {
            "phone": "8613812345279",
            "messageid": "msg002",
            "status": "Success"
        }
    ]
}

部分失败示例（部分号码发送成功，部分失败）

{
    "code": 0,
    "message": "Success",
    "data": [
        {
            "phone": "8618651883168",
            "messageid": "msg001",
            "status": "Success"
        },
        {
            "phone": "8613812345279",
            "messageid": "msg002",
            "status": "Failure",
            "message": "Incorrect phone number format"
        }
    ]
}

参数错误示例（请求参数不符合要求）

{
    "code": 9000,
    "message": "Request parameter error",
    "data": null
}

应用错误示例（appKey验证失败）

{
    "code": 13002,
    "message": "Unavailable app or incorrect key",
    "data": null
}

响应码说明

code 说明
0 Success
-1 Failure
1000~10XX 详情参照API鉴权常见错误码
1100 Customer does not exist / Status is unavailable
1102 Insufficient balance
9000 Request parameter error
13001 Exceeded content length limit (1000 characters)
13002 Unavailable app or incorrect key
13003 IP not in whitelist
13005 Incorrect phone number format
13006 Incorrect source address (Source address must consist of 1 to 20 alphanumeric characters (letters or digits))
13007 Rate limit exceeded (5 messages per hour)
13008 TPS limit exceeded
13009 Empty content or illegal Keywords
13010 Exceeding maximum numbers for verification channel

⚠️ **GitHub.com Fallback** ⚠️