批量短信 API

通过本 API，您可以在一次请求中批量发送 1-5000 条国际短信，适用于大规模通知、促销活动、提醒和自动化消息发送。PaaSoo 专门针对高集中度发送场景进行了优化，并提供了灵活的参数配置选项，以满足不同业务需求。

功能及使用场景

• 大规模通知：如紧急通知、活动公告或系统维护提醒，需要一次性触达大量用户。
• 营销活动：批量发送优惠券、折扣信息、节日促销等，以快速扩大推广覆盖面。
• 平台服务提示：包括快递物流更新、会员续费提醒、预约确认等。
• 自动化任务：通过定时或事件驱动的方式，批量向特定人群发送短信，提升效率。

通过此API，您可以将多个号码一次性打包发送，同时跟踪和管理每条短信的发送状态和消息ID。也可以使用 batchid 在后续进行查询、统计或对账。 若需检查批量短信的投递结果或成功率，请参阅 批量发送成功率查询 API 获取更多信息。

---

1.调用方式

调用方式

• HTTP Method：POST
• Content-Type：application/x-www-form-urlencoded
• 请求地址： https://api.paasoo.cn/batch_json

注意事项

• 每次请求批量发送数量必须在 1-5000 条之间，超过此范围会返回错误状态码。
• 对批量号码做去重和有效性检查，减少因无效号码或重复号码带来的失败。
• 在大规模投递前，建议先在测试环境或小范围进行验证，以确保模板和参数正确。

---

2.请求格式

以下是使用 POST 请求的典型示例，需要在请求体中以 URL 编码（ application/x-www-form-urlencoded ）格式传递参数：

cURL

curl -X POST "https://api.paasoo.cn/batch_json" \ 
-H "Content-Type: application/x-www-form-urlencoded" \ 
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=8618911111111,8618922222222&text=This+is+test+sms+from+TEST"

在上述示例中：

• to 参数接受用逗号分隔的多个号码，如 8618911111111,8618922222222。
• text 参数已进行 URL 编码，This+is+test+sms+from+TEST 表示实际的短信内容。
• 请确保 key 和 secret 分别替换为在 PaaSoo 后台获取的凭证，并妥善保管。

---

3.请求参数说明

以下参数中，标注为『仅印度适用』的仅在向印度本地号码发送（或使用印度本地通信通道）时适用；其他国家/地区请勿填写，否则可能发送失败。

参数	类型	必填	描述	示例
key	string	是	API Key（字母或数字构成，共 8 位），用于唯一标识您的账户。可在PaaSoo 客户端后台获取。	Abcdefgh
secret	string	是	API Secret（字母或数字构成，共 8 位），与 key 配合使用以进行身份验证。可在PaaSoo 客户端后台获取。	Abc123EF
from	string	是	短信发件人显示名称（Sender ID）。仅部分国家/地区支持自定义，且可能存在长度或字符限制。如需使用特定 Sender ID，请联系您的客户经理或技术支持（support@paasoo.com）。	TEST
to	string	是	发送目标号码，格式为国家区号 + 手机号码（不含前导 00 或 +）。 支持 1 - 5000 个手机号码； 多个号码之间用英文逗号(,)分隔； 建议验证号码合规后再提交。	8618911111111,8618922222222
text	string	是	短信内容（请使用 URL Encode 处理）。字符串长度超限时可能被拆分为多条，产生额外费用。	This is test sms from TEST
peid	string	否	印度模板的 Principal Entity ID。仅印度适用。需在印度 DLT 平台完成注册并向客户经理申请开通。	1401480220000021629
templateid	string	否	印度模板 ID，仅印度适用。与 DLT 平台上的模板名称对应。需完成注册并联系客户经理开通。	1407160568716357486

注意：

• from 的显示在不同国家或运营商环境下受本地政策限制。
• text 中包含空格或特殊字符时，需进行 URL 编码。
• 为保障安全，请勿将 API Key 和 API Secret 暴露在前端应用或公开位置。
• 如需发送更高量的短信，您可以多次调用本接口来实现大规模发送。

---

4.响应参数说明

批量短信请求成功时，会返回批量级别的状态信息，以及每个号码对应的发送结果。可通过 batchid 在后续进行查询、统计或追踪。

参数	类型	描述	示例
status	integer	整个批次的处理结果。0 表示成功接收并处理请求。	0
status_code	string	响应状态。提交至PaaSoo云通讯平台的响应状态码。一般来说，0 代表成功。	Invalid credentials
batchid	string	批量请求ID，每次请求生成一个全局唯一值用于后续查询或统计。	a0018f-e4bf51-e000
data	array	批量号码对应的发送详情列表，包括对每个号码的处理结果。	[...]

data 数组中每个元素：

参数	类型	描述	示例
to	string	短信发送目标号码。	8618911111111
messageid	string	消息ID，用于单条短信发送记录区分。	00018f-e4bf51-e002
status	integer	单个号码的发送状态码。0 代表成功。	0
status_code	string	该号码的错误原因或描述，可帮助定位问题。	Missing parameters

以下是常见返回结果示例：

4.1 成功示例

{ 
    "status": 0, 
    "status_code": "success", 
    "batchid": "a0018f-e4bf51-e000", 
    "data": [
        { 
            "status": 0,
            "to": "8618911111111",
            "messageid": "00018f-e4bf51-e002"
        },
        {
            "status": 0,
            "to": "8618922222222",
            "messageid": "00018f-e4bf51-e003"
        }
    ]
}

4.2 失败示例

{ "status": 4, "status_code": "Invalid credentials."}

---

5. 接口状态码列表

• 0 - success：成功
• 2 - Missing parameters：缺少必要参数
• 3 - Invalid parameters：参数格式错误
• 4 - Invalid credentials：API Key 或 API Secret 错误
• 5 - Unauthorized IP：IP 限制
• 6 - Invalid phone number：号码格式错误
• 7 - Invalid sender id：from 参数格式错误
• 8 - Message bombing detected：3 秒内重复请求
• 9 - Quota exceeded：欠费或信用额度不足
• 10 - Throttling error：超过限速
• 11 - System error：系统错误
• 14 - Nb of messages per request should be between 1 and 5000
• 19 - Invalid peid / Invalid templateid

本接口默认提供极高的发送弹性。若您在调用时收到错误码status=10，说明您的账户已根据业务约定开启了自定义速率限制。如需调整限速阈值，请联系您的客户经理或 PaaSoo 技术支持团队（support@paasoo.com）。

---

6.代码示例

以下是如何在各种主流的编程语言中，集成 “批量发送国际短信 API” 的简单示例。

Python

import requests

# API 端点
url = "https://api.paasoo.cn/batch_json"

# 表单数据
payload = {
    "key": "API_KEY",                         # 替换为您的 API Key
    "secret": "API_SECRET",                   # 替换为您的 API Secret
    "from": "TEST",                           # 发送者 ID
    "to": "8618911111111,8618922222222",      # 目的手机号码，以逗号分隔
    "text": "这是一条来自 TEST 的测试短信"        # 短信内容
}

# 请求头
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

try:
    # 发送 HTTP POST 请求
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    
    # 解析并打印 JSON 响应
    data = response.json()
    if data.get("status") == 0:
        print("群发短信发送成功，batchid:", data.get("batchid"))
    else:
        print(f"群发短信发送失败，状态: {data.get('status')}，信息: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

Node.js

const axios = require('axios'); // 运行: npm install axios

// API 端点
const url = 'https://api.paasoo.cn/batch_json';

// 准备 URL 编码的表单数据
const data = new URLSearchParams({
    key: 'API_KEY',                      // 替换为您的 API Key
    secret: 'API_SECRET',                // 替换为您的 API Secret
    from: 'TEST',                        // 发送者 ID
    to: '8618911111111,8618922222222',   // 目的手机号码，以逗号分隔
    text: '这是一条来自 TEST 的测试短信'     // 短信内容
});

// 发送 HTTP POST 请求
axios.post(url, data.toString(), {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === 0) {
        console.log('群发短信发送成功，batchid:', result.batchid);
    } else {
        console.log('群发短信发送失败，状态:', result.status, '信息:', result.status_code);
    }
})
.catch((error) => {
    console.error('请求失败:', error.message || error);
});

PHP

<?php

// API 端点
$url = "https://api.paasoo.cn/batch_json";

// 请求参数
$data = [
    "key" => "API_KEY",                    // 替换为您的 API Key
    "secret" => "API_SECRET",              // 替换为您的 API Secret
    "from" => "TEST",                      // 发送者 ID
    "to" => "8618911111111,8618922222222", // 目的手机号码，以逗号分隔
    "text" => "这是一条来自 TEST 的测试短信"   // 短信内容
];

// 初始化 cURL 会话
$ch = curl_init($url);

// 设置 POST 和 x-www-form-urlencoded 的 cURL 选项
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/x-www-form-urlencoded"
]);

// 执行请求
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "请求失败: " . $e;
} else {
    $result = json_decode($response, true);
    if (isset($result['status']) && $result['status'] === 0) {
        echo "群发短信发送成功，batchid: " . $result['batchid'] . "\n";
    } else {
        echo "群发短信发送失败，状态: " . $result['status'] . "，信息: " . $result['status_code'] . "\n";
    }
}

// 关闭 cURL 会话
curl_close($ch);
?>

Java

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.FormBody;
import okhttp3.Response;
import java.io.IOException;

// 请确保在 pom.xml 或 build.gradle 中添加 OkHttp 依赖
public class BulkSmsApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // 构建 x-www-form-urlencoded 请求体
        RequestBody formBody = new FormBody.Builder()
                .add("key", "API_KEY")                          // 替换为您的 API Key
                .add("secret", "API_SECRET")                    // 替换为您的 API Secret
                .add("from", "TEST")                            // 发送者 ID
                .add("to", "8618911111111,8618922222222")       // 目的手机号码
                .add("text", "这是一条来自 TEST 的测试短信")        // 短信内容
                .build();

        // 构建请求
        Request request = new Request.Builder()
                .url("https://api.paasoo.cn/batch_json")
                .post(formBody)
                .addHeader("Content-Type", "application/x-www-form-urlencoded")
                .build();

        // 执行请求
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("响应: " + response.body().string());
            } else {
                System.out.println("请求失败，状态码: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("请求失败: " + e.getMessage());
        }
    }
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
    "strings"
)

func main() {
    apiURL := "https://api.paasoo.cn/batch_json"

    // 准备表单数据
    data := url.Values{}
    data.Set("key", "API_KEY")                          // 替换为您的 API Key
    data.Set("secret", "API_SECRET")                    // 替换为您的 API Secret
    data.Set("from", "TEST")                            // 发送者 ID
    data.Set("to", "8618911111111,8618922222222")       // 目的手机号码
    data.Set("text", "这是一条来自 TEST 的测试短信")        // 短信内容

    // 发送 HTTP POST 请求
    req, err := http.NewRequest("POST", apiURL, strings.NewReader(data.Encode()))
    if err != nil {
        fmt.Println("创建请求时发生错误:", err)
        return
    }
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("请求失败:", err)
        return
    }
    defer resp.Body.Close()

    // 读取响应体
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("读取响应时发生错误:", err)
        return
    }

    // 解析 JSON
    var result map[string]interface{}
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Println("解析 JSON 时发生错误:", err)
        return
    }

    // 检查状态（注意：在 Go 中，JSON 数字默认被解析为 float64）
    if status, ok := result["status"].(float64); ok && status == 0 {
        fmt.Println("群发短信发送成功，batchid:", result["batchid"])
    } else {
        fmt.Printf("群发短信发送失败，状态: %v，信息: %v\n", result["status"], result["status_code"])
    }
}

任何支持 HTTP/HTTPS 的语言或框架都可轻松对接，用相同的 POST 方法和 application/x-www-form-urlencoded 进行请求即可。

---

7. 最佳实践

1. 号码验证与清洗：在批量下发前去除无效或重复号码，减少因无效号码导致的浪费及错误。
2. 遵循发送频率限制：避免在极短时间内一次性发送过多短信，如有较大规模的需求，可多次调用该API。
3. 内容与编码：短信内容应进行 URL 编码，注意超长内容被拆分成多条时需额外关注费用或计费。
4. 发送日志与监控：在后端记录 batchid 并保存每条短信的 status 和 messageid，方便追踪。
5. 重试与幂等：若网络波动或其他异常，可设定重试机制并使用唯一请求ID，避免重复发送。
6. 数据安全与合规：遵守各目标国家或地区的隐私及短信发送规定。对于营销类短信，应事先取得用户同意。

通过以上步骤以及最佳实践，您可以快速实现对全球用户的批量短信发送。 如果需要了解批量短信的投递结果或成功率，请查看 批量发送成功率查询 API 以获取更多信息。

技术支持

如在 API 对接过程中遇到任何技术问题或业务疑问，欢迎随时联系我们的开发者支持团队：support@paasoo.com。我们将竭诚为您提供技术协助。