批量发送成功率查询 API

在使用 PaaSoo 平台进行大批量短信或营销活动时，您可能需要在事后查询整批发送的统计数据，例如：提交总量、计费条数、实际送达数、被拒绝数等。通过此接口，您可以在批次级别进行数据检索，掌握整体的发送效果和成功率，以便进一步统计或分析。

1. 调用说明

调用方式

HTTP Method：GET
请求地址：https://api.paasoo.cn/batchReport
使用场景：当您通过批量发送接口触发了一次批次短信后，可使用该接口来获取该批次的统计报告；报告包含送达率、运营商退回等信息。

2. 请求示例

GET https://api.paasoo.cn/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. 小结​