文档首页/消息&短信 MSGSMS/API参考/API/发送接收短信API/批量接收状态报告API
更新时间：2026-02-06 GMT+08:00
查看PDF
分享

批量接收状态报告API

功能介绍

该接口用于用户批量接收短信平台主动发送的短信状态报告，批量接收状态报告中的回调地址在控制台的应用管理中设置。

  • 短信发送成功后，平台收到状态报告，会实时推送状态报告给用户，最迟不超过72小时。
  • 平台推送汇聚后的状态报告，状态报告存在一定时延。
  • 短信平台批量推送状态报告，单次最多推送50条。

前提条件

  • 用户对短信平台推送的状态报告免鉴权。
  • 用户服务器若有IP白名单配置，请联系运营经理获取短信平台IP地址并加入白名单。
  • 用户在创建短信应用时配置了批量接收状态报告地址。
  • 用户在调用发送短信API时，不携带statusCallback字段。
    • 若“statusCallback”字段已设置，则优先使用该字段的取值作为短信状态报告的回调地址。
    • 若“statusCallback”字段未设置，则使用应用中配置的批量接收状态报告地址。
    • 若“statusCallback”字段未设置且未在应用端配置批量接收状态报告地址，则用户无法接收短信平台主动发送的状态报告。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

用户在应用中配置的批量接收状态报告地址。

通信协议

HTTPS/HTTP

回调接口使用HTTPS协议时，服务端需支持TLS1.2，加密套件需支持

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256，TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384，TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256，TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384中的一种或多种。

请求参数

表2 请求Headers参数说明

参数名称

是否必选

参数类型

默认值

说明

Content-Type

是

String

无

固定填application/json。

X-Sdk-Date

否

String

无

签名时间戳，开启推送AKSK鉴权后携带。

格式为：yyyyMMdd'T'HHmmss'Z'

Authorization

否

String

无

用于消息鉴权的哈希码，开启推送AKSK鉴权后携带。

格式为：SDK-HMAC-SHA256 Access=app_key的值, SignedHeaders=参与签名的头域（小写）, Signature=经过签名算法计算得到的值

具体计算方式请参考添加签名信息到请求头。

AKSK说明请参考认证鉴权，验证方法请参考推送AKSK验证。

表3 请求Body参数说明

参数名称

是否必选

参数类型

默认值

说明

statusReportList

是

List<SmsStatusBeanOut>

无

状态报告列表。

表4 请求SmsStatusBeanOut参数说明

参数名称

是否必选

参数类型

默认值

说明

smsMsgId

是

String(1-50)

无

发送短信成功时返回的短信唯一标识。

total

否

String(1-2)

无

长短信拆分后的短信条数。

当短信未拆分时该参数取值为1。

sequence

否

String(1-2)

无

长短信拆分后的短信序号，当total参数取值大于1时，该参数才有效。

当短信未拆分时该参数取值为1。

status

是

String(1-7)

无

短信状态报告枚举值，常见取值请参考表 Status常见取值，处理方法请参考状态报告错误码。

source

否

String(枚举)

无

短信状态报告来源：

  • 短信平台自行产生的状态报告。
  • 短信中心返回的状态报告。
  • 华为平台产生的状态报告。

updateTime

否

String(1-20)

无

短信资源的更新时间，通常为短信平台接收短信状态报告的时间，为UTC时间，格式为：yyyy-MM-dd'T'HH:mm:ss'Z'，该时间会通过urlencode转义为%3a。

当短信平台未收到短信中心上报的状态报告时，会自行构造状态报告，该状态报告中不携带“updateTime”参数。

orgCode

否

String(1-7)

无

透传南向网元状态码，仅国际/港澳台短信状态报告携带，国内短信不涉及。

当南向网元未返回状态码时不携带该参数。

extend

否

String(1-128)

无

扩展字段，由用户在发送短信的请求中携带。若用户发送短信时未携带extend参数，则状态报告中也不会携带extend参数。

to

否

String(1-21)

无

本条状态报告对应的短信的接收方号码，仅当状态报告中携带了extend参数时才会同时携带该参数。

响应参数

用户可以返回任意响应消息给短信平台，短信平台不会对响应消息处理。

请求示例

POST /batchReport HTTP/1.1
Host: 205.145.111.168:9330
Content-Type: application/JSON;charset=UTF-8
X-Sdk-Date: 20241212T070653Z
Authorization: SDK-HMAC-SHA256 Access=exampleAk,SignedHeaders=connection;content-length;content-type;host;x-sdk-date,Signature=765a365f3851fd1c96011a82b893266fb7b3e79b3002526c43199c97e61bb88b
Connection: close
Pooltype: approxy
Ompsid: 7f540777fe4b40dfb3c21d10f48781e3
TerminalIP: ******
TrcModule: AP
UserTrace: application
TraceHandle: DMZ_818405

{"statusReportList":[{"sequence":"1","total":"1","updateTime":"2023-04-18T07:26:00Z","source":"2","smsMsgId":"f6dcba15-ced9-45f7-9f5e-af82328c5253_1188602","status":"DELIVRD"},{"sequence":"1","total":"1","updateTime":"2023-04-18T07:26:00Z","source":"2","smsMsgId":"f6dcba15-ced9-45f7-9f5e-af82328c5253_123456","status":"DELIVRD"}]}

响应示例

HTTP/1.1 200 OK 
Date: Fri, 13 Apr 2018 06:31:45 GMT
Content-Type: application/JSON; charset=UTF-8
Content-Length: 43  

{"returnCode":0,"returnCodeDesc":"Success"}