コンバージョン追跡 API

コンバージョン追跡 API（Conversion Tracking API）は、企業がユーザー側での OTP（One‑Time Password、ワンタイムパスワード）SMS の実際のコンバージョン状況を正確に測定するのを支援するために使用されます。国際 SMS の配信受領確認は、キャリアや地域の規制など複数の要因に影響されることが多く、正確性を確保するのが困難なため、企業はこの API を通じてユーザーがコンバージョン（例：ログインや認証の成功）を完了したかどうかをリアルタイムでフィードバックできます。これにより、PaaSoo はお客様が SMS の品質を追跡し、通信チャネルを最適化し、ユーザーエクスペリエンスを向上させるためのサポートをより適切に行うことができます。

1. 呼び出し方法

呼び出し方法

HTTP Method：POST
Content-Type：application/json
リクエスト URL：https://api.paasoo.com/conversion

2. 利用シナリオと重要性

ユーザーに OTP SMS を送信した後、国際 SMS の受領確認情報は遅延したり不正確だったりすることがよくあります。企業はこの API を通じて、ユーザーのその後の認証の実際の結果（例：ユーザーが指定された時間内に正しい認証コードを入力したことは、SMS が実際にコンバージョンに成功したことを示します）を積極的に PaaSoo に通知できます。これにより以下のことが可能になります：

品質管理の補助：ユーザーの実際の認証アクションと組み合わせることで、さまざまな国/地域、キャリア、またはルートの実際のパフォーマンスを判断するのに役立ちます。
コストの最適化：コンバージョン率の低いルートを発見し、タイムリーに調整することで、全体的なコストを削減します。
ウィンウィン（相互利益）の協力：PaaSoo は、実際のコンバージョン効果に基づいて、SMS の送信品質とユーザーエクスペリエンスを継続的に最適化できます。

3. リクエストのサンプル

cURL
curl -X POST "https://api.paasoo.com/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。各 SMS レコードの一意の識別子。企業は SMS 送信 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/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.com/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.com/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.com/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/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. ベストプラクティスと注意事項

セキュリティ管理：
- クライアント側（例：フロントエンドブラウザ、モバイルアプリのフロントエンドロジック）で API Key と API Secret を絶対に露出させないでください。バックエンドサーバーで呼び出してください。
データの有効性：
- messageid が SMS 送信時に返された ID と一致していることを確認し、コンバージョンの関連付けを正確に確立してください。
時間形式：
- できるだけ ISO8601 標準時間形式を使用し、UTC+0 タイムゾーンであることを保証してください。
正確性と適時性：
- システムがユーザーの成功または失敗から一定時間後にのみ報告できる場合は、ローカル時間を記録して conversionTime に渡すことができます。報告がタイムリーであるほど、SMS 品質分析に役立ちます。
バッチ更新：
- 高同時実行環境で大量のコンバージョン情報を報告する必要がある場合は、API 呼び出しの頻度を合理的に計画し、追加の帯域幅やより高い同時実行機能が必要かどうかを PaaSoo と協議してください。

9. よくある質問（FAQ）

ユーザーの操作の正確な時間を取得できない場合はどうすればよいですか？

conversionTime フィールドを渡さないことを選択できます。システムはリクエストの到達時間をコンバージョン時間として使用します。

一度に大量のコンバージョン記録を報告する必要がある場合、タイムアウトになりませんか？

ネットワークとサーバーの安定性を確保するために、バッチでスケジュールすることをお勧めします。大規模な同時実行のサポートが必要な場合は、解決策について PaaSoo にお問い合わせください。

コンバージョンを報告した後、PaaSoo はこれらのデータをどのように処理しますか？

PaaSoo はこれらのデータを集約および分析し、SMS 通信ルートとコストの最適化を支援します。また、統計レポートに含めることもあります。

conversion に他のステータスを含めることはできますか？

現在は成功（1）と失敗（0）のみを区別しています。より詳細な要件がある場合は、PaaSoo サポートチームにご相談ください。

SMS 送信 API の messageid とどのように関連付けますか？

messageid が SMS 送信 API から返された ID と一致すれば、1 対 1 の関連付けが完了します。SMS 送信時にレスポンス内の messageid を適切に保存してください。

テクニカルサポート

API 連携の過程で技術的な問題やビジネスに関する疑問が生じた場合は、いつでも当社の開発者サポートチーム（support@paasoo.com）までご連絡ください。誠心誠意、技術的なサポートを提供いたします。

1. 呼び出し方法​

2. 利用シナリオと重要性​

3. リクエストのサンプル​

4. リクエストパラメータの説明​

5. レスポンスパラメータの説明​

5.1 成功のサンプル​

5.2 失敗のサンプル​

6. よくあるエラーとトラブルシューティング​

7. コードサンプル​

8. ベストプラクティスと注意事項​

9. よくある質問（FAQ）​