铁布衫MiCPaaS短信 HTTP 接口文档 v2.0
短信平台 HTTP 接口文档
HTTP API REFERENCE · 短信服务

铁布衫MiCPaaS短信平台 HTTP 接口文档

面向接入方的标准接口参考,覆盖短信发送、状态报告、上行回复、余额查询、模板与签名报备,以及鉴权签名与 AES 加密规则。

版本 v2.0Base URL https://www.8dx.cn 协议 HTTP / HTTPS编码 UTF-8 更新日期 2026-11-17
01

鉴权与通用约定

所有主动调用接口均需携带 sp_id 及一种鉴权凭据。

方式 A · password

将平台分配的产品密码做 MD5 处理后作为 password 参数传入。适合服务端固定凭据调用。

签名计算时 password 本身属于参与排序的参数。

方式 B · signature

按「签名生成规则」对全部请求参数做 HMAC-SHA1 + Base64 运算,结果作为 signature 传入。

signature 参数本身不参与签名计算。

约定项说明
基础地址https://www.8dx.cn
请求参数(POST)application/x-www-form-urlencoded 表单参数
请求参数(GET)QueryString 查询参数(依据签名规则中的参数拼接约定)
响应格式JSON;code = 0 表示成功
鉴权signature 与 password 二选一,必传其一
字符编码UTF-8;推送回调为 UTF-8 原始字节流
幂等与消费状态报告 / 上行回复每条仅可获取或推送一次
特殊限制不支持 curl 的 100 continue 协议,详见「接入注意事项」
02

接口总览

共 13 个接口:11 个主动调用 + 2 个平台回调推送。

序号接口方式路径说明
01单条短信发送POST/api/send-sms-single黑名单、模板、通道等拦截类错误在本次请求中实时返回。
02批量短信发送POST/api/send-sms-batch相同内容群发;一次最多提交 10,000 个号码,拦截类错误实时返回。
03变量短信发送POST/api/send-variable同一模板按号码注入不同变量;一次最多提交 10,000 条,拦截类错误实时返…
04一对一批量发送POST/api/send-biunique每个号码对应不同内容;一次最多提交 500 条,拦截类错误实时返回。
05获取状态报告GET/api/report主动拉取短信送达状态。每条短信状态仅可获取一次,拉取后平台不再返回。
06推送状态报告PUSH回调地址由平台主动向您配置的回调地址推送送达状态,每条短信仅推送一次。
07获取用户上行回复GET/api/get-reply主动拉取用户回复的上行短信(如退订)。每条上行仅可获取一次。
08推送用户上行回复PUSH回调地址由平台主动推送用户上行回复,每条上行仅推送一次。
09获取余额GET/api/balance查询当前产品账户的可用余额。
10模板报备POST/api/add-template提交短信模板供平台审核,审核通过后方可用于发送。
11获取模板审核状态GET/api/get-template-status按模板 ID 查询审核结果。
12签名报备POST/api/add-sign提交短信签名供平台审核,审核通过后方可在短信内容中使用。
13获取签名审核状态GET/api/get-sign-status按签名 ID 查询审核结果。
03

03

短信发送接口

01

单条短信发送

POSThttps://www.8dx.cn/api/send-sms-single

黑名单、模板、通道等拦截类错误在本次请求中实时返回。

请求方式 POST返回格式 JSONContent-Type application/x-www-form-urlencoded鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
mobilestring是单个手机号;支持 AES 加密传输,见「AES 加密规则」17600000000
contentstring是短信内容;支持 AES 加密传输。需包含已报备签名【测试】验证码1234
signaturestring否HMAC-SHA1 签名,与 password 二选一<40位十六进制签名>
passwordstring否产品密码的 MD5 值,与 signature 二选一<32位MD5值>
extstring否扩展号,用于状态报告 / 上行回复的归属识别123

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
msg_idint否消息 ID,用于与状态报告匹配;仅成功时返回17
datastring否拦截等原因码,仅失败时返回,见「错误码(data)」WL:NMLJ

请求示例

cURL / HTTP
curl -X POST 'https://www.8dx.cn/api/send-sms-single' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'mobile=17600000000' \
  --data-urlencode 'content=【测试】验证码1234' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' \
  --data-urlencode 'ext=123' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "msg_id": 17
}

响应示例(失败 / 部分失败)

JSON
{
  "code": 10208,
  "msg": "短信进拦截",
  "data": "WL:NMLJ"
}
注意事项
  • mobile 与 content 均支持 AES 加密,加密后需改用 -aes 后缀地址。
  • 本接口为实时拦截返回:发送成功仅代表平台已受理,最终送达结果需通过状态报告确认。
02

批量短信发送

POSThttps://www.8dx.cn/api/send-sms-batch

相同内容群发;一次最多提交 10,000 个号码,拦截类错误实时返回。

请求方式 POST返回格式 JSONContent-Type application/x-www-form-urlencoded鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id766586
mobilesstring是手机号列表,多个号码以英文逗号 , 分隔17600000000,17100000000
contentstring是短信内容,本批次所有号码使用同一内容【测试】验证码1234
signaturestring否HMAC-SHA1 签名,与 password 二选一<40位十六进制签名>
passwordstring否产品密码的 MD5 值,与 signature 二选一<32位MD5值>
extstring否扩展号123

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
msg_idint否批次消息 ID;与批次内手机号共同构成唯一标识17
failed_dataobject否发送号码中失败号码对应的错误码,全部成功时为空数组{"17600000000":"WL:CWHM"}

请求示例

cURL / HTTP
curl -X POST 'https://www.8dx.cn/api/send-sms-batch' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'mobiles=17600000000,17100000000' \
  --data-urlencode 'content=【测试】验证码1234' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "msg_id": 17,
  "failed_data": {}
}

响应示例(失败 / 部分失败)

JSON
{
  "code": 0,
  "msg": "success",
  "msg_id": 17,
  "failed_data": {
    "17100000000": "WL:CWHM"
  }
}
注意事项
  • 一次最多 10,000 个号码;超限建议拆分为多批次。
  • 即使 code=0 也需检查 failed_data:部分号码可能被拦截或号码错误。
03

变量短信发送

POSThttps://www.8dx.cn/api/send-variable

同一模板按号码注入不同变量;一次最多提交 10,000 条,拦截类错误实时返回。

请求方式 POST返回格式 JSONContent-Type application/x-www-form-urlencoded鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id766586
paramsstring是变量参数:多条短信以英文分号 ; 分隔,多个变量之间以英文逗号 , 分隔,变量前带手机号17600000000,822233;17500000000,656552
contentstring是短信内容模板,变量以 ${Text} 形式占位【测试】验证码${Text}
signaturestring否HMAC-SHA1 签名,与 password 二选一<40位十六进制签名>
passwordstring否产品密码的 MD5 值,与 signature 二选一<32位MD5值>
extstring否扩展号123

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
msg_idint否批次消息 ID;与批次内手机号共同构成唯一标识17
failed_dataobject否失败号码对应的错误码,全部成功时为空数组{"17600000000":"WL:CWHM"}

请求示例

cURL / HTTP
curl -X POST 'https://www.8dx.cn/api/send-variable' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'params=17600000000,822233;17500000000,656552' \
  --data-urlencode 'content=【测试】验证码${Text}' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "msg_id": 17,
  "failed_data": {}
}
注意事项
  • 内容模板须先完成模板报备,否则可能返回 WL:NMLJ / WL:ZJLJ 等拦截码。
  • params 中的分隔符均为英文半角字符,中文分号 / 逗号会导致解析失败。
04

一对一批量发送

POSThttps://www.8dx.cn/api/send-biunique

每个号码对应不同内容;一次最多提交 500 条,拦截类错误实时返回。

请求方式 POST返回格式 JSONContent-Type application/x-www-form-urlencoded鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id766586
paramsstring是一对一参数,JSON 字符串;key 为手机号,value 为短信内容{"17655555555":"测试111","17666666666":"测试222"}
signaturestring否HMAC-SHA1 签名,与 password 二选一<40位十六进制签名>
passwordstring否产品密码的 MD5 值,与 signature 二选一<32位MD5值>
extstring否扩展号123

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
msg_idint否批次消息 ID;与批次内手机号共同构成唯一标识17
failed_dataobject否失败号码对应的错误码,全部成功时为空数组{"17655555555":"WL:CWHM"}

请求示例

cURL / HTTP
curl -X POST 'https://www.8dx.cn/api/send-biunique' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'params={"17655555555":"测试111","17666666666":"测试222"}' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "msg_id": 17,
  "failed_data": {}
}
注意事项
  • 一次最多 500 条,是四个发送接口中上限最低的一个。
  • 每条内容都需符合签名 / 模板报备要求,逐条校验。
04

04

状态报告与上行回复

05

获取状态报告

GEThttps://www.8dx.cn/api/report

主动拉取短信送达状态。每条短信状态仅可获取一次,拉取后平台不再返回。

请求方式 GET返回格式 JSON鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
datastring否状态记录;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2

data 字段构成

字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。

序号字段说明示例
1扩展号发送接口传入的 ext123
2msg_id发送接口返回的 msg_id2
3手机号接收号码1762532xxxx
4状态运营商回执状态DELIVRD
5时间回执时间2021-12-23 01:02:03
6售价本条计费金额0.2

请求示例

cURL / HTTP
curl -G 'https://www.8dx.cn/api/report' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": "123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2|123,2,17862532xxxx,DELIVRD,2021-12-23 01:02:03,0.1"
}
重点提示
  • 重要:拉取即消费。请在成功拉取后立即按「手机号 + msg_id」落库,否则状态将永久丢失。
  • 建议定时轮询;若无新状态,data 通常为空,需做好空值处理。
06

推送状态报告

PUSH(平台回调您的接收地址)

由平台主动向您配置的回调地址推送送达状态,每条短信仅推送一次。

请求方式 POST(平台推送)返回格式 —(回调,无响应体)Content-Type text/plain; charset=utf-8(原始字节流)鉴权 signature 或 password 二选一

回调说明

项说明
注意事项推送使用 POST 方式,请求体为 UTF-8 原始字节流(非表单、非 JSON)
推送格式扩展号,msg_id,手机号,状态,时间,售价;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔
内容示范123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2|123,2,17862532xxxx,DELIVRD,2021-12-23 01:02:03,0.1

推送字段构成

字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。

序号字段说明示例
1扩展号发送接口传入的 ext123
2msg_id发送接口返回的 msg_id2
3手机号接收号码1762532xxxx
4状态运营商回执状态DELIVRD
5时间回执时间2021-12-23 01:02:03
6售价本条计费金额0.2

请求 / 推送示例

cURL / HTTP
POST <您的回调地址> HTTP/1.1
Content-Type: text/plain; charset=utf-8

123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2|123,2,17862532xxxx,DELIVRD,2021-12-23 01:02:03,0.1

接收端应答

JSON / TEXT
接收方应返回 HTTP 200,否则平台可能判定推送失败并重试。
重点提示
  • 接收端需按 UTF-8 原始字节流读取请求体,请勿按 application/x-www-form-urlencoded 解析。
  • 回调地址需在平台侧配置;与「获取状态报告」二选一使用,避免状态重复或遗漏。
07

获取用户上行回复

GEThttps://www.8dx.cn/api/get-reply

主动拉取用户回复的上行短信(如退订)。每条上行仅可获取一次。

请求方式 GET返回格式 JSON鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
datastring否上行记录;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔TD,158114xxxx,100000006,048842426601,20220325123304

data 字段构成

字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。

序号字段说明示例
1回复内容经 urlencode 编码的上行内容TD
2手机号发送上行短信的号码158114xxxx
3msg_id发送接口返回的 msg_id100000006
4扩展号发送接口传入的 ext048842426601
5时间上行时间,格式 yyyyMMddHHmmss20220325123304

请求示例

cURL / HTTP
curl -G 'https://www.8dx.cn/api/get-reply' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": "TD,158114xxxx,100000006,048842426601,20220325123304|退订,1891456xxxx,100000007,0615,20211115173903"
}
重点提示
  • 重要:拉取即消费。请落库后再按 msg_id / 手机号 自行匹配原下发短信。
  • 回复内容为 urlencode 后的字符串,业务使用前需做 URL 解码。
08

推送用户上行回复

PUSH(平台回调您的接收地址)

由平台主动推送用户上行回复,每条上行仅推送一次。

请求方式 POST(平台推送)返回格式 —(回调,无响应体)Content-Type text/plain; charset=utf-8(原始字节流)鉴权 signature 或 password 二选一

回调说明

项说明
注意事项推送使用 POST 方式,请求体为 UTF-8 原始字节流(非表单、非 JSON)
推送格式urlencode 后的内容,手机号,扩展号,时间;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔
内容示范TD,158114xxxx,048842426601,20220325123304|退订,1891456xxxx,0615,20211115173903

推送字段构成

字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。

序号字段说明示例
1回复内容经 urlencode 编码的上行内容TD
2手机号发送上行短信的号码158114xxxx
3扩展号发送接口传入的 ext048842426601
4时间上行时间,格式 yyyyMMddHHmmss20220325123304

请求 / 推送示例

cURL / HTTP
POST <您的回调地址> HTTP/1.1
Content-Type: text/plain; charset=utf-8

TD,158114xxxx,048842426601,20220325123304|退订,1891456xxxx,0615,20211115173903

接收端应答

JSON / TEXT
接收方应返回 HTTP 200,否则平台可能判定推送失败并重试。
重点提示
  • 注意:推送格式中不含 msg_id,与「获取用户上行回复」的 5 字段格式不同,解析时勿混用。
  • 回复内容为 urlencode 后的字符串,业务使用前需做 URL 解码。
05

05

账户、模板与签名

09

获取余额

GEThttps://www.8dx.cn/api/balance

查询当前产品账户的可用余额。

请求方式 GET返回格式 JSON鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
dataobject否余额信息{"balance": "99999.89"}

请求示例

cURL / HTTP
curl -G 'https://www.8dx.cn/api/balance' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": {
    "balance": "99999.89"
  }
}
注意事项
  • balance 为字符串形式的金额,做数值比较前需显式转换。
  • 余额不足时发送接口返回 code=10011。
10

模板报备

POSThttps://www.8dx.cn/api/add-template

提交短信模板供平台审核,审核通过后方可用于发送。

请求方式 POST返回格式 JSONContent-Type application/x-www-form-urlencoded鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>
templatestring是模板内容,变量占位符按平台约定书写【测试】您的验证码是%不要告诉他人

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
dataobject否模板 ID{"temp_id": 123456}

请求示例

cURL / HTTP
curl -X POST 'https://www.8dx.cn/api/add-template' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'template=【测试】您的验证码是%不要告诉他人' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": {
    "temp_id": 123456
  }
}
注意事项
  • 返回的 temp_id 用于「获取模板审核状态」查询。
  • 模板中的 % 为源文档示例里的变量占位写法,实际占位符请与平台客服确认。
11

获取模板审核状态

GEThttps://www.8dx.cn/api/get-template-status

按模板 ID 查询审核结果。

请求方式 GET返回格式 JSON鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>
temp_idstring是模板报备接口返回的模板 ID123456

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
dataobject否审核状态 status:0 待审核 / 1 审核通过 / 2 被驳回{"status": "1"}

请求示例

cURL / HTTP
curl -G 'https://www.8dx.cn/api/get-template-status' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'temp_id=123456' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "1"
  }
}
注意事项
  • status 为字符串,取值 "0" / "1" / "2"。
12

签名报备

POSThttps://www.8dx.cn/api/add-sign

提交短信签名供平台审核,审核通过后方可在短信内容中使用。

请求方式 POST返回格式 JSONContent-Type application/x-www-form-urlencoded鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>
signstring是签名内容,需带【】【测试签名2】

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
dataobject否签名 ID{"sign_id": 285229}

请求示例

cURL / HTTP
curl -X POST 'https://www.8dx.cn/api/add-sign' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'sign=【测试签名2】' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": {
    "sign_id": 285229
  }
}
注意事项
  • 返回的 sign_id 用于「获取签名审核状态」查询。
  • 未报备签名会导致发送被拦截(WL:QWBB / WL:MQM)。
13

获取签名审核状态

GEThttps://www.8dx.cn/api/get-sign-status

按签名 ID 查询审核结果。原文档此章节编号误写为「十一」,本版修正为「十三」。

请求方式 GET返回格式 JSON鉴权 signature 或 password 二选一

请求参数

参数名类型必填说明示例
sp_idstring是产品 sp_id(账户产品标识,由平台分配)766586
signaturestring否HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」<40位十六进制签名>
passwordstring否产品密码经 MD5 处理后的值,与 signature 二选一<32位MD5值>
sign_idstring是签名报备接口返回的签名 ID285229

响应字段

字段名类型返回说明示例
codeint是状态码,0 表示成功,其余见「错误码(code)」0
msgstring是结果描述:成功为 success,失败为具体提示success
dataobject否审核状态 status:0 待审核 / 1 审核通过 / 2 审核未通过{"status": "1"}

请求示例

cURL / HTTP
curl -G 'https://www.8dx.cn/api/get-sign-status' \
  -H 'Expect:' \
  --data-urlencode 'sp_id=766586' \
  --data-urlencode 'sign_id=285229' \
  --data-urlencode 'password=<MD5_OF_PASSWORD>' 

响应示例(成功)

JSON / TEXT
{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "1"
  }
}
注意事项
  • status 为字符串,取值 "0" / "1" / "2"。
06

错误码(code)

接口顶层 code 字段;0 为成功,其余为业务 / 系统错误。

共 13 条
错误码说明
10000服务出错,请稍后再试
10001参数错误,请确认
10008账号被锁定,请联系管理员确认
10011余额不足,请尽快充值
10100签名校验失败
10101您的 IP 不在白名单内,请确认
10102密码错误,请确认
10200产品 sp_id 必须填写
10201手机号必须填写
10202短信内容必须填写
10203发送时间格式必须为 UNIX 时间戳
10208短信进拦截,具体原因参考 data 字段
10209触发防刷,请调整配置
07

错误码(data)

发送被拦截时返回的原因码,常见于单条发送的 data 或批量发送的 failed_data。

共 20 条
错误码说明
WL:MBLJ短信内容匹配到了模板,并且此模板类型是拦截
WL:MBSH命中审核模板
WL:NMLJ短信内容没有匹配到模板,并且用户的模板审核方式是未匹配到就进拦截
WL:NMSH短信内容没有匹配到模板,并且用户的模板审核方式是未匹配到就进审核
WL:KHLJ命中空号,进拦截
WL:QHLJ命中用户签名黑名单,进拦截
WL:SHLJ命中用户 SPID 黑名单,进拦截
WL:CHLJ命中系统产品黑名单,进拦截
WL:CWHM错误号码
WL:QWBB签名未报备,进拦截
WL:MQM需要签名但没有,进拦截
WL:CS超过限速了
WL:ZJLJ不匹配任何模板,直接拦截
WL:CMT产品未配置相应通道,进拦截
WL:CDQC通道不支持该地区发送,进拦截
WL:CGMT产品通道池中没有相应通道,进拦截
WL:CNH所选的通道不健康,进拦截
WL:TCLJ不在发送时间段,进拦截
WL:TCSH不在发送时间段,进审核
WL:CPL超频限制
08

签名生成规则

采用 HMAC-SHA1 + Base64,密钥为产品密码。

步骤动作说明
1整理参数取本次请求的所有参数(不含 signature),按参数名 key 升序排序。
2编码键值对排序后的 key 与 value 分别做 URLEncode,再做三次字符替换:+ → %20、* → %2A、%7E → ~。
3拼接 QueryString按 key=value 拼接,多个参数间用 & 连接,例:a=%E5%93%88%E5%93%88&b=haha。
4拼接请求方法与路径在 QueryString 前拼接:HTTPMethod + "&" + URLEncode("/") + "&" + QueryString。
5HMAC-SHA1以产品密码为密钥,对上一步字符串做 HmacSHA1 摘要。
6Base64对摘要结果做 Base64 编码,得到最终 signature。

规范化字符串

Canonical String
HTTPMethod + "&" + URLEncode("/") + "&" + QueryString

QueryString 示例:
a=%E5%93%88%E5%93%88&b=haha

最终待签名串示例:
POST&%2F&content=%E3%80%90...&sp_id=766586

PHP 参考实现

PHP
<?php
// 按官方「签名生成规则」整理的参考实现,请以平台实际校验结果为准
function buildSignature(string $method, array $params, string $secret): string
{
    unset($params['signature']);
    ksort($params);                              // 1. 按 key 升序

    $pairs = [];
    foreach ($params as $k => $v) {
        $e = rawurlencode((string)$k);
        $e = str_replace(['+', '*', '%7E'], ['%20', '%2A', '~'], $e);
        $p = rawurlencode((string)$v);
        $p = str_replace(['+', '*', '%7E'], ['%20', '%2A', '~'], $p);
        $pairs[] = $e . '=' . $p;                // 2~3. 编码并拼接
    }
    $queryString = implode('&', $pairs);

    // 4. 拼接 HTTPMethod + "&" + URLEncode("/") + "&" + QueryString
    $canonical = strtoupper($method) . '&' . rawurlencode('/') . '&' . $queryString;

    // 5~6. HmacSHA1 + Base64
    return base64_encode(hash_hmac('sha1', $canonical, $secret, true));
}
重点提示
  • 官方原文表述为「HMAC 生成信息摘要时需用您的产品密码作为密钥」;password 参数则为「产品密码经 MD5 处理后的值」。两者是否同一形态,请在联调时与平台确认。
  • 编码替换顺序不可颠倒:先 URLEncode,再将 + → %20、* → %2A、%7E → ~。
  • 参与签名的参数为本次请求的全部参数(不含 signature),且需按 key 升序排列。
09

AES 加密规则

手机号与短信内容可分别加密传输,用于敏感字段保护。

步骤动作说明
1适用字段AES 加密发送时,手机号字段与内容字段需分别加密。
2切换地址在原有发送地址后加 -aes,例如 https://www.8dx.cn/api/send-sms-single-aes。
3准备密钥向客服索取加密 key,并自行生成随机 iv。
4加密明文用 AES-128-CBC 加密手机号或内容,对密文做 Base64 得到字符串 s1。
5编码 iv对 iv 做 Base64 得到字符串 s2。
6组装 JSON生成 s3 = {"iv":"s2","value":"s1"}(JSON_UNESCAPED_SLASHES)。
7最终入参对 s3 再做一次 Base64,放入对应 POST 字段,代替未加密数据。

加密后的入参结构

Algorithm
s1 = Base64( AES-128-CBC(明文, key, iv) )
s2 = Base64( iv )
s3 = {"iv": s2, "value": s1}
最终字段值 = Base64( s3 )

PHP 实现(官方文档原码)

PHP
<?php
// 官方文档提供的 PHP 加密示例
$cipher = 'AES-128-CBC';

$iv = random_bytes(openssl_cipher_iv_length($cipher));

$value = openssl_encrypt($value, $cipher, $key, 0, $iv);

if ($value === false) {
    throw new RuntimeException('Could not encrypt the data.');
}

$iv = base64_encode($iv);

$json = json_encode(compact('iv', 'value'), JSON_UNESCAPED_SLASHES);

if (json_last_error() !== JSON_ERROR_NONE) {
    throw new RuntimeException('Could not encrypt the data.');
}

return base64_encode($json);
重点提示
  • 加密发送地址需在原地址后加 -aes,例如 https://www.8dx.cn/api/send-sms-single-aes。
  • 加密 key 需向平台客服索取;iv 每次随机生成,不可复用。
  • 手机号字段与内容字段需分别加密,各自使用独立的 iv 与密文结构。
10

接入注意事项

上线前请逐项核对,以下均为官方文档明确说明或按其规则推导。

事项说明
禁用 100-continue官方明确说明:本文档所有接口都不支持 curl 的 100 continue 协议。若接口响应过慢,请关闭该协议。PHP cURL 可加入 curl_setopt($ch, CURLOPT_HTTPHEADER, array("Expect:"));命令行 curl 加 -H 'Expect:'。
鉴权二选一signature 与 password 二选一即可,不必同时传。使用 signature 时,该参数本身不参与签名计算。
IP 白名单若返回 10101,需先由管理员将调用方出口 IP 加入白名单。
状态只可取一次获取状态报告 / 上行回复均为「拉取即消费」,务必先落库再做业务处理。
编码请求与响应统一 UTF-8;推送类回调的请求体为 UTF-8 原始字节流。
内容合规短信需包含已报备签名与已审核模板,否则会被拦截并返回 WL: 前缀的 data 错误码。
第三方接口官方页面注明:第三方短信接口请联系客服确认。
11

Demo 下载

平台官方提供的多语言示例,链接指向接口文档所在服务。

12

api文档下载

铁布衫官方提供的标准API对接文档。

铁布衫MiCPaaS短信平台 HTTP 接口文档 · v2.0 · 2026-11-17