SMS API

PaaSoo の SMS API サービスへようこそ！本 API を使用することで、世界中に向けて単一の SMS メッセージを迅速に送信し、さまざまなビジネスシナリオ（本人確認、マーケティングプロモーション、注文通知など）のニーズを満たすことができます。PaaSoo は、キャリアとの直接接続および長年の経験を通じて、効率的で信頼性の高い SMS 配信を保証するグローバル SMS サービスを提供しています。本ガイドでは、API のスムーズな統合と SMS API サービスの最大限の活用をサポートするため、完全かつ詳細な API の使用手順、パラメータの説明、サンプル、およびベストプラクティスを提供します。

1. API 概要

200 以上の国と地域をカバーする国際 SMS 送信をサポートしており、認証コード、サービス通知、マーケティングなど、多様なシナリオに対応しています（実際のカバレッジはキャリアのゲートウェイに依存します）。本 API を通じて、以下のことが可能です：

世界中の携帯電話ユーザーへの SMS 送信
カスタム送信元（Sender ID）の設定（目的地の国のキャリアポリシーに依存します）
SMS の送信結果、ステータス変更、エラー原因の追跡
アプリケーション、ウェブサイト、またはバックエンドサービスへの柔軟な組み込み

説明

各国のキャリアの規制やネットワークプロトコルの違いにより、一部の国や地域ではカスタム送信元やその他の高度な機能がサポートされていない場合があります。これらのカスタム機能が必要な場合は、アカウントマネージャーにご連絡いただくか、次の宛先までお問い合わせください：support@paasoo.com。

2. 呼び出し方法

呼び出し方法

HTTP Method：GET
リクエスト URL： https://api.paasoo.com/json

本 API を呼び出す前に、管理コンソールで API Key と API Secret を取得していることを確認してください。これらは両方とも、リクエストのクエリパラメータ（Query Params）として含める必要があります。

推奨

データの機密性とセキュリティを確保するため、送信中の盗聴や改ざんを防ぐことができる HTTPS プロトコルを使用して API を呼び出すことを強く推奨します。

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

最もシンプルなサンプルです。必要なパラメータを付与して HTTP GET リクエストを送信します：

https://api.paasoo.com/json?key=API_KEY&secret=API_SECRET&from=TEST&to=819011111111&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	はい	SMS 送信元の表示名（Sender ID）。一部の国/地域でのみカスタマイズ可能であり、長さや文字種に制限がある場合があります。特定の Sender ID を使用する必要がある場合は、アカウントマネージャーまたはテクニカルサポート（support@paasoo.com）までご連絡ください。	TEST
to	string	はい	宛先番号。形式は `国番号 + 携帯電話番号` です（先頭の 00 や + は含みません）。例えば、日本の番号は 819011111111 となります。	819011111111
text	string	はい	SMS の本文。URL エンコード方式で UTF-8 エンコードする必要があります。簡単なテストを行う場合は、サードパーティのツールやバックエンドによる自動エンコードを利用できます。	This is test sms from TEST
requestId	string	いいえ	一意のリクエスト ID。このリクエストを識別し、追跡および異常調査を行うために使用します。冪等性を保証する必要がある場合は、リクエストごとに異なる `requestId` を使用してください。 60秒以内に同じリクエスト ID が使用された場合、同一のリクエストとみなされます。システムは重複して課金や送信を行うことなく、最初のリクエストと同じレスポンス結果を返します。	0432258a-ecc7-4628-9158-2b883fe65181
peid	string	いいえ	インドテンプレートの Principal Entity ID。インドのみ適用。インドで SMS を送信し、このパラメータを使用する場合は、インドの DLT プラットフォームでの登録を完了し、アカウントマネージャーに連絡して有効化する必要があります。	1401480220000021629
templateid	string	いいえ	インドテンプレート ID。インドのみ適用。インドで SMS を送信し、このパラメータを使用する場合は、インドの DLT プラットフォームでの登録を完了し、アカウントマネージャーに連絡して有効化する必要があります。	1407160568716357486
ref	string	いいえ	顧客のカスタムパラメータ。最初のリクエストと PaaSoo のレスポンス（非同期通知または照会結果経由）を関連付けるために使用します。

注意

from の表示は、国やキャリアの環境によって現地のポリシーによる制限を受けます。
text にスペースや特殊文字が含まれる場合は、URL エンコードが必要です。
セキュリティ確保のため、フロントエンドアプリケーションや公開された場所に key と secret を露出させないでください。
大量の SMS を送信する必要がある場合は、本 API を複数回呼び出すことで大規模な送信を実現できます。

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

成功した場合、API はステータスコードと対応するメッセージ ID を返します。
失敗した場合、対応するエラーステータスコードとその説明を返します。

パラメータ	型	説明	サンプル
messageid	string	メッセージ ID。各 SMS レコードの一意の識別子。	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. API ステータスコード一覧

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

本 API はデフォルトで非常に高い送信弾力性を提供します。呼び出し時にエラーコード status=10 を受信した場合、業務の取り決めに従ってアカウントにカスタムレート制限が有効になっていることを示します。制限のしきい値を調整する必要がある場合は、アカウントマネージャーまたは PaaSoo テクニカルサポートチーム（support@paasoo.com）までご連絡ください。

7. コードサンプル

既存のシステムに素早く統合できるように、複数の言語での呼び出しサンプルを提供します：

Python
Node.js
PHP
Java
Go

import requests

# API エンドポイント
url = "https://api.paasoo.com/json"

# クエリパラメータ
params = {
    "key": "API_KEY",                # あなたの API Key に置き換えてください
    "secret": "API_SECRET",          # あなたの API Secret に置き換えてください
    "from": "TEST",                  # 送信元 ID
    "to": "819011111111",            # 宛先番号
    "text": "これは TEST からのテスト SMS です"
}

try:
    # HTTP GET リクエストを送信
    response = requests.get(url, params=params)
    response.raise_for_status()
    
    # JSON レスポンスを解析して出力
    data = response.json()
    if data.get("status") == "0":
        print("SMS の送信に成功しました。messageid:", data.get("messageid"))
    else:
        print(f"SMS の送信に失敗しました。status: {data.get('status')}, message: {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/json';

// クエリパラメータ
const params = {
    key: 'API_KEY',               // あなたの API Key に置き換えてください
    secret: 'API_SECRET',         // あなたの API Secret に置き換えてください
    from: 'TEST',                 // 送信元 ID
    to: '819011111111',           // 宛先番号
    text: 'これは TEST からのテスト SMS です',
};

// HTTP GET リクエストを送信
axios.get(url, { params })
    .then((response) => {
        const data = response.data;
        if (data.status === '0') {
            console.log('SMS の送信に成功しました。messageid:', data.messageid);
        } else {
            console.log('SMS の送信に失敗しました。status:', data.status, 'message:', data.status_code);
        }
    })
    .catch((error) => {
        console.error('リクエストに失敗しました:', error.message || error);
    });

<?php

// API エンドポイント
$url = "https://api.paasoo.com/json";

// クエリパラメータ
$params = [
    "key" => "API_KEY",             // あなたの API Key に置き換えてください
    "secret" => "API_SECRET",       // あなたの API Secret に置き換えてください
    "from" => "TEST",               // 送信元 ID
    "to" => "819011111111",         // 宛先番号
    "text" => "これは TEST からのテスト SMS です"
];

// クエリストリングを構築して 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 "SMS の送信に成功しました。messageid: " . $data['messageid'] . "\n";
    } else {
        echo "SMS の送信に失敗しました。status: " . $data['status'] . ", message: " . $data['status_code'] . "\n";
    }
}

// cURL セッションを閉じる
curl_close($ch);
?>

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/json").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");         // あなたの API Key に置き換えてください
        urlBuilder.addQueryParameter("secret", "API_SECRET");   // あなたの API Secret に置き換えてください
        urlBuilder.addQueryParameter("from", "TEST");           // 送信元 ID
        urlBuilder.addQueryParameter("to", "819011111111");     // 宛先番号
        urlBuilder.addQueryParameter("text", "これは TEST からのテスト SMS です");

        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());
        }
    }
}

package main

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

func main() {
    // ベース URL を解析
    baseURL, err := url.Parse("https://api.paasoo.com/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
    params.Add("to", "819011111111")         // 宛先番号
    params.Add("text", "これは TEST からのテスト SMS です")

    // パラメータをエンコードして 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("SMS の送信に成功しました。messageid:", result["messageid"])
    } else {
        fmt.Printf("SMS の送信に失敗しました。status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

本 API は HTTP リクエストのみに依存しているため、HTTP/HTTPS をサポートする任意の言語やフレームワークに基づいて実装することができます。同じクエリパラメータの構築方法に従うだけです。

8. 送信レポートとステータスコールバック

特定のシナリオでは、SMS の最終的な配信ステータスやバウンスの理由（番号の到達不能、ユーザーの利用停止など）を取得する必要がある場合があります。管理コンソールで送信ステータスを確認できるほか、以下の方法でも取得可能です：

メッセージステータス API を呼び出して、SMS のリアルタイムの配信結果を取得する
コールバック URL（Webhook）を設定し、非同期で配信コールバック URL API 経由で SMS の配信成功または失敗レポートを取得する

これらの方法の設定と使用に関する詳細は、対応するドキュメントを参照してください。

9. ベストプラクティス

パラメータのセキュリティ：バックエンドで API Key と API Secret を安全に保存および使用し、フロントエンドには絶対に露出させないでください。
リクエストのレート制限：PaaSoo プラットフォームでは、お客様のビジネスの急速な成長をサポートするため、デフォルトでは一律の同時リクエスト制限を設けていません。ただし、特定のシナリオにおいて、アカウントのセキュリティを確保するため、または契約の取り決めに従って、カスタマイズされた QPS（1秒あたりのリクエスト数）制限を設定することができます。トラフィックの爆発的な増加が見込まれる場合は、十分なゲートウェイリソースを確保するため、事前にアカウントマネージャーにお知らせください。
コンテンツのコンプライアンス：現地の法規制を遵守し、機密性の高い、違法、または不適切なコンテンツを送信しないでください。アカウントの停止を避けるためです。
エンコードと長さの制御：ラテン文字以外の文字を使用する場合、SMS 本文は Unicode で送信される可能性が高く、長さの上限が短くなります。GSM 7-bit と Unicode エンコードの違いをご参照ください。
テスト環境：本番環境への正式なデプロイ前に、テスト番号またはサンドボックス環境で十分にテストを行い、統合が正しく行われていることを確認することをお勧めします。
監視とログ：ログレベルと監視アラートのメカニズムを確立し、送信量と成功率をタイムリーに監視します。
冪等性の設計：同一の SMS が 1 回のみ送信されることを保証するには、リクエストごとに一意の requestId を生成し、サーバー側で重複排除処理を実装してください。

10. よくある質問（FAQ）

Sender ID が反映されないのはなぜですか？

考えられる原因としては、該当国で指定されている Sender ID の制限、ローカルオペレーターによる事前登録の要求、またはキャリアのポリシー制限などが挙げられます。カスタマイズされた Sender ID が必要な場合は、アカウントマネージャーに詳細をお問い合わせください。

日本語、中国語、または絵文字を含むコンテンツを送信できますか？

はい、可能です。ただし、UTF-8 を使用してエンコードし、さらに URL エンコードを行っていることを確認してください。非 GSM 文字はより多くの文字スペースを消費し、SMS の分割や長さ制限の超過を引き起こす可能性があります。

"status = 9 / Quota exceeded" が表示されるのはなぜですか？

アカウントの残高が不足しているか、クレジット制限を使い切ったことを示しています。速やかにチャージを行うか、営業担当者に連絡して限度額を増やしてください。

SMS の最終的な配信または失敗の理由を取得するにはどうすればよいですか？

管理コンソールで直接送信レポートを照会することができます。また、メッセージステータス API を呼び出すか、コールバック URL（Webhook）によるステータスレポート受信を有効にして、最終的なステータス更新を取得することもできます。

一括で SMS を送信するにはどうすればよいですか？

当社が提供する 一括 SMS API を使用するか、単一の SMS API をバッチ単位で呼び出し、並行処理またはキュー制御を実装することをお勧めします。詳細は、一括 SMS API のドキュメントをご参照ください。

11. 付録

Unicode と GSM 7-bit エンコード：
- GSM 7-bit エンコード：
  - 160 文字以内：1 通として課金。
  - 160 文字を超える場合：153 文字/通として分割課金（連結 SMS 用の識別ヘッダー/UDH として 7 文字を予約）。
- Unicode エンコード：
  - 70 文字以内：1 通として課金。
  - 70 文字を超える場合：67 文字/通として分割課金。
Concatenated SMS（長文 SMS の分割）：
- メッセージの長さが最大文字数制限を超えると、キャリアは SMS を分割して送信します。通常、プラットフォームは分割、並べ替え、結合を自動的に処理しますが、追加の SMS 課金が発生する場合があります。
DLT 登録（インド）：
- インドの電気通信法規制により、マーケティングや企業向け SMS を送信するすべての送信元は、DLT プラットフォームで登録を完了する必要があります。
- インドでローカル SMS を送信し、テンプレート ID や PEID などのパラメータをサポートする必要がある場合は、現地のポリシーを必ず遵守してください。
IP 制限とセキュリティ：
- アカウントに IP ホワイトリストが設定されている場合、API にアクセスする際のリクエスト元 IP がホワイトリストに含まれていることを確認してください。含まれていない場合、status = 5（IP 制限）がトリガーされます。

重要なリマインダー

世界各国のキャリアや異なる配信ゲートウェイの課金ロジックには違いがあるため、上記の長さは参考値です。実際の課金通数は、宛先国のキャリアの精算ルール、および PaaSoo システムの最終的な課金控除記録または請求書のフィードバックに基づきます。
大規模な送信を行う前に、テスト番号を使用して実際の課金状況を確認することをお勧めします。

テクニカルサポート

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

1. API 概要​

2. 呼び出し方法​

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

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

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

5.1 成功レスポンスのサンプル​

5.2 失敗レスポンスのサンプル​

6. API ステータスコード一覧​

7. コードサンプル​

8. 送信レポートとステータスコールバック​

9. ベストプラクティス​

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

11. 付録​