转化追踪 API

转化追踪 API（Conversion Tracking API）用于辅助企业精确衡量 OTP（One‑Time Password，一次性密码）短信在用户侧的实际转化情况。因为国际短信的送达回执常受到运营商和地区监管等多重因素影响，难以确保准确性，企业可通过本 API 实时回传用户是否已完成转换（例如成功登录或验证），以便 PaaSoo 更好地帮助您跟踪短信质量、优化通信渠道及提升用户体验。

1. 调用方式

调用方式

HTTP Method：POST
Content-Type：application/json
请求地址：https://api.paasoo.cn/conversion

2. 使用场景及重要性

当发送 OTP 短信给用户后，国际短信的回执信息常常会出现延迟或不准确。企业可通过此 API 主动将用户后续验证的真实结果告知 PaaSoo（例如用户在指定时间内输入了正确验证码，说明短信确实转化成功），从而：

辅助质量管理：结合用户的真实验证动作，帮助判断不同国家/地区、运营商或链路的实际表现；
成本优化：发现转化率偏低的链路并及时调整，降低整体成本；
合作共赢：PaaSoo 可基于真实转化效果，持续优化短信发送质量与用户体验。

3. 请求示例

cURL
curl -X POST "https://api.paasoo.cn/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.cn/conversion"

# 请求负载 (Payload)
payload = {
    "key": "API_KEY",                             # 替换为您的 API Key
    "secret": "API_SECRET",                       # 替换为您的 API Secret
    "messageid": "015bd4-d6dfa7-58w",             # 来自 SMS 发送 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.cn/conversion';

// 请求负载 (Payload)
const data = {
    key: 'API_KEY',                             // 替换为您的 API Key
    secret: 'API_SECRET',                       // 替换为您的 API Secret
    messageid: '015bd4-d6dfa7-58w',             // 来自 SMS 发送 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.cn/conversion";

// 请求负载 (Payload)
$data = [
    "key" => "API_KEY",                             // 替换为您的 API Key
    "secret" => "API_SECRET",                       // 替换为您的 API Secret
    "messageid" => "015bd4-d6dfa7-58w",             // 来自 SMS 发送 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.cn/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.cn/conversion"

    // 准备 JSON 负载
    payload := map[string]interface{}{
        "key":            "API_KEY",                    // 替换为您的 API Key
        "secret":         "API_SECRET",                 // 替换为您的 API Secret
        "messageid":      "015bd4-d6dfa7-58w",          // 来自 SMS 发送 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）​