批量發送成功率查詢 API

在使用 PaaSoo 平台進行大批次簡訊或行銷活動時，您可能需要在事後查詢整批發送的統計資料，例如：提交總量、計費訊息數、實際送達數、被拒絕數等。透過此介面，您可以在批次級別進行資料檢索，掌握整體的發送效果和成功率，以便進一步統計或分析。

1. 呼叫說明

呼叫方式

HTTP Method：GET
請求地址：https://api.paasoo.com.tw/batchReport
使用場景：當您透過批次發送介面觸發了一次批次簡訊後，可使用該介面來取得該批次的統計報告；報告包含送達率、營運商退回等資訊。

2. 請求範例

GET https://api.paasoo.com.tw/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，用於唯一標識一批簡訊發送任務。	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	該批次提交的簡訊總數（排隊等待發送的總數量）。	10000
charged	integer	計費訊息數，代表此次批次發送最終計費所依據的總分拆數。	10000
pending	integer	當前仍未發送或等待處理的簡訊數量。	0
rejected	integer	在平台側或營運商側被拒絕的簡訊數量（發送請求被明確拒絕）。	0
deliveryRate	string	送達率，通常由 (`delivered` + `accepted`) / `submitted` 計算，再以百分比形式顯示。	100%
delivered	integer	營運商返回「已送達」狀態的簡訊總數。	10000
accepted	integer	營運商接收但尚未或無法確認最終送達的條數。	0
failed	integer	營運商返回「發送失敗」的簡訊總數。	0
unreachable	integer	營運商返回「無法送達」的簡訊總數（可能包括關機、停機、無信號等）。	0
expired	integer	營運商返回「超時」導致無法送達的簡訊總數。	0
deleted	integer	營運商返回「已刪除」的簡訊總數（通常指在營運商儲存有效期內未發送成功）。	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，用於後續統計和對帳。
- 若需要更細顆粒度的報告（逐條簡訊狀態），可搭配單條 DLR 查詢或 DLR 回呼機制使用。
補償查詢：
- 某些營運商會有一定的狀態回饋延遲，如果查詢結果與預期不符，建議稍後再次查詢。
- 可根據業務需要設定合理的輪詢間隔和次數，避免過度頻繁呼叫。
資料準確性：
- 由於報告依賴於營運商回執，不同地區的營運商在時效性和準確率方面會有差異。
- 若發現資料有明顯異常或無法匹配業務實際情況，可聯絡 PaaSoo 技術支援做進一步排查。

6. 總結

批量發送成功率查詢 API 可讓您在短時間內對大規模簡訊的發送成功率、失敗數、計費訊息數等進行統計與分析。結合 PaaSoo 其他查詢和回呼功能，您能更全面地掌握簡訊發送全流程的狀態資訊，提高對大規模活動或宣傳的追蹤與管理效率。

技術支援

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

1. 呼叫說明​

2. 請求範例​

3. 請求參數說明​

4. 回應範例​

4.1 回應參數說明​

4.2 成功回應範例​

4.3 失敗回應範例​

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

6. 總結​