短信 API

欢迎使用 PaaSoo 的短信 API 服务！通过此 API，您可以快速向世界各地发送单条短信消息，以满足不同业务场景（如身份验证、营销推广、订单通知等）的需求。PaaSoo 提供全球短信服务，通过与运营商的直接连接和多年的经验，确保高效可靠的短信传递。本指南提供了完整且详细的 API 使用说明、参数解释、示例及最佳实践，帮助您顺利集成并充分利用短信 API 服务。

1. API 概述

支持覆盖 200+ 国家和地区的国际短信发送，包含验证码、服务通知和营销等多种场景（具体覆盖范围以运营商通道为准）。通过本 API，您可以：

向全球范围的手机用户发送短信
设置自定义短信发件人（Sender ID），具体功能取决于目的地国家的运营商政策
跟踪短信发送结果、状态变更和错误原因
灵活集成到您的应用、网站或后台服务中

说明

由于各国运营商法规及网络协议的差异，某些国家或地区可能不支持自定义发件人或其他高级功能。若需要此类自定义功能，请联系您的客户经理或将问题发送至：support@paasoo.com。

2. 调用方式

调用方式

HTTP Method：GET
请求地址： https://api.paasoo.cn/json

在调用此API之前，请确保您已在用户后台获取到 API Key 和 API Secret。这两者都需要在请求中以查询参数（Query Params）方式携带。

建议

为了保证数据的机密性与安全性，我们强烈建议您使用 HTTPS 协议来调用接口，从而避免在传输过程中遭受窃听或篡改。

3. 请求示例

最简单的示例，仅通过 HTTP GET 请求带上必要的参数：

https://api.paasoo.cn/json?key=API_KEY&secret=API_SECRET&from=TEST&to=8618911111111&text=This+is+test+sms+from+TEST

上面示例中的 text 参数已使用 URL 编码，请在实际使用时务必进行正确的编码处理。

4. 请求参数说明

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

参数	类型	必填	描述	示例
key	string	是	API Key（由 8 位字母或数字构成），用户唯一标识，可在客户端后台获取，请妥善保管。	Abcdefgh
secret	string	是	API Secret（字母或数字构成，共 8 位），与 `key` 配合使用以进行身份验证。可在PaaSoo 客户端后台获取。	Abc123EF
from	string	是	短信发件人显示名称（Sender ID）。仅部分国家/地区支持自定义，且可能存在长度或字符限制。如需使用特定 Sender ID，请联系您的客户经理或技术支持（support@paasoo.com）。	TEST
to	string	是	发送目标号码，格式为`国家区号 + 手机号码`（不含前导 00 或 +）。如中国号码写作 8618911111111。	8618911111111
text	string	是	短信内容，需要通过 URL Encode 方式进行 UTF-8 编码。如需简单测试，可通过第三方工具或后端自动编码。	This is test sms from TEST
requestId	string	否	唯一请求 ID，用于标识此次请求以便追踪和排查异常。若需保证幂等性，每次请求请使用不同的 `requestId`；若在60秒内使用了相同的请求 ID，则视作同一个请求。系统将返回第一次请求的相同响应结果，而不会重复扣费或重复发送。	0432258a-ecc7-4628-9158-2b883fe65181
peid	string	否	印度模板的 Principal Entity ID。仅印度适用。如需在印度发送短信并使用此参数，需在印度 DLT 平台完成注册并联系客户经理开通。	1401480220000021629
templateid	string	否	印度模板 ID。仅印度适用。如需在印度发送短信并使用此参数，需在印度 DLT 平台完成注册并联系客户经理开通。	1407160568716357486
ref	string	否	客户自定义参数，用于将初始请求与 PaaSoo 的响应（通过异步通知或查询结果返回）进行关联。

注意

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

5. 响应参数说明

成功时，接口会返回状态码并携带对应的消息ID。
失败时，会返回相应的错误状态码及说明。

参数	类型	描述	示例
messageid	string	消息ID，每条短信记录的唯一标识。	015bd4-d6dfa7-58w
status	string	响应状态。提交至PaaSoo云通讯平台的响应状态码。一般来说，"0" 代表成功。	"0" - success
status_code	string	状态说明，用于说明错误原因或详细状态。	Missing parameters

5.1 成功响应示例

{ "status": "0", "messageid": "015bd4-d6dfa7-58w"}

5.2 失败响应示例

{ "status": "2", "status_code": "Missing parameters."}

6. 接口状态码列表

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：系统错误
19 - Invalid peid / Invalid templateid

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

7. 代码示例

以下提供多种语言的调用示例，帮助您快速整合到现有系统：

Python
Node.js
PHP
Java
Go

import requests

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

# 查询参数
params = {
    "key": "API_KEY",                # 替换为您的 API Key
    "secret": "API_SECRET",          # 替换为您的 API Secret
    "from": "TEST",                  # 发送者 ID
    "to": "8618911111111",           # 目标号码
    "text": "这是一条来自 TEST 的测试短信"
}

try:
    # 发送 HTTP GET 请求
    response = requests.get(url, params=params)
    response.raise_for_status()
    
    # 解析并打印 JSON 响应
    data = response.json()
    if data.get("status") == "0":
        print("短信发送成功，messageid:", data.get("messageid"))
    else:
        print(f"短信发送失败，status: {data.get('status')}, message: {data.get('status_code')}")

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

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

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

// 查询参数
const params = {
    key: 'API_KEY',               // 替换为您的 API Key
    secret: 'API_SECRET',         // 替换为您的 API Secret
    from: 'TEST',                 // 发送者 ID
    to: '8618911111111',          // 目标号码
    text: '这是一条来自 TEST 的测试短信',
};

// 发送 HTTP GET 请求
axios.get(url, { params })
    .then((response) => {
        const data = response.data;
        if (data.status === '0') {
            console.log('短信发送成功，messageid:', data.messageid);
        } else {
            console.log('短信发送失败，status:', data.status, 'message:', data.status_code);
        }
    })
    .catch((error) => {
        console.error('请求失败:', error.message || error);
    });

<?php

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

// 查询参数
$params = [
    "key" => "API_KEY",             // 替换为您的 API Key
    "secret" => "API_SECRET",       // 替换为您的 API Secret
    "from" => "TEST",               // 发送者 ID
    "to" => "8618911111111",        // 目标号码
    "text" => "这是一条来自 TEST 的测试短信"
];

// 构建查询字符串并附加到 URL
$queryString = http_build_query($params);
$requestUrl = $url . '?' . $queryString;

// 初始化 cURL 会话
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $requestUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

if($e = curl_error($ch)) {
    echo "请求失败: " . $e;
} else {
    $data = json_decode($response, true);
    if ($data['status'] === "0") {
        echo "短信发送成功，messageid: " . $data['messageid'] . "\n";
    } else {
        echo "短信发送失败，status: " . $data['status'] . ", message: " . $data['status_code'] . "\n";
    }
}

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

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.HttpUrl;
import java.io.IOException;

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

        // 构建带有查询参数的 URL
        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://api.paasoo.cn/json").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");         // 替换为您的 API Key
        urlBuilder.addQueryParameter("secret", "API_SECRET");   // 替换为您的 API Secret
        urlBuilder.addQueryParameter("from", "TEST");           // 发送者 ID
        urlBuilder.addQueryParameter("to", "8618911111111");    // 目标号码
        urlBuilder.addQueryParameter("text", "这是一条来自 TEST 的测试短信");

        String url = urlBuilder.build().toString();

        // 构建请求
        Request request = new Request.Builder()
                .url(url)
                .get()
                .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());
        }
    }
}

package main

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

func main() {
    // 解析基础 URL
    baseURL, err := url.Parse("https://api.paasoo.cn/json")
    if err != nil {
        fmt.Println("解析 URL 错误:", err)
        return
    }

    // 添加查询参数
    params := url.Values{}
    params.Add("key", "API_KEY")             // 替换为您的 API Key
    params.Add("secret", "API_SECRET")       // 替换为您的 API Secret
    params.Add("from", "TEST")               // 发送者 ID
    params.Add("to", "8618911111111")        // 目标号码
    params.Add("text", "这是一条来自 TEST 的测试短信")

    // 编码参数并附加到 URL
    baseURL.RawQuery = params.Encode()

    // 发送 HTTP GET 请求
    resp, err := http.Get(baseURL.String())
    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
    }

    // 检查状态
    if status, ok := result["status"].(string); ok && status == "0" {
        fmt.Println("短信发送成功，messageid:", result["messageid"])
    } else {
        fmt.Printf("短信发送失败，status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

由于本 API 仅依赖 HTTP 请求，所以您可以基于任意支持 HTTP/HTTPS 的语言或框架来实现。只需按照相同的查询参数拼接方式即可。

8. 发送报告与状态回调

在某些场景中，您可能需要获取短信的最终送达状态或退回原因（如号码不可达、用户停机等）。您可以在客户后台查看发送状态，也可以通过以下方式：

调用状态报告查询 API 以获取短信的实时投递结果
配置回调URL（Webhook），以异步方式状态报告回调 API 来获取短信送达或失败报告

具体如何配置与使用这些方式，请参阅对应的文档说明。

9. 最佳实践

参数安全：在后端安全地存储和使用 API Key 与 API Secret，切勿在前端暴露。
请求限速：PaaSoo 平台默认不设统一的并发限制，以支持客户业务的快速增长。但在特定场景下，为了保障您的账号安全或根据合同约定，我们可以为您配置个性化的 QPS（每秒请求数）限制。若您的业务量预计会有爆发式增长，请提前告知客户经理以确保通道资源充足。
内容合规：遵守当地法规，不发送敏感、违法或不当内容，避免账号被封。
编码与长度控制：当使用非拉丁字符时，短信内容很可能以 Unicode 方式发送，长度上限会更低；请参考 GSM 7-bit 和 Unicode 编码的区别。
测试环境：在生产环境正式部署前，建议先在测试号码或沙箱环境上进行充分测试，确保集成正确。
监控与日志：建立日志等级和监控报警机制，及时监测发送量与成功率。
幂等性设计：若要保证同一条短信只发送一次，请为每次请求生成唯一 requestId，并在服务器端进行去重处理。

10. 常见问题（FAQ）

为何我的 Sender ID 不生效？

可能原因包括该国家指定的 Sender ID 限制、Local Operator 要求预先注册、或运营商策略限制等。若需定制化 Sender ID，请联系客户经理了解更多详情。

我可以发送含有中文、日文或表情符号的内容吗？

可以，但需确保使用UTF-8进行编码，并进行URL编码。非GSM字符会占用更多字符空间，可能引发短信拆分或长度限制。

为什么出现了 "status = 9 / Quota exceeded "？

表示您的账户余额不足或信用额度已用完。请及时充值或联系销售人员增加额度。

如何获取短信最终的送达或失败原因？

您可以在管理控制台直接查询发送报告，也可调用状态报告查询 API 或开通回调 URL（Webhook）状态报告接收来获取最终状态更新。

如何发送批量短信？

建议使用我们提供的批量短信 API 或分批调用单条短信 API，并实现并发或队列控制。详细信息请参阅我们的批量短信 API 文档。

11. 附录

Unicode 与 GSM 7-bit 编码：
- GSM 7-bit 编码：
  - 160 个字符以内：按 1 条计费。
  - 超过 160 个字符：按 153 个字符/条拆分计费（预留 7 个字符作为长短信合并的识别头/UDH）。
- Unicode 编码：
  - 70 个字符以内：按 1 条计费。
  - 超过 70 个字符：按 67 个字符/条拆分计费。
Concatenated SMS（长短信拆分）：
- 一旦消息长度超过最大字符限制，运营商会将短信拆分并发送。一般情况下，平台会自动处理拆分、排序和合并，可能产生额外的短信计费。
DLT注册（印度）：
- 由于印度的电信法规，所有用于发送营销或企业短信的归属方需在 DLT 平台完成注册。
- 若需在印度发送本地 SMS 并支持模板 ID、PEID 等参数，请务必遵守当地政策。
IP限制与安全：
- 若您的账户设置了 IP 白名单，请在访问API时确保请求源 IP 在白名单内，以避免触发 status = 5（IP 限制）。

重要提醒

由于全球各国运营商及不同下发通道的计费逻辑存在差异，上述长度仅供参考。实际计费条数将以目的地国家运营商的结算规则及 PaaSoo 系统的最终计费扣费记录或账单反馈为准。
建议在大规模发送前，通过测试号码观察实际扣费情况。

技术支持

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

1. API 概述​

2. 调用方式​

3. 请求示例​

4. 请求参数说明​

5. 响应参数说明​

5.1 成功响应示例​

5.2 失败响应示例​

6. 接口状态码列表​

7. 代码示例​

8. 发送报告与状态回调​

9. 最佳实践​

10. 常见问题（FAQ）​

11. 附录​