メッセージステータス API
コールバック（Callback）メカニズムを通じて SMS の配信ステータスレポート（DLR）を取得することに加えて、PaaSoo プラットフォームは同期的な照会もサポートしています。これにより、必要なときにインターフェースを呼び出して、特定のメッセージの配信結果を確認できます。この照会インターフェースは、受動的なコールバックに依存することなく、能動的にポーリングを行ったり、手動で照会をトリガーしたりしたい場合に特に役立ちます。
1. 呼び出しについて
呼び出し方法
- HTTP Method：
GET - リクエスト先：
https://api.paasoo.com/dlr - 使用シナリオ：メッセージIDに基づいて、手動で、または定期的に SMS の送信ステータスを取得および確認する必要がある場合に、このインターフェースを呼び出すことができます。一部の国や地域では、通信事業者の DLR の信頼性が限られているため、この照会を通じて送信ステータスをさらに確認することができます。
2. リクエスト例
GET https://api.paasoo.com/dlr?key=API_KEY&secret=API_SECRET&messageid=MESSAGE_ID
3. リクエストパラメータの説明
| パラメータ | タイプ | 必須 | 説明 | 例 |
|---|---|---|---|---|
| key | string | はい | API Key（英数字8桁）。アカウントの一意の識別子として使用します。PaaSoo のクライアントバックグラウンドで取得できます。 | Abcdefgh |
| secret | string | はい | API Secret（英数字8桁）。key と組み合わせて認証に使用します。PaaSoo のクライアントバックグラウンドで取得できます。 | Abc123EF |
| messageid | string | はい | 照会するメッセージID。SMS 送信リクエストを一意に識別するために使用します。 | 015bd4-d6dfa7-58w |
4. レスポンス例
照会が成功すると、詳細なステータスレポートデータを受信します。照会に失敗した場合は、エラーコードと対応するメッセージが返されます。
4.1 レスポンスパラメータの説明
4.1.1 成功パラメータの説明
配列リストが返されます。配列項目の説明：
| パラメータ | タイプ | 説明 | 例 |
|---|---|---|---|
| price | number | 1件あたりの課金料金（単位：USD またはアカウントの請求通貨によって決定されます）。 | 0.03 |
| network | string | 送信先番号の通信事業者ネットワーク（MCC+MNC の組み合わせなど）。 | 23420 |
| status | string | 送信ステータス。
| 1 - 送信中 |
| to | string | 宛先番号。形式は 国番号 + 携帯電話番号 です（先頭の 00 や + は含みません）。 | 819012345678 |
| drTime | string | レポート時間 (UTC+0)。形式は（yyyy-MM-dd HH:mm:ss.ZZZ） | 2025-08-12 09:01:17.676 |
| drStatus | integer | ステータスレポート値：
| 0 |
| type | string | 結果のデータタイプ。ステータス照会の場合は dlr を返します。 | dlr |
| messageid | string | 照会対象のメッセージID。SMS リクエストを一意に識別するために使用します。 | 015bd4-d6dfa7-58w |
| counts | integer | 課金メッセージ数（SMS の長さや分割などの要因により 1 件を超える場合があります）。 | 1 |
| drStatuscode | string | 詳細なステータスレポートコード：
| delivered |
| drErrcode | string | 通信事業者が返すエラーコード。drStatuscode に対応します：
| 0 - 正常 |
4.1.2 失敗パラメータの説明
| パラメータ | タイプ | 説明 | 例 |
|---|---|---|---|
| code | integer | ステータスコード。
| 2 |
| descr | string | ステータスコードの説明。 | Invalid credentials |
4.2 成功レスポンス例
[
{
"type": "dlr",
"messageid": "00041d-23fefc-c000",
"to": "819012345678",
"status": 0,
"drStatus": 400,
"drStatuscode": "failed",
"drErrcode": "5",
"price": 0.001,
"counts": 1,
"drTime": "2025-12-16 15:51:20.055",
"network": "405840"
}
]
4.3 失敗レスポンス例
{
"code": 2,
"descr": "Missing parameters"
}
5. ベストプラクティスと注意事項
- 署名とセキュリティ：
keyとsecretを通じて認証を行います。漏洩を防ぐため、適切に保管してください。- 機密情報が送信中に盗まれるのを防ぐため、インターフェースの呼び出しには HTTPS を使用することを推奨します。
- ポーリング戦略：
- DLR コールバックメカニズムを既に設定している場合は、コールバックが失敗したとき、またはメッセージのステータスが長期間更新されないときにのみ、この照会インターフェースを使用することができます。
- サーバーへの過度な負荷を避けるため、合理的な照会頻度を設定する必要があります。
- データの解析：
statusに基づいて照会リクエストが成功したかどうかを判断します。0は照会が成功し、drStatusなどの詳細フィールドを取得できることを示します。drStatus/drStatuscodeの解釈は DLR コールバックと同じです。フロントエンドまたはシステムのロジックと組み合わせて、照合とステータスのマッピングを行ってください。
- 互換性：
- DLR コールバックと同様に、特定の国や地域の通信事業者は、正確またはリアルタイムなステータスレポートを提供できない場合があります。
- 照会結果が実際の配信状況と一致しない場合は、関連する通信事業者または PaaSoo テクニカルサポートに連絡して、さらに調査を行ってください。
6. まとめ
上記の メッセージステータス API を使用すると、指定した SMS の送信ステータスをいつでも能動的に取得できます。 DLR コールバックと手動照会の両方を組み合わせることで、SMS 送信リンクの監視と管理機能を効果的に向上させることができます。
テクニカルサポート
API 連携の過程で技術的な問題やビジネスに関する疑問が生じた場合は、いつでも当社の開発者サポートチーム（support@paasoo.com）までご連絡ください。誠心誠意、技術的なサポートを提供いたします。