簡訊 API

歡迎使用 PaaSoo 的簡訊 API 服務！透過此 API，您可以快速向世界各地發送單則簡訊訊息，以滿足不同業務場景（如身分驗證、行銷推廣、訂單通知等）的需求。PaaSoo 提供全球簡訊服務，透過與營運商的直接連線和多年的經驗，確保高效可靠的簡訊傳遞。本指南提供了完整且詳細的 API 使用說明、參數解釋、範例及最佳實踐，幫助您順利整合並充分利用簡訊 API 服務。

1. API 概述

支援覆蓋 200+ 國家和地區的國際簡訊發送，包含驗證碼、服務通知和行銷等多種場景（具體覆蓋範圍以營運商通道為準）。透過本 API，您可以：

• 向全球範圍的手機用戶發送簡訊
• 設定自訂簡訊發件人（Sender ID），具體功能取決於目的地國家的營運商政策
• 追蹤簡訊發送結果、狀態變更和錯誤原因
• 靈活整合到您的應用程式、網站或後台服務中

說明

由於各國營運商法規及網路協定的差異，某些國家或地區可能不支援自訂發件人或其他進階功能。若需要此類自訂功能，請聯絡您的客戶經理或將問題發送至：support@paasoo.com。

---

2. 呼叫方式

呼叫方式

• HTTP Method：GET
• 請求位址： https://api.paasoo.com.tw/json

在呼叫此 API 之前，請確保您已在用戶後台取得 API Key 和 API Secret。這兩者都需要在請求中以查詢參數（Query Params）方式攜帶。

建議

為了保證資料的機密性與安全性，我們強烈建議您使用 HTTPS 協定來呼叫介面，從而避免在傳輸過程中遭受竊聽或竄改。

---

3. 請求範例

最簡單的範例，僅透過 HTTP GET 請求帶上必要的參數：

https://api.paasoo.com.tw/json?key=API_KEY&secret=API_SECRET&from=TEST&to=886912345678&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 或 +）。如台灣號碼寫作 886912345678。	886912345678
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

import requests

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

# 查詢參數
params = {
    "key": "API_KEY",                # 替換為您的 API Key
    "secret": "API_SECRET",          # 替換為您的 API Secret
    "from": "TEST",                  # 發送者 ID (Sender ID)
    "to": "886912345678",            # 目標號碼
    "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}")

Node.js

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

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

// 查詢參數
const params = {
    key: 'API_KEY',               // 替換為您的 API Key
    secret: 'API_SECRET',         // 替換為您的 API Secret
    from: 'TEST',                 // 發送者 ID (Sender ID)
    to: '886912345678',           // 目標號碼
    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

<?php

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

// 查詢參數
$params = [
    "key" => "API_KEY",             // 替換為您的 API Key
    "secret" => "API_SECRET",       // 替換為您的 API Secret
    "from" => "TEST",               // 發送者 ID (Sender ID)
    "to" => "886912345678",         // 目標號碼
    "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);
?>

Java

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.com.tw/json").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");         // 替換為您的 API Key
        urlBuilder.addQueryParameter("secret", "API_SECRET");   // 替換為您的 API Secret
        urlBuilder.addQueryParameter("from", "TEST");           // 發送者 ID (Sender ID)
        urlBuilder.addQueryParameter("to", "886912345678");     // 目標號碼
        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());
        }
    }
}

Go

package main

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

func main() {
    // 解析基礎 URL
    baseURL, err := url.Parse("https://api.paasoo.com.tw/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 (Sender ID)
    params.Add("to", "886912345678")         // 目標號碼
    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. 狀態報告接收與查詢

在某些場景中，您可能需要取得簡訊的最終送達 (Delivered) 狀態或退回原因（如號碼無法連通、用戶停機等）。您可以在客戶後台查看發送狀態，也可以透過以下方式：

• 呼叫狀態報告查詢 API 以取得簡訊的即時投遞結果
• 設定回呼 URL（Webhook），以非同步方式透過狀態報告接收 API 來取得簡訊送達或失敗 (Failed) 報告

具體如何設定與使用這些方式，請參閱對應的文件說明。

---

9. 最佳實踐

1. 參數安全：在後端安全地儲存和使用 API Key 與 API Secret，切勿在前端暴露。
2. 請求限速：PaaSoo 平台預設不設統一的併發限制，以支援客戶業務的快速成長。但在特定場景下，為了保障您的帳戶安全或根據合約約定，我們可以為您設定個性化的 QPS（每秒請求數）限制。若您的業務量預計會有爆發式增長，請提前告知客戶經理以確保通道資源充足。
3. 內容合規：遵守當地法規，不發送敏感、違法或不當內容，避免帳戶被封鎖。
4. 編碼與長度控制：當使用非拉丁字元時，簡訊內容很可能以 Unicode 方式發送，長度上限會更低；請參考 GSM 7-bit 和 Unicode 編碼的區別。
5. 測試環境：在生產環境正式部署前，建議先在測試號碼或沙箱環境上進行充分測試，確保整合正確。
6. 監控與日誌：建立日誌等級和監控報警機制，及時監測發送量與成功率。
7. 冪等性設計：若要保證同一則簡訊只發送一次，請為每次請求生成唯一 requestId，並在伺服器端進行去重處理。

---

10. 常見問題（FAQ）

為何我的 Sender ID 不生效？

• 可能原因包括該國家指定的 Sender ID 限制、本地營運商要求預先註冊、或營運商策略限制等。若需客製化 Sender ID，請聯絡客戶經理了解更多詳情。

我可以發送含有中文、日文或表情符號的內容嗎？

• 可以，但需確保使用 UTF-8 進行編碼，並進行 URL 編碼。非 GSM 字元會占用更多字元空間，可能引發簡訊拆分或長度限制。

為什麼出現了 "status = 9 / Quota exceeded "？

• 表示您的帳戶餘額不足或信用額度已用完。請及時儲值或聯絡銷售人員增加額度。

如何取得簡訊最終的送達或失敗原因？

• 您可以在管理控制台直接查詢狀態報告，也可呼叫狀態報告查詢 API 或開通回呼 URL (Webhook) 狀態報告接收來取得最終狀態更新。

如何發送批次簡訊？

• 建議使用我們提供的批次簡訊 API 或分批呼叫單條簡訊 API，並實作併發或佇列控制。詳細資訊請參閱我們的批次簡訊 API 文件。

---

11. 附錄

1. Unicode 與 GSM 7-bit 編碼：
   • GSM 7-bit 編碼：
     • 160 個字元以內：按 1 條計費。
     • 超過 160 個字元：按 153 個字元/條 拆分計費（預留 7 個字元作為長簡訊合併的識別頭/UDH）。
   • Unicode 編碼：
     • 70 個字元以內：按 1 條計費。
     • 超過 70 個字元：按 67 個字元/條 拆分計費。
2. Concatenated SMS（長簡訊拆分）：
   • 一旦訊息長度超過最大字元限制，營運商會將簡訊拆分並發送。一般情況下，平台會自動處理拆分、排序和合併，可能產生額外的計費訊息數。
3. DLT 註冊（印度）：
   • 由於印度的電信法規，所有用於發送行銷或企業簡訊的歸屬方需在 DLT 平台完成註冊。
   • 若需在印度發送本地簡訊並支援模版 ID、PEID 等參數，請務必遵守當地政策。
4. IP白名單與安全：
   • 若您的帳戶設定了 IP白名單，請在存取 API 時確保請求來源 IP 在白名單內，以避免觸發 status = 5（IP 限制）。

重要提醒

• 由於全球各國營運商及不同下發通道的計費邏輯存在差異，上述長度僅供參考。實際計費條數將以目的地國家營運商的結算規則及 PaaSoo 系統的最終計費扣費記錄或帳單回饋為準。
• 建議在大規模發送前，透過測試號碼觀察實際扣費情況。

技術支援

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