一括 SMS API

本 API を使用することで、1 回のリクエストで 1～5000 通の国際 SMS を一括送信できます。大規模な通知、プロモーションキャンペーン、リマインダー、および自動化されたメッセージ送信に適しています。PaaSoo は高集中的な送信シナリオに特化して最適化されており、さまざまなビジネスニーズを満たすための柔軟なパラメータ設定オプションを提供しています。

機能および利用シナリオ

大規模な通知：緊急通知、イベントの告知、システムメンテナンスのリマインダーなど、一度に大量のユーザーにリーチする必要がある場合。
マーケティングキャンペーン：クーポン、割引情報、ホリデープロモーションなどを一括送信し、プロモーションのカバレッジを迅速に拡大します。
プラットフォームサービス通知：宅配便の配送状況の更新、会員更新のリマインダー、予約の確認など。
自動化タスク：スケジュールやイベント駆動の方式により、特定のターゲット層へ SMS を一括送信し、効率を向上させます。

この API を通じて、複数の番号を一度にパッケージ化して送信すると同時に、各 SMS の送信ステータスやメッセージ ID を追跡および管理できます。また、後で batchid を使用して照会、統計、または照合を行うことも可能です。一括 SMS の配信結果や成功率を確認する必要がある場合は、詳細について一括送信成功率照会 API をご参照ください。

1. 呼び出し方法

呼び出し方法

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
リクエスト URL： https://api.paasoo.com/batch_json

注意事項

1 回のリクエストでの一括送信数は 1～5000 通の間である必要があります。この範囲を超えると、エラーステータスコードが返されます。
無効な番号や重複した番号による失敗を減らすため、一括送信先の番号の重複排除と有効性チェックを行ってください。
大規模な配信を行う前に、テンプレートとパラメータが正しいことを確認するため、テスト環境または小規模な範囲で事前に検証することをお勧めします。

2. リクエスト形式

以下は POST リクエストの典型的なサンプルです。リクエストボディに URL エンコード（application/x-www-form-urlencoded）形式でパラメータを渡す必要があります：

cURL
curl -X POST "https://api.paasoo.com/batch_json" \ 
-H "Content-Type: application/x-www-form-urlencoded" \ 
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=819011111111,819022222222&text=This+is+test+sms+from+TEST"

上記のサンプルにおいて：

to パラメータは、カンマで区切られた複数の番号を受け付けます（例：819011111111,819022222222）。
text パラメータは URL エンコードされています。This+is+test+sms+from+TEST は実際の SMS 本文を表します。
key と secret は、それぞれ PaaSoo の管理コンソールで取得した認証情報に置き換え、大切に保管してください。

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

以下のパラメータのうち、「インドのみ適用」と記載されているものは、インドの国内番号へ送信する（またはインドの国内通信ゲートウェイを使用する）場合のみ適用されます。その他の国/地域では入力しないでください。送信に失敗する可能性があります。

パラメータ	型	必須	説明	サンプル
key	string	はい	API Key（英数字8桁）。アカウントの一意の識別子として使用します。PaaSoo の管理コンソールで取得できます。	Abcdefgh
secret	string	はい	API Secret（英数字8桁）。`key` と組み合わせて認証に使用します。PaaSoo の管理コンソールで取得できます。	Abc123EF
from	string	はい	SMS 送信元の表示名（Sender ID）。一部の国/地域でのみカスタマイズ可能であり、長さや文字種に制限がある場合があります。特定の Sender ID を使用する必要がある場合は、アカウントマネージャーまたはテクニカルサポート（support@paasoo.com）までご連絡ください。	TEST
to	string	はい	宛先番号。形式は `国番号 + 携帯電話番号` です（先頭の 00 や + は含みません）。 1 ～ 5000 個の携帯電話番号をサポートします。複数の番号は半角カンマ (,) で区切ります。番号のコンプライアンスを検証した上で送信することをお勧めします。	819011111111,819022222222
text	string	はい	SMS の本文（URL エンコード処理を行ってください）。文字列の長さが制限を超えた場合、複数通に分割され、追加料金が発生する可能性があります。	This is test sms from TEST
peid	string	いいえ	インドテンプレートの Principal Entity ID。インドのみ適用。インドの DLT プラットフォームでの登録を完了し、アカウントマネージャーに有効化を申請する必要があります。	1401480220000021629
templateid	string	いいえ	インドテンプレート ID。インドのみ適用。DLT プラットフォーム上のテンプレート名に対応します。登録を完了し、アカウントマネージャーに連絡して有効化する必要があります。	1407160568716357486

注意：

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

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

一括 SMS リクエストが成功すると、バッチレベルのステータス情報と、各番号に対応する送信結果が返されます。後で batchid を使用して照会、統計、または追跡を行うことができます。

パラメータ	型	説明	サンプル
status	integer	バッチ全体の処理結果。0 はリクエストを正常に受信し、処理したことを示します。	0
status_code	string	レスポンスステータス。PaaSoo クラウド通信プラットフォームに送信された際のレスポンスステータスコード。通常、0 は成功を意味します。	Invalid credentials
batchid	string	一括リクエスト ID。リクエストごとに生成されるグローバルに一意の値であり、後続の照会や統計に使用されます。	a0018f-e4bf51-e000
data	array	一括送信番号に対応する送信詳細のリスト。各番号に対する処理結果が含まれます。	[...]

data 配列内の各要素：

パラメータ	型	説明	サンプル
to	string	SMS 送信の宛先番号。	819011111111
messageid	string	メッセージ ID。単一の SMS 送信レコードを区別するために使用されます。	00018f-e4bf51-e002
status	integer	単一の番号の送信ステータスコード。0 は成功を意味します。	0
status_code	string	該当番号のエラー原因または説明。問題の特定に役立ちます。	Missing parameters

以下は一般的な戻り値のサンプルです：

4.1 成功のサンプル

{ 
    "status": 0, 
    "status_code": "success", 
    "batchid": "a0018f-e4bf51-e000", 
    "data": [
        { 
            "status": 0,
            "to": "819011111111",
            "messageid": "00018f-e4bf51-e002"
        },
        {
            "status": 0,
            "to": "819022222222",
            "messageid": "00018f-e4bf51-e003"
        }
    ]
}

4.2 失敗のサンプル

{ "status": 4, "status_code": "Invalid credentials."}

5. 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：システムエラー
14 - Nb of messages per request should be between 1 and 5000
19 - Invalid peid / Invalid templateid

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

6. コードサンプル

以下は、主要なプログラミング言語で「国際一括 SMS 送信 API」を統合するための簡単なサンプルです。

Python
Node.js
PHP
Java
Go

import requests

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

# フォームデータ
payload = {
    "key": "API_KEY",                         # あなたの API Key に置き換えてください
    "secret": "API_SECRET",                   # あなたの API Secret に置き換えてください
    "from": "TEST",                           # 送信元 ID
    "to": "819011111111,819022222222",        # 宛先番号、カンマ区切り
    "text": "これは TEST からのテスト SMS です"   # SMS 本文
}

# リクエストヘッダー
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

try:
    # HTTP POST リクエストを送信
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    
    # JSON レスポンスを解析して出力
    data = response.json()
    if data.get("status") == 0:
        print("一括 SMS の送信に成功しました。batchid:", data.get("batchid"))
    else:
        print(f"一括 SMS の送信に失敗しました。ステータス: {data.get('status')}，メッセージ: {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/batch_json';

// URL エンコードされたフォームデータを準備
const data = new URLSearchParams({
    key: 'API_KEY',                      // あなたの API Key に置き換えてください
    secret: 'API_SECRET',                // あなたの API Secret に置き換えてください
    from: 'TEST',                        // 送信元 ID
    to: '819011111111,819022222222',     // 宛先番号、カンマ区切り
    text: 'これは TEST からのテスト SMS です' // SMS 本文
});

// HTTP POST リクエストを送信
axios.post(url, data.toString(), {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === 0) {
        console.log('一括 SMS の送信に成功しました。batchid:', result.batchid);
    } else {
        console.log('一括 SMS の送信に失敗しました。ステータス:', result.status, 'メッセージ:', result.status_code);
    }
})
.catch((error) => {
    console.error('リクエストに失敗しました:', error.message || error);
});

<?php

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

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

// cURL セッションを初期化
$ch = curl_init($url);

// POST および x-www-form-urlencoded の cURL オプションを設定
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/x-www-form-urlencoded"
]);

// リクエストを実行
$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 "一括 SMS の送信に成功しました。batchid: " . $result['batchid'] . "\n";
    } else {
        echo "一括 SMS の送信に失敗しました。ステータス: " . $result['status'] . "，メッセージ: " . $result['status_code'] . "\n";
    }
}

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

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

// pom.xml または build.gradle に OkHttp の依存関係が追加されていることを確認してください
public class BulkSmsApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // x-www-form-urlencoded リクエストボディを構築
        RequestBody formBody = new FormBody.Builder()
                .add("key", "API_KEY")                          // あなたの API Key に置き換えてください
                .add("secret", "API_SECRET")                    // あなたの API Secret に置き換えてください
                .add("from", "TEST")                            // 送信元 ID
                .add("to", "819011111111,819022222222")         // 宛先番号
                .add("text", "これは TEST からのテスト SMS です")    // SMS 本文
                .build();

        // リクエストを構築
        Request request = new Request.Builder()
                .url("https://api.paasoo.com/batch_json")
                .post(formBody)
                .addHeader("Content-Type", "application/x-www-form-urlencoded")
                .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"
    "strings"
)

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

    // フォームデータを準備
    data := url.Values{}
    data.Set("key", "API_KEY")                          // あなたの API Key に置き換えてください
    data.Set("secret", "API_SECRET")                    // あなたの API Secret に置き換えてください
    data.Set("from", "TEST")                            // 送信元 ID
    data.Set("to", "819011111111,819022222222")         // 宛先番号
    data.Set("text", "これは TEST からのテスト SMS です")    // SMS 本文

    // HTTP POST リクエストを作成
    req, err := http.NewRequest("POST", apiURL, strings.NewReader(data.Encode()))
    if err != nil {
        fmt.Println("リクエスト作成時にエラーが発生しました:", err)
        return
    }
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

    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
    }

    // ステータスを確認（注意：Go では、JSON の数値はデフォルトで float64 として解析されます）
    if status, ok := result["status"].(float64); ok && status == 0 {
        fmt.Println("一括 SMS の送信に成功しました。batchid:", result["batchid"])
    } else {
        fmt.Printf("一括 SMS の送信に失敗しました。ステータス: %v，メッセージ: %v\n", result["status"], result["status_code"])
    }
}

HTTP/HTTPS をサポートする任意の言語やフレームワークで簡単に統合でき、同じ POST メソッドと application/x-www-form-urlencoded を使用してリクエストを行うだけです。

7. ベストプラクティス

番号の検証とクリーニング：一括送信の前に無効な番号や重複した番号を取り除き、無効な番号による無駄やエラーを減らします。
送信頻度制限の遵守：極端に短い時間内に一度に大量の SMS を送信することは避けてください。大規模なニーズがある場合は、本 API を複数回呼び出すことができます。
コンテンツとエンコード：SMS 本文は URL エンコードする必要があります。超長文が複数通に分割される場合は、費用や課金に特に注意してください。
送信ログと監視：バックエンドで batchid を記録し、各 SMS の status と messageid を保存して追跡を容易にします。
再試行と冪等性：ネットワークの変動やその他の異常が発生した場合に備えて再試行メカニズムを設定し、重複送信を避けるために一意のリクエスト ID を使用します。
データのセキュリティとコンプライアンス：ターゲットとなる各国のプライバシーおよび SMS 送信規制を遵守してください。マーケティング系 SMS の場合は、事前にユーザーの同意を得る必要があります。

上記の手順とベストプラクティスを通じて、世界中のユーザーへの一括 SMS 送信を迅速に実現できます。一括 SMS の配信結果や成功率を把握したい場合は、詳細について一括送信成功率照会 API をご確認ください。

テクニカルサポート

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

機能および利用シナリオ​

1. 呼び出し方法​

2. リクエスト形式​

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

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

4.1 成功のサンプル​

4.2 失敗のサンプル​

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

6. コードサンプル​

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