メインコンテンツまでスキップ

配信コールバック URL API

PaaSoo のグローバル SMS / 通信サービスを使用して SMS を送信した後、このコールバックメカニズムを通じて SMS の配信ステータスレポート（DLR）を受信できます。ご注意：これらの配信ステータスレポート（DLR）は通常、通信事業者側から返されるため、国や地域によって通信事業者のレポートメカニズムや適時性に違いがある場合があります。一部の地域では、レポートが不完全であったり信頼性が低かったりして、最終的な配信状況を完全に反映できない場合があります。

このコールバック機能を統合することで、ビジネスデータベースまたはフロントエンドシステムで SMS の配信結果を同期して更新し、各 SMS がユーザーの端末に正常に配信 (Delivered) されたかどうかをより適切に管理および追跡できます。本書では、コールバックの方式、パラメータの意味、および一般的な受信処理の例について説明します。

1. コールバックの説明​

呼び出し方法
  • HTTP Method：GET
  • コールバック URL：PaaSoo プラットフォームで事前に設定された USER_CALLBACK_URL（お客様が提供）。
  • コールバックのタイミング：対象の通信事業者がステータスレポートを作成または更新したとき、PaaSoo は GET リクエストを通じて、指定されたコールバック URL にステータスをプッシュします。
  • 再試行ポリシー：サーバーが HTTP 200 を正しく返せなかった場合、PaaSoo は 5 / 10 / 30 分間隔で再送信を試みます。

2. コールバック例​

ステータスレポートが生成されると、PaaSoo プラットフォームは以下の GET リクエストの形式でお客様のコールバック URL を呼び出します：

https://USER_CALLBACK_URL?type=dlr&messageid=MESSAGE_ID&to=819012345678&status=0&statuscode=delivered&errcode=0&network=52099&price=0.03&counts=1×tamp=1686045579378

注意：timestamp パラメータのプラス記号（+）は、実際の URL エンコード方式に応じて、URL 内で %3A またはその他のエスケープ文字にエンコードされます。

3. パラメータの説明​

パラメータタイプ説明例
typestringコールバックメッセージのタイプ。DLR コールバックの場合は dlr に固定されます。dlr
messageidstring送信リクエスト時に返されたメッセージID。SMS リクエストを一意に識別するために使用されます。015bd4-d6dfa7-58w
tostringSMS の宛先番号。形式は 国番号 + 携帯電話番号 です（先頭の 00 や + は含みません）。819012345678
statusintegerステータス値：
  • 0 - 正常なステータス
  • 400 - 異常なステータス
0
statuscodestring詳細なステータスコード：
  • delivered - 配信 (Delivered) (status=0 に対応)
  • accepted - 受信 (Accepted) (status=0 に対応)
  • rejected - 拒否 (Rejected) (status=400 に対応)
  • failed - 失敗 (Failed) (status=400 に対応)
  • expired - タイムアウト (Expired) (status=400 に対応)
  • deleted - 削除済み (Deleted) (status=400 に対応)
  • unknown - 未知 (Unknown) (status=400 に対応)
delivered
errcodestring通信事業者が返したエラーコード（ある場合）。statuscode に対応します：
  • 0 - 正常
  • 1 - 未知のエラー
  • 2 - メッセージが到達不能 (Unreachable)（利用停止、電源オフ、圏外など）
  • 3 - 番号が利用停止または無効
  • 4 - ユーザーが SMS を拒否
  • 5 - 通信事業者によって拒否 (Rejected) された
  • 6 - タイムアウト (Expired)
  • 7 - 削除済み (Deleted)
  • 8 - ユーザーが DND（Do Not Disturb）に設定
  • 10 - 無効な Sender ID
  • 11 - 無効なテンプレート
  • 12 - Entity ID の不一致
  • 99 - その他の通信事業者エラー
0 - 正常
networkstring宛先番号の通信事業者ネットワーク（MCC+MNC の組み合わせなど）。52099
pricenumber送信メッセージごとの料金（単位：USD またはアカウントの請求通貨によって決定されます）。0.03
countsinteger課金メッセージ数（SMS の長さ、GSM7/Unicode 変換、分割請求などの要因に影響される場合があります）。1
refstring顧客のカスタムパラメータ。初期リクエストと PaaSoo のレスポンス（非同期通知または照会結果を通じて返される）を関連付けるために使用されます。
timestamplongステータスレポートが生成されたタイムスタンプ（ミリ秒単位）。1686045579378

4. コールバックのレスポンスと再試行​

  • 成功レスポンス：コールバックを受信して処理を完了した後、PaaSoo にコールバックが正しく受信されたことを知らせるために、HTTP 200 または同様の成功レスポンスを返す必要があります。
  • 再試行メカニズム：PaaSoo が有効な成功レスポンスを受信しなかった場合、システムは 5 分、10 分、30 分の間隔で 1 回ずつ再試行します。それでも 200 レスポンスを受信できない場合、その後の再試行は放棄されます。
  • 推奨事項：実際の運用環境では、複数回の再試行によるデータの重複を防ぐため、コールバックにログ記録またはデータベースへの挿入ロジックを必ず追加してください。messageid を使用して重複排除を行うことができます。

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

  1. セキュリティ：
    • データ転送のセキュリティを確保するため、コールバック URL には HTTPS 暗号化を使用することをお勧めします。
    • 不正な呼び出しを防ぐため、送信元 IPホワイトリストの検証や署名パラメータの確認などにより、セキュリティ制御を強化することができます。
  2. パラメータの保存：
    • 後続の照合やログ分析をサポートするために、messageid、to、statuscode などのコアフィールドを必ず記録してください。
    • 課金や引き落としの状況を統計する必要がある場合は、price と counts フィールドを記録できます。
  3. 冪等性の処理：
    • 同じ DLR コールバックが複数回到達した場合（再試行状態のときに発生する可能性があります）、重複したデータベース登録や処理を避けるため、messageid を使用して冪等性を判断してください。
  4. 互換性：
    • 一部の通信事業者は、最終的なステータスを時間どおりに返さなかったり、ネットワークが不安定な場合にコールバックを遅延させたりする可能性があります。
    • 一部の通信事業者は、完全な errcode の詳細情報を提供しない場合があります。
    • ステータスレポートは通信事業者側に依存するため、一部の国や地域では正確性が制限される場合があり、特別な注意が必要です。

6. まとめ​

以上が、PaaSoo プラットフォームからユーザーが指定したコールバック URL に SMS の配信ステータスレポート（Delivery Receipt, DLR）をプッシュするための説明と実装例です。 このようなレポートの信頼性は、国や地域によって現地の通信事業者の同期メカニズムに依存するため、ビジネスシナリオと組み合わせて最終的な配信状況を評価する必要があるかもしれません。 DLR コールバックの受信側を構築することで、SMS 配信プロセス全体において、より包括的かつリアルタイムな監視機能を得ることができます。

テクニカルサポート

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