バッチステータス API

PaaSoo プラットフォームを使用して大規模なSMS送信やマーケティングキャンペーンを行う際、事後にバッチ全体の送信統計データ（提出件数 (Submitted)、課金メッセージ数、実際の配信 (Delivered) 数、拒否 (Rejected) 数など）を照会する必要がある場合があります。このインターフェースを通じて、バッチレベルでデータを検索し、全体的な送信効果と配信率を把握して、さらなる統計や分析に役立てることができます。

1. 呼び出しについて

呼び出し方法

HTTP Method：GET
リクエスト先：https://api.paasoo.com/batchReport
使用シナリオ：バッチ SMS API を通じてバッチSMS送信をトリガーした後、このインターフェースを使用して該当バッチの統計レポートを取得できます。レポートには、配信率や通信事業者からの返送などの情報が含まれます。

2. リクエスト例

GET https://api.paasoo.com/batchReport?key=API_KEY&secret=API_SECRET&batchId=Batch_ID

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

パラメータ	タイプ	必須	説明	例
key	string	はい	API Key（英数字8桁）。アカウントの一意の識別子として使用します。PaaSoo のクライアントバックグラウンドで取得できます。	Abcdefgh
secret	string	はい	API Secret（英数字8桁）。`key` と組み合わせて認証に使用します。PaaSoo のクライアントバックグラウンドで取得できます。	Abc123EF
batchId	string	はい	照会するバッチID。バッチSMS送信タスクを一意に識別するために使用します。	a0018f-e4bf51-e000

4. レスポンス例

以下の例は、照会成功時と失敗時の一般的なレスポンス結果を示しています。

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

パラメータ	タイプ	サービス	説明
code	integer	リクエストに対する PaaSoo クラウド通信プラットフォームのレスポンスステータスコード： 0 - success: 成功 2 - Missing parameters: 必須パラメータの欠落 3 - Invalid parameters: パラメータの形式エラー 4 - Invalid credentials: Key または Secret の誤り	0
batchId	string	バッチID。	a0018f-e4bf51-e000
descr	string	`code` に対応するテキスト説明。	Missing parameters
submitted	integer	提出件数 (Submitted)。該当バッチで提出されたSMSの総数（送信待ちキューにある総数）。	10000
charged	integer	課金メッセージ数。今回のバッチ送信で最終的に課金される分割数の合計を表します。	10000
pending	integer	送信待ち (Pending)。現在未送信または処理待ちのSMSの数。	0
rejected	integer	拒否 (Rejected)。プラットフォーム側または通信事業者側で拒否されたSMSの数（送信リクエストが明確に拒否された場合）。	0
deliveryRate	string	配信率。通常は (`delivered` + `accepted`) / `submitted` で計算され、パーセンテージで表示されます。	100%
delivered	integer	配信 (Delivered)。通信事業者が「配信」ステータスを返したSMSの総数。	10000
accepted	integer	受信 (Accepted)。通信事業者が受信したが、最終的な配信をまだ確認していない、または確認できない件数。	0
failed	integer	失敗 (Failed)。通信事業者が「送信失敗」を返したSMSの総数。	0
unreachable	integer	到達不能 (Unreachable)。通信事業者が「到達不能」を返したSMSの総数（電源オフ、利用停止、圏外などが含まれる場合があります）。	0
expired	integer	タイムアウト (Expired)。通信事業者から「タイムアウト」が返され、配信できなかったSMSの総数。	0
deleted	integer	削除済み (Deleted)。通信事業者が「削除済み」を返したSMSの総数（通常、通信事業者の保存有効期間内に送信が成功しなかったことを指します）。	0
usage	string	総消費金額。	100

4.2 成功レスポンス例

{
    "submitted": 10000,
    "charged": 10000,
    "pending": 0,
    "rejected": 0,
    "deliveryRate": "100%",
    "delivered": 10000,
    "accepted": 0,
    "failed": 0,
    "unreachable": 0,
    "expired": 0,
    "deleted": 0
}

4.3 失敗レスポンス例

{
    "code": 2,
    "descr": "Missing parameters."
}

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

インターフェースのセキュリティ：
- key と secret を通じて認証を行います。安全な環境で適切に保管してください。
- 機密情報が送信中に盗まれるのを防ぐため、インターフェースの呼び出しには HTTPS を使用することを推奨します。
送信戦略と照合：
- バッチ送信時に一意の batchId を生成し、後続の統計や照合に使用することができます。
- より詳細なレポート（メッセージごとのステータス）が必要な場合は、単一のメッセージステータス API や配信コールバックメカニズムと組み合わせて使用できます。
補償照会：
- 一部の通信事業者ではステータスのフィードバックに一定の遅延が生じる場合があります。照会結果が予想と異なる場合は、少し時間をおいてから再度照会することをお勧めします。
- 過度に頻繁な呼び出しを避けるため、業務ニーズに応じて合理的なポーリング間隔と回数を設定してください。
データの正確性：
- レポートは通信事業者の受領確認に依存するため、地域や通信事業者によって適時性や正確率に違いが生じる場合があります。
- データに明らかな異常がある場合や、業務の実態と一致しない場合は、PaaSoo テクニカルサポートにご連絡いただき、詳細な調査をご依頼ください。

6. まとめ

バッチステータス API を使用すると、大規模な SMS の配信率、失敗数、課金メッセージ数などを短時間で統計および分析できます。 PaaSoo の他の照会やコールバック機能と組み合わせることで、SMS 送信プロセス全体のステータス情報をより包括的に把握し、大規模なキャンペーンやプロモーションの追跡と管理の効率を向上させることができます。

テクニカルサポート

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

1. 呼び出しについて​

2. リクエスト例​

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

4. レスポンス例​

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

4.2 成功レスポンス例​

4.3 失敗レスポンス例​

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

6. まとめ​