批次簡訊 API

透過本 API，您可以在一次請求中批次發送 1-5000 條國際簡訊，適用於大規模通知、促銷活動、提醒和自動化訊息發送。PaaSoo 專門針對高集中度發送場景進行了最佳化，並提供了靈活的參數設定選項，以滿足不同業務需求。

功能及使用場景

大規模通知：如緊急通知、活動公告或系統維護提醒，需要一次性觸及大量用戶。
行銷活動：批次發送優惠券、折扣資訊、節日促銷等，以快速擴大推廣覆蓋面。
平台服務提示：包括快遞物流更新、會員續費提醒、預約確認等。
自動化任務：透過定時或事件驅動的方式，批次向特定人群發送簡訊，提升效率。

透過此 API，您可以將多個號碼一次性打包發送，同時追蹤和管理每條簡訊的發送狀態和簡訊 ID。也可以使用 batchid 在後續進行查詢、統計或對帳。若需檢查批次簡訊的投遞結果或成功率，請參閱批量發送成功率查詢 API 取得更多資訊。

1. 呼叫方式

呼叫方式

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
請求位址： https://api.paasoo.com.tw/batch_json

注意事項

每次請求批次發送數量必須在 1-5000 條之間，超過此範圍會返回錯誤狀態碼。
對批次號碼做去重和有效性檢查，減少因無效號碼或重複號碼帶來的失敗。
在大規模投遞前，建議先在測試環境或小範圍進行驗證，以確保模版和參數正確。

2. 請求格式

以下是使用 POST 請求的典型範例，需要在請求體中以 URL 編碼（ application/x-www-form-urlencoded ）格式傳遞參數：

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

在上述範例中：

to 參數接受用逗號分隔的多個號碼，如 886912345678,886912345679。
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 個手機號碼；多個號碼之間用英文逗號(,)分隔；建議驗證號碼合規後再提交。	886912345678,886912345679
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	簡訊發送目標號碼。	886912345678
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": "886912345678",
            "messageid": "00018f-e4bf51-e002"
        },
        {
            "status": 0,
            "to": "886912345679",
            "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
Node.js
PHP
Java
Go

import requests

# API 端點
url = "https://api.paasoo.com.tw/batch_json"

# 表單資料
payload = {
    "key": "API_KEY",                         # 替換為您的 API Key
    "secret": "API_SECRET",                   # 替換為您的 API Secret
    "from": "TEST",                           # 發送者 ID (Sender ID)
    "to": "886912345678,886912345679",        # 目的手機號碼，以逗號分隔
    "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}")

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

// API 端點
const url = 'https://api.paasoo.com.tw/batch_json';

// 準備 URL 編碼的表單資料
const data = new URLSearchParams({
    key: 'API_KEY',                      // 替換為您的 API Key
    secret: 'API_SECRET',                // 替換為您的 API Secret
    from: 'TEST',                        // 發送者 ID (Sender ID)
    to: '886912345678,886912345679',      // 目的手機號碼，以逗號分隔
    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

// API 端點
$url = "https://api.paasoo.com.tw/batch_json";

// 請求參數
$data = [
    "key" => "API_KEY",                    // 替換為您的 API Key
    "secret" => "API_SECRET",              // 替換為您的 API Secret
    "from" => "TEST",                      // 發送者 ID (Sender ID)
    "to" => "886912345678,886912345679",    // 目的手機號碼，以逗號分隔
    "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);
?>

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 (Sender ID)
                .add("to", "886912345678,886912345679")          // 目的手機號碼
                .add("text", "這是一條來自 TEST 的測試簡訊")        // 簡訊內容
                .build();

        // 建構請求
        Request request = new Request.Builder()
                .url("https://api.paasoo.com.tw/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());
        }
    }
}

package main

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

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

    // 準備表單資料
    data := url.Values{}
    data.Set("key", "API_KEY")                          // 替換為您的 API Key
    data.Set("secret", "API_SECRET")                    // 替換為您的 API Secret
    data.Set("from", "TEST")                            // 發送者 ID (Sender ID)
    data.Set("to", "886912345678,886912345679")          // 目的手機號碼
    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. 最佳實踐

號碼驗證與清洗：在批次下發前去除無效或重複號碼，減少因無效號碼導致的浪費及錯誤。
遵循發送頻率限制：避免在極短時間內一次性發送過多簡訊，如有較大規模的需求，可多次呼叫該 API。
內容與編碼：簡訊內容應進行 URL 編碼，注意超長內容被拆分成多條時需額外關注費用或計費。
發送日誌與監控：在後端記錄 batchid 並儲存每條簡訊的 status 和 messageid，方便追蹤。
重試與冪等：若網路波動或其他異常，可設定重試機制並使用唯一請求 ID，避免重複發送。
資料安全與合規：遵守各目標國家或地區的隱私及簡訊發送規定。對於行銷類簡訊，應事先取得用戶同意。

透過以上步驟以及最佳實踐，您可以快速實現對全球用戶的批次簡訊發送。如果需要了解批次簡訊的投遞結果或成功率，請查看批量發送成功率查詢 API 以取得更多資訊。

技術支援

如在 API 對接過程中遇到任何技術問題或業務疑問，歡迎隨時聯絡我們的開發者支援團隊：support@paasoo.com。我們將竭誠為您提供技術協助。

功能及使用場景​

1. 呼叫方式​

2. 請求格式​

3. 請求參數說明​

4. 回應參數說明​

4.1 成功範例​

4.2 失敗範例​

5. 介面狀態碼列表​

6. 程式碼範例​

7. 最佳實踐​