轉換追蹤 API

轉換追蹤 API（Conversion Tracking API）用於輔助企業精確衡量 OTP（One‑Time Password，一次性密碼）簡訊在用戶側的實際轉換情況。因為國際簡訊的送達回執常受到營運商和地區監管等多重因素影響，難以確保準確性，企業可透過本 API 即時回傳用戶是否已完成轉換（例如成功登入或驗證），以便 PaaSoo 更好地幫助您追蹤簡訊品質、最佳化通訊管道及提升用戶體驗。

1. 呼叫方式

呼叫方式

HTTP Method：POST
Content-Type：application/json
請求位址：https://api.paasoo.com.tw/conversion

2. 使用場景及重要性

當發送 OTP 簡訊給用戶後，國際簡訊的回執資訊常常會出現延遲或不準確。企業可透過此 API 主動將用戶後續驗證的真實結果告知 PaaSoo（例如用戶在指定時間內輸入了正確驗證碼，說明簡訊確實轉換成功），從而：

輔助品質管理：結合用戶的真實驗證動作，幫助判斷不同國家/地區、營運商或鏈路的實際表現；
成本最佳化：發現轉換率偏低的鏈路並及時調整，降低整體成本；
合作共贏：PaaSoo 可基於真實轉換效果，持續最佳化簡訊發送品質與用戶體驗。

3. 請求範例

cURL
curl -X POST "https://api.paasoo.com.tw/conversion" \ 
    -H "Content-Type: application/json" \ 
    -d '{ "key": "Abcdefgh", "secret": "Abc123EF", "messageid": "015bd4-d6dfa7-58w", "conversionTime": "2022-02-22T01:00:01.000Z", "conversion": 1 }'

其中：

Content-Type 必須為 application/json
請求體使用 JSON 格式，包含本 API 所需的欄位

4. 請求參數說明

參數	類型	必填	描述	範例
key	string	是	API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。	Abcdefgh
secret	string	是	API Secret（字母或數字構成，共 8 位），與 `key` 配合使用以進行身分驗證。可在 PaaSoo 用戶端後台取得。	Abc123EF
messageid	string	是	簡訊 ID，每條簡訊記錄的唯一標識。企業可透過簡訊 API 取得該 ID。	00018f-e4bf51-e002
conversionTime	string	否	轉換時間，採用 ISO8601 標準時間（yyyy-MM-dd'T'HH:mm:ss.SSS'Z'），時區為 UTC+0。預設為本次 API 請求到達伺服器的 UTC 時間。	2022-02-22T01:00:01.000Z
conversion	integer	是	訊息的轉換狀態： 0 - 轉換失敗； 1 - 轉換成功	1

注意事項：

轉換時間務必使用正確的 UTC 時區格式，否則系統可能產生時間差。
由於此 API 透過 key 和 secret 進行認證，請務必在伺服器端呼叫並妥善保管憑證，避免在前端暴露。
若您未能準確取得用戶操作時間，可選擇不傳遞 conversionTime，系統會自動記錄為伺服器接收請求的 UTC 時間。

5. 回應參數說明

轉換追蹤請求提交後，系統會返回相應的狀態碼以確認請求是否被成功接收處理。

參數	類型	描述	範例
status	string	回應狀態。提交至 PaaSoo 雲通訊平台的回應狀態碼。 0 - success：成功 2 - Missing parameters：缺少必要參數 3 - Invalid parameters：參數格式錯誤 4 - Invalid credentials：Key或Secret錯誤 11 - System error：系統錯誤	"0"
status_details	string	狀態描述，用於說明錯誤原因或詳細資訊。	Missing parameters

以下是常見返回結果範例：

5.1 成功範例

{ "status": "0", "status_details": "success"}

5.2 失敗範例

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

6. 常見錯誤與排查

2 - Missing parameters：檢查是否漏傳 key、secret、messageid 或其他必填欄位。
3 - Invalid parameters：參數格式錯誤，如 conversion 傳入非數字、時間格式不符合 ISO8601 等。
4 - Invalid credentials：API Key 或 API Secret 不匹配，請確認憑證的正確性。
11 - System error：伺服器內部錯誤，如伺服器處理異常、無法解析請求等。若多次出現，請聯絡技術支援。

7. 程式碼範例

以下範例展示如何使用常見語言呼叫本 API：

Python
Node.js
PHP
Java
Go

import requests

# API 介面端點
url = "https://api.paasoo.com.tw/conversion"

# 請求負載 (Payload)
payload = {
    "key": "API_KEY",                             # 替換為您的 API Key
    "secret": "API_SECRET",                       # 替換為您的 API Secret
    "messageid": "015bd4-d6dfa7-58w",             # 來自簡訊 API 的 Message ID
    "conversionTime": "2022-02-22T01:00:01.000Z", # 選填：ISO8601 格式的 UTC 時間
    "conversion": 1                               # 1 表示成功，0 表示失敗
}

# 請求標頭
headers = {
    "Content-Type": "application/json"
}

try:
    # 發送 HTTP POST 請求
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    
    # 解析並列印 JSON 回應
    data = response.json()
    if data.get("status") == "0":
        print("轉換報告成功:", data.get("status_details"))
    else:
        print(f"報告失敗，status: {data.get('status')}, details: {data.get('status_details')}")

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

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

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

// 請求負載 (Payload)
const data = {
    key: 'API_KEY',                             // 替換為您的 API Key
    secret: 'API_SECRET',                       // 替換為您的 API Secret
    messageid: '015bd4-d6dfa7-58w',             // 來自簡訊 API 的 Message ID
    conversionTime: '2022-02-22T01:00:01.000Z', // 選填：ISO8601 格式的 UTC 時間
    conversion: 1                               // 1 表示成功，0 表示失敗
};

// 發送 HTTP POST 請求
axios.post(url, data, {
    headers: {
        'Content-Type': 'application/json'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === '0') {
        console.log('轉換報告成功:', result.status_details);
    } else {
        console.log('報告失敗，status:', result.status, 'details:', result.status_details);
    }
})
.catch((error) => {
    console.error('請求失敗:', error.message || error);
});

<?php

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

// 請求負載 (Payload)
$data = [
    "key" => "API_KEY",                             // 替換為您的 API Key
    "secret" => "API_SECRET",                       // 替換為您的 API Secret
    "messageid" => "015bd4-d6dfa7-58w",             // 來自簡訊 API 的 Message ID
    "conversionTime" => "2022-02-22T01:00:01.000Z", // 選填：ISO8601 格式的 UTC 時間
    "conversion" => 1                               // 1 表示成功，0 表示失敗
];

$jsonData = json_encode($data);

// 初始化 cURL 會話
$ch = curl_init($url);

// 設定 cURL 選項（POST 和 application/json）
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Content-Length: " . strlen($jsonData)
]);

// 執行請求
$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 "轉換報告成功: " . $result['status_details'] . "\n";
    } else {
        echo "報告失敗，status: " . $result['status'] . ", details: " . $result['status_details'] . "\n";
    }
}

// 關閉 cURL 會話
curl_close($ch);
?>

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

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

        // JSON 負載
        String jsonPayload = "{"
                + "\"key\": \"API_KEY\","
                + "\"secret\": \"API_SECRET\","
                + "\"messageid\": \"015bd4-d6dfa7-58w\","
                + "\"conversionTime\": \"2022-02-22T01:00:01.000Z\","
                + "\"conversion\": 1"
                + "}";

        // 建立 RequestBody
        MediaType JSON = MediaType.parse("application/json; charset=utf-8");
        RequestBody body = RequestBody.create(JSON, jsonPayload);

        // 建構請求
        Request request = new Request.Builder()
                .url("https://api.paasoo.com.tw/conversion")
                .post(body)
                .addHeader("Content-Type", "application/json")
                .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 (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

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

    // 準備 JSON 負載
    payload := map[string]interface{}{
        "key":            "API_KEY",                    // 替換為您的 API Key
        "secret":         "API_SECRET",                 // 替換為您的 API Secret
        "messageid":      "015bd4-d6dfa7-58w",          // 來自簡訊 API 的 Message ID
        "conversionTime": "2022-02-22T01:00:01.000Z",   // 選填：ISO8601 格式的 UTC 時間
        "conversion":     1,                            // 1 表示成功，0 表示失敗
    }

    jsonData, err := json.Marshal(payload)
    if err != nil {
        fmt.Println("編碼 JSON 出錯:", err)
        return
    }

    // 發送 HTTP POST 請求
    req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("建立請求出錯:", err)
        return
    }
    req.Header.Add("Content-Type", "application/json")

    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
    }

    // 檢查狀態
    if status, ok := result["status"].(string); ok && status == "0" {
        fmt.Println("轉換報告成功:", result["status_details"])
    } else {
        fmt.Printf("報告失敗，status: %v, details: %v\n", result["status"], result["status_details"])
    }
}

注意：以上程式碼參數均為範例，需替換為您真實的參數值。

只要支援 HTTP/HTTPS 並能發送 JSON 格式請求的語言或框架都可輕鬆對接該 API。按照相同的請求方式（POST + Content-Type: application/json）提交相應參數即可。

8. 最佳實踐及注意事項

安全管理：
- 切勿在用戶端（例如前端瀏覽器、行動 App 的前端邏輯）暴露 API Key 和 API Secret；請在後端伺服器呼叫。
資料有效性：
- 確保 messageid 與簡訊發送時所返回的 ID 一致，以便準確建立轉換關聯。
時間格式：
- 盡量使用 ISO8601 標準時間格式，並保證是 UTC+0 時區。
準確及時：
- 若您的系統只能在用戶成功或失敗後某段時間上報，可記錄本地時間並傳入 conversionTime。報告越及時，對簡訊品質分析幫助越大。
批次更新：
- 若在高併發環境下需要上報海量轉換資訊，請合理規劃介面呼叫頻率，並與 PaaSoo 協商是否需要額外頻寬或更高併發能力。

9. 常見問題（FAQ）

假如無法取得用戶操作的準確時間怎麼辦？

您可以選擇不傳遞 conversionTime 欄位，系統將以請求到達時間作為轉換時間。

如果我一次性有大量轉換記錄需要彙報，會不會導致超時？

建議分批次調度，確保網路與伺服器穩定性。如需大規模併發支援，可聯絡 PaaSoo 以協商解決方案。

上報轉換後，PaaSoo 會如何處理這些資料？

PaaSoo 將對這些資料進行聚合和分析，幫助您最佳化簡訊通訊通道和成本，也可將其納入統計報表。

conversion 可否包含更多狀態？

目前僅區分成功（1）與失敗（0）。如有更細化需求，可與 PaaSoo 支援團隊溝通。

如何與簡訊 API 中的 messageid 做關聯？

messageid 與簡訊 API 返回的 ID 一致，即可完成一一對應的關聯。請在發送簡訊時妥善保留回應中的 messageid。

技術支援

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

1. 呼叫方式​

2. 使用場景及重要性​

3. 請求範例​

4. 請求參數說明​

5. 回應參數說明​

5.1 成功範例​

5.2 失敗範例​

6. 常見錯誤與排查​

7. 程式碼範例​

8. 最佳實踐及注意事項​

9. 常見問題（FAQ）​