接口概述

• 状态回执是短信在终端用户触达的状态，可以判断终端是否成功接收到了短信。状态分为成功、失败、未知这三大类，成功状态只有一个，即"status":"DELIVRD"，三网均为“DELIVRD”；失败状态的种类比较多，详情请参考回执码查询

---

注意事项

• 只有成功和失败这两大类的状态可以通过本API获得，未知的状态代表空的意思，未知的状态会在72小时内可能有更新，如超过72小时未改变状态，那么不会再变更，并且不会生成回执报告。
• 状态回执的获得方式有两种，即推送和拉取，同时只能选择一种，不可同时选择。
• 每个号码短信的状态回执只能获取一次，当我们推送给您或者您拉取走这一条数据后，将不在重复获得。

---

前置条件（提交短信之前）

前置条件	说明
传入report参数	提交短信接口入参中，传入report参数："report"="true"，否则无法使用回执接口
配置获取方式	新开账户默认为推送方式，如需改为拉取需要登录控制台修改 推送方式的推送地址可通过短信接口传入，也可以登录控制台配置。 单个API账号同一时间只能选择一种获取方式。 回执配置示例 预览

---

状态回执消息体

1、推送的方式

1.1推送 GET 参数

名称	类型	描述	示例
receiver	String	接收验证的用户名，配置时不填写则为空，如需配置请联系技术
pswd	String	接收验证的密码，配置时不填则为空，如需配置请联系技术
mobile	String	接收短信的手机号码	"mobile":"13900000000"
status	String	运营商返回的短信接收状态（接收成功只有一个状态：DELIVRD，其余失败状态请前往 code.253.com 查看）	"status":"DELIVRD"
statusDesc	String	"status"状态里对应的中文解释，内容经过 URLEncode 编码(UTF-8),需要自行解码后得到明文	"statusDesc":"%E7%9F%AD%E4%BF%A1%E5% 8F%91%E9%80%81%E6%88%90%E5%8A%9F"
notifyTime	String	253创蓝平台收到运营商推送状态报告的时间，格式 yyMMddHHmmss	"notifyTime":"241104172820"
reportTime	String	运营商返回的状态更新时间，格式 YYMMddHHmm，其中 YY=年份的最后两位（00-99）	"reportTime":"2411041728"
msgid	String	消息 id（32位纯数字，调用发送接口时接口响应的msgId）	"msgid":"24073116453300902203000007708373"
length	int	下发短信计费条数，纯数字	"length":"1"
uid	String	请求发送接口传了uid参数，则会返回该参数，反之没有	"uid":"154789574"

1.2示例说明

• 比如用户账户设置的短信回送地址为：http://client_url，那么当 253 平台收到运营商回送的短信状态后便会以 GET 请求访问以下 url：

复制成功

http://client_url?receiver=&pswd=&msgid=24073116453300902203000007708373&reportTime=2411041728&mobile=13900000000&status=DELIVRD&notifyTime=241104172820&statusDesc=%E7%9F%AD%E4%BF%A1%E5%8F%91%E9%80%81%E6%88%90%E5%8A%9F&length=1
 

---

1.3推送重试机制

• 推送失败后将自动重试，最多重试2次（共3次推送机会）
• 每次重推间隔时间为1分钟
• 第三次推送失败后，将不再继续推送

---

1.4客户端响应要求

复制成功
{"clcode":"000000"} ---- 代表成功
{"clcode":"111111"} ---- 代表失败，需要重新推送（按照一定规则重新推送）

---

2、拉取的方式

• 我方拉取方式的明细存储上限为100万，建议您在发送短信后设置定时拉取任务，避免因存储上限导致明细丢失。

请求地址：

• 请求方式：json 格式封装的字符串，采用 post 方式提交请求
• Content-Type：application/json
• 编码格式：utf-8
• 请求地址：https://smssh1.253.com/msg/pull/report

参数说明

参数名	类型	是否必须	描述	示例
account	String	是	API 账号	"account":"N9000001"
password	String	是	API 密码（8-16 位）	"password":"ABCdef15301"
count	integer	否	拉取个数（上限 200，默认 20）	"count":"20"

请求示例

复制成功
{
  "account":"N6000001",
  "password":"123456",
  "count":"20"
}

响应参数说明

参数名	类型	描述	示例
ret	int	请求状态。0 成功，其他状态为失败	"ret":0
result	String	状态明细结果，没结果则返回空数组	"result":[{ XXX：XXX }]
mobile	String	接收短信的手机号码	"mobile":"13900000000"
status	String	运营商返回的状态（接收成功只有一个状态：DELIVRD，其余失败状态前往 code.253.com 查看）	"status":"DELIVRD"
statusDesc	String	"status"状态里对应的中文解释	"statusDesc":"短信发送成功
notifyTime	String	253创蓝平台收到运营商推送状态报告的时间，格式 yyMMddHHmmss	"notifyTime":"241104172820"
reportTime	String	运营商返回的状态更新时间，格式 YYMMddHHmm，其中 YY=年份的最后两位（00-99）	"reportTime":"2411041728"
msgId	String	消息 id （32位纯数字，调用发送接口时我们响应的msgId）	"msgId":"24073116453300902203000007708373"
length	String	下发短信计费条数，纯数字	"length":"1"
uid	String	请求发送接口传了uid参数，则会返回该参数，反之没有	"uid":"154789574"

响应示例

复制成功
{
  "ret":0,
  "result":[{
    "uid":"154789574",
    "statusDesc":"短信发送成功",
    "notifyTime":"241104172820",
    "mobile":"13900000000",
    "msgId":"24073116453300902203000007708373",
    "reportTime":"2411041728",
    "status":"DELIVRD",
    "length": "1"
  }]
}