狀態報告查詢 API

除了透過回呼機制（Callback）取得簡訊的投遞狀態報告（DLR），PaaSoo 平台同時支援同步查詢的方式，便於您在需要時呼叫介面來檢查特定訊息的投遞結果。該查詢介面在您希望主動輪詢或手動觸發查詢的時候特別有用，無需依賴被動回呼。

1. 呼叫說明

呼叫方式

HTTP Method：GET
請求地址：https://api.paasoo.com.tw/dlr
使用場景：當您需要基於簡訊 ID 手動取得或定時審核簡訊發送狀態時，可呼叫此介面。在部分國家或地區，營運商的 DLR 可靠性有限，因此可透過此查詢進一步確認發送狀態。

2. 請求範例

GET https://api.paasoo.com.tw/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，用於唯一標識一則簡訊發送請求。	015bd4-d6dfa7-58w

4. 回應範例

當查詢成功時，您將收到詳細的狀態報告資料；若查詢失敗，則會返回錯誤碼及相應提示。

4.1 回應參數說明

4.1.1 成功參數說明

返回陣列列表，陣列項說明

參數	類型	描述	範例
price	number	單條簡訊計費價格（單位：USD 或由帳戶計費貨幣決定）。	0.03
network	string	發送號碼的營運商網路，如 MCC+MNC 組合。	23420
status	string	發送狀態。 1 - 發送中 0 - 提交供應商成功 400 - 提交供應商失敗	1 - 發送中
to	string	發送目標號碼，格式為`國際電話代碼 + 手機號碼`（不含前導 00 或 +）。	886912345678
drTime	string	報告時間(UTC+0)，格式（yyyy-MM-dd HH:mm:ss.ZZZ）	2025-08-12 09:01:17.676
drStatus	integer	狀態報告值： 0 - 正常狀態 400 - 異常狀態	0
type	string	結果資料類型，狀態報告查詢返回 dlr。	dlr
messageid	string	被查詢的簡訊 ID，用以唯一標識一則簡訊請求。	015bd4-d6dfa7-58w
counts	integer	計費訊息數（根據簡訊長度或拆分等因素可能會超過 1 條）。	1
drStatuscode	string	詳細狀態報告代碼： delivered - 簡訊送達，對應 drStatus=0 accepted - 營運商接收，對應 drStatus=0 rejected - 營運商拒絕，對應 drStatus=400 failed - 發送失敗，對應 drStatus=400 expired - 營運商超時，對應 drStatus=400 deleted - 被營運商刪除，對應 drStatus=400 unknown - 未知錯誤，對應 drStatus=400	delivered
drErrcode	string	營運商返回的錯誤碼，與 drStatuscode 相對應： 0 - 正常 1 - 未知錯誤 2 - 訊息無法送達（停機、關機、無信號等） 3 - 號碼已停用或無效 4 - 用戶拒收簡訊 5 - 被營運商拒絕 6 - 營運商超時 7 - 被營運商刪除 8 - 用戶免打擾（DND） 10 - 標題/ Sender ID 無效 11 - 模板無效 12 - Entity ID 不匹配 99 - 其他營運商錯誤	0 - 正常

4.1.2 失敗參數說明

參數	類型	描述	範例
code	integer	狀態碼。 2 - Missing parameters：缺少必要參數 3 - Invalid parameters：參數格式錯誤 4 - Invalid credentials：Key或Secret錯誤 5 - Unauthorized IP：IP限制 9 - Quota exceeded：欠費或信用額度不足 11 - System error：系統錯誤 20 - Dlr search not support：報告查詢不支援	2
descr	string	狀態碼描述。	Invalid credentials

4.2 成功回應範例

[
    {
        "type": "dlr",
        "messageid": "00041d-23fefc-c000",
        "to": "919340275066",
        "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，您可以隨時主動取得指定簡訊的發送狀態。結合 DLR 回呼與手動查詢兩種方式，能夠有效提升對簡訊發送鏈路的監控與管理能力。

技術支援

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

1. 呼叫說明​

2. 請求範例​

3. 請求參數說明​

4. 回應範例​

4.1 回應參數說明​

4.1.1 成功參數說明​

4.1.2 失敗參數說明​

4.2 成功回應範例​

4.3 失敗回應範例​

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

6. 總結​