跳至主要内容

狀態報告接收 API

當您使用 PaaSoo 國際簡訊/通訊服務發送簡訊後，您可以透過本回呼機制接收簡訊的投遞狀態報告（即 DLR）。請注意：這些投遞狀態報告（DLR）通常由營運商端返回，因此在不同國家/地區，營運商的上報機制和時效性可能存在差異，在某些區域，報告可能不夠完整或可靠，無法完全反映最終的送達情況。

透過整合此回呼功能，您可以在業務資料庫或前端系統中同步更新簡訊的投遞結果，從而更好地管理、追蹤各條簡訊是否成功送達用戶終端。本文件將向您介紹回呼方式、參數含義以及常見的接收處理範例。

1. 回呼說明​

呼叫方式
  • HTTP Method：GET
  • 回呼位址：在 PaaSoo 平台中預先配置的 USER_CALLBACK_URL (由您提供)。
  • 回呼時機：當目標營運商產生或更新狀態報告時，PaaSoo 會將狀態透過 GET 請求推送到您指定的回呼位址。
  • 重試策略：若您的伺服器未能正確返回 HTTP 200，PaaSoo 會在 5 / 10 / 30 分鐘間隔嘗試重新發送。

2. 回呼範例​

當狀態報告產生後，PaaSoo 平台會以下列 GET 請求形式呼叫您的回呼位址：

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

注意：timestamp 參數中的加號（+）會在 URL 中被編碼為 %3A 或其它跳脫字元，這取決於實際 URL 編碼方式。

3. 參數說明​

參數類型描述範例
typestring回呼訊息類型，DLR 回呼固定為 dlr。dlr
messageidstring發送請求時所返回的簡訊 ID，用於唯一標識一則簡訊請求。015bd4-d6dfa7-58w
tostring簡訊目標號碼，格式為國際電話代碼 + 手機號碼（不含前導 00 或 +）。886912345678
statusinteger狀態值：
  • 0 - 正常狀態
  • 400 - 異常狀態
0
statuscodestring詳細狀態代碼：
  • delivered - 簡訊送達 (對應 status=0)
  • accepted - 營運商接收 (對應 status=0)
  • rejected - 營運商拒絕 (對應 status=400)
  • failed - 發送失敗 (對應 status=400)
  • expired - 營運商超時 (對應 status=400)
  • deleted - 被營運商刪除 (對應 status=400)
  • unknown - 未知錯誤 (對應 status=400)
delivered
errcodestring營運商返回的錯誤碼（如果有），與 statuscode 對應：
  • 0 - 正常
  • 1 - 未知錯誤
  • 2 - 訊息無法送達（停機、關機、無信號等）
  • 3 - 號碼已停用或無效
  • 4 - 用戶拒收簡訊
  • 5 - 被營運商拒絕
  • 6 - 營運商超時
  • 7 - 被營運商刪除
  • 8 - 用戶免打擾（DND）
  • 10 - 無效的 Sender ID
  • 11 - 模板無效
  • 12 - Entity ID 不匹配
  • 99 - 其他營運商錯誤
0 - 正常
networkstring目標號碼的營運商網路，如 MCC+MNC 組合。52099
pricenumber單條簡訊計費價格（單位：USD 或由帳戶計費貨幣決定）。0.03
countsinteger計費訊息數（可能受簡訊長度、GSM7/Unicode 轉換、拆分計費等因素影響）。1
refstring客戶自訂參數，用於將初始請求與 PaaSoo 的回應（透過非同步通知或查詢結果返回）進行關聯。
timestamplong狀態報告產生的時間戳記，單位毫秒。1686045579378

4. 回呼回應與重試​

  • 成功回應：當您接收到回呼並完成處理後，需要返回 HTTP 200 或類似的成功回應，以告知 PaaSoo 回呼已被正確接收。
  • 重試機制：如果 PaaSoo 未接收到有效的成功回應，系統會在 5 分鐘、10 分鐘、30 分鐘間隔分別重試一次。如仍未收到 200 回應，則放棄後續重試。
  • 建議：在實際生產環境中，務必為回呼添加日誌記錄或資料庫插入邏輯，以防止多次重試造成重複資料。可透過 messageid 進行去重操作。

5. 最佳實踐與注意事項​

  1. 安全性：
    • 建議在回呼 URL 中採用 HTTPS 加密，以保障資料傳輸安全。
    • 可透過驗證來源 IP、查詢簽名參數等方式加強安全控制，避免惡意呼叫。
  2. 參數儲存：
    • 務必記錄 messageid、to、statuscode 等核心欄位，以支援後續對帳和日誌分析。
    • 如需對計費、扣費情況進行統計，可記錄 price 和 counts 欄位。
  3. 冪等處理：
    • 若同一條 DLR 回呼多次到達（在重試狀態下可能發生），請使用 messageid 進行冪等性判斷，避免重複入庫與處理。
  4. 相容性：
    • 部分營運商可能不會按時返回最終狀態，或在網路不穩定時延遲回呼。
    • 部分營運商可能不提供完整的 errcode 詳細資訊。
    • 由於狀態報告依賴營運商端，本身的準確性在部分國家或地區可能受限，需額外關注。

6. 總結​

以上便是 PaaSoo 平台推送簡訊狀態報告（Delivery Receipt, DLR）至用戶指定回呼位址的相關說明與實現範例。 由於這類報告在不同國家或地區的可靠性取決於當地營運商的同步機制，您可能需要結合業務場景來評估最終送達情況。 透過搭建 DLR 回呼接收端，您可以在簡訊觸達的全流程中獲得更全面、更即時的監控能力。

技術支援

如在 API 對接過程中遇到任何技術問題或業務疑問，歡迎隨時聯絡我們的開發者支援團隊：support@paasoo.com。我們將竭誠為您提供技術協助。