铁布衫MiCPaaS短信平台 HTTP 接口文档
面向接入方的标准接口参考,覆盖短信发送、状态报告、上行回复、余额查询、模板与签名报备,以及鉴权签名与 AES 加密规则。
鉴权与通用约定
所有主动调用接口均需携带 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 协议,详见「接入注意事项」 |
接口总览
共 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
短信发送接口
单条短信发送
https://www.8dx.cn/api/send-sms-single黑名单、模板、通道等拦截类错误在本次请求中实时返回。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| mobile | string | 是 | 单个手机号;支持 AES 加密传输,见「AES 加密规则」 | 17600000000 |
| content | string | 是 | 短信内容;支持 AES 加密传输。需包含已报备签名 | 【测试】验证码1234 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一 | <40位十六进制签名> |
| password | string | 否 | 产品密码的 MD5 值,与 signature 二选一 | <32位MD5值> |
| ext | string | 否 | 扩展号,用于状态报告 / 上行回复的归属识别 | 123 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| msg_id | int | 否 | 消息 ID,用于与状态报告匹配;仅成功时返回 | 17 |
| data | string | 否 | 拦截等原因码,仅失败时返回,见「错误码(data)」 | WL:NMLJ |
请求示例
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' 响应示例(成功)
{
"code": 0,
"msg": "success",
"msg_id": 17
}响应示例(失败 / 部分失败)
{
"code": 10208,
"msg": "短信进拦截",
"data": "WL:NMLJ"
}- mobile 与 content 均支持 AES 加密,加密后需改用 -aes 后缀地址。
- 本接口为实时拦截返回:发送成功仅代表平台已受理,最终送达结果需通过状态报告确认。
批量短信发送
https://www.8dx.cn/api/send-sms-batch相同内容群发;一次最多提交 10,000 个号码,拦截类错误实时返回。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id | 766586 |
| mobiles | string | 是 | 手机号列表,多个号码以英文逗号 , 分隔 | 17600000000,17100000000 |
| content | string | 是 | 短信内容,本批次所有号码使用同一内容 | 【测试】验证码1234 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一 | <40位十六进制签名> |
| password | string | 否 | 产品密码的 MD5 值,与 signature 二选一 | <32位MD5值> |
| ext | string | 否 | 扩展号 | 123 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| msg_id | int | 否 | 批次消息 ID;与批次内手机号共同构成唯一标识 | 17 |
| failed_data | object | 否 | 发送号码中失败号码对应的错误码,全部成功时为空数组 | {"17600000000":"WL:CWHM"} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"msg_id": 17,
"failed_data": {}
}响应示例(失败 / 部分失败)
{
"code": 0,
"msg": "success",
"msg_id": 17,
"failed_data": {
"17100000000": "WL:CWHM"
}
}- 一次最多 10,000 个号码;超限建议拆分为多批次。
- 即使 code=0 也需检查 failed_data:部分号码可能被拦截或号码错误。
变量短信发送
https://www.8dx.cn/api/send-variable同一模板按号码注入不同变量;一次最多提交 10,000 条,拦截类错误实时返回。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id | 766586 |
| params | string | 是 | 变量参数:多条短信以英文分号 ; 分隔,多个变量之间以英文逗号 , 分隔,变量前带手机号 | 17600000000,822233;17500000000,656552 |
| content | string | 是 | 短信内容模板,变量以 ${Text} 形式占位 | 【测试】验证码${Text} |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一 | <40位十六进制签名> |
| password | string | 否 | 产品密码的 MD5 值,与 signature 二选一 | <32位MD5值> |
| ext | string | 否 | 扩展号 | 123 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| msg_id | int | 否 | 批次消息 ID;与批次内手机号共同构成唯一标识 | 17 |
| failed_data | object | 否 | 失败号码对应的错误码,全部成功时为空数组 | {"17600000000":"WL:CWHM"} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"msg_id": 17,
"failed_data": {}
}- 内容模板须先完成模板报备,否则可能返回 WL:NMLJ / WL:ZJLJ 等拦截码。
- params 中的分隔符均为英文半角字符,中文分号 / 逗号会导致解析失败。
一对一批量发送
https://www.8dx.cn/api/send-biunique每个号码对应不同内容;一次最多提交 500 条,拦截类错误实时返回。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id | 766586 |
| params | string | 是 | 一对一参数,JSON 字符串;key 为手机号,value 为短信内容 | {"17655555555":"测试111","17666666666":"测试222"} |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一 | <40位十六进制签名> |
| password | string | 否 | 产品密码的 MD5 值,与 signature 二选一 | <32位MD5值> |
| ext | string | 否 | 扩展号 | 123 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| msg_id | int | 否 | 批次消息 ID;与批次内手机号共同构成唯一标识 | 17 |
| failed_data | object | 否 | 失败号码对应的错误码,全部成功时为空数组 | {"17655555555":"WL:CWHM"} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"msg_id": 17,
"failed_data": {}
}- 一次最多 500 条,是四个发送接口中上限最低的一个。
- 每条内容都需符合签名 / 模板报备要求,逐条校验。
04
状态报告与上行回复
获取状态报告
https://www.8dx.cn/api/report主动拉取短信送达状态。每条短信状态仅可获取一次,拉取后平台不再返回。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | string | 否 | 状态记录;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔 | 123,2,1762532xxxx,DELIVRD,2021-12-23 01:02:03,0.2 |
data 字段构成
字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。
| 序号 | 字段 | 说明 | 示例 |
|---|---|---|---|
| 1 | 扩展号 | 发送接口传入的 ext | 123 |
| 2 | msg_id | 发送接口返回的 msg_id | 2 |
| 3 | 手机号 | 接收号码 | 1762532xxxx |
| 4 | 状态 | 运营商回执状态 | DELIVRD |
| 5 | 时间 | 回执时间 | 2021-12-23 01:02:03 |
| 6 | 售价 | 本条计费金额 | 0.2 |
请求示例
curl -G 'https://www.8dx.cn/api/report' \
-H 'Expect:' \
--data-urlencode 'sp_id=766586' \
--data-urlencode 'password=<MD5_OF_PASSWORD>' 响应示例(成功)
{
"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 通常为空,需做好空值处理。
推送状态报告
(平台回调您的接收地址)由平台主动向您配置的回调地址推送送达状态,每条短信仅推送一次。
回调说明
| 项 | 说明 |
|---|---|
| 注意事项 | 推送使用 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 | 扩展号 | 发送接口传入的 ext | 123 |
| 2 | msg_id | 发送接口返回的 msg_id | 2 |
| 3 | 手机号 | 接收号码 | 1762532xxxx |
| 4 | 状态 | 运营商回执状态 | DELIVRD |
| 5 | 时间 | 回执时间 | 2021-12-23 01:02:03 |
| 6 | 售价 | 本条计费金额 | 0.2 |
请求 / 推送示例
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接收端应答
接收方应返回 HTTP 200,否则平台可能判定推送失败并重试。- 接收端需按 UTF-8 原始字节流读取请求体,请勿按 application/x-www-form-urlencoded 解析。
- 回调地址需在平台侧配置;与「获取状态报告」二选一使用,避免状态重复或遗漏。
获取用户上行回复
https://www.8dx.cn/api/get-reply主动拉取用户回复的上行短信(如退订)。每条上行仅可获取一次。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | string | 否 | 上行记录;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔 | TD,158114xxxx,100000006,048842426601,20220325123304 |
data 字段构成
字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。
| 序号 | 字段 | 说明 | 示例 |
|---|---|---|---|
| 1 | 回复内容 | 经 urlencode 编码的上行内容 | TD |
| 2 | 手机号 | 发送上行短信的号码 | 158114xxxx |
| 3 | msg_id | 发送接口返回的 msg_id | 100000006 |
| 4 | 扩展号 | 发送接口传入的 ext | 048842426601 |
| 5 | 时间 | 上行时间,格式 yyyyMMddHHmmss | 20220325123304 |
请求示例
curl -G 'https://www.8dx.cn/api/get-reply' \
-H 'Expect:' \
--data-urlencode 'sp_id=766586' \
--data-urlencode 'password=<MD5_OF_PASSWORD>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"data": "TD,158114xxxx,100000006,048842426601,20220325123304|退订,1891456xxxx,100000007,0615,20211115173903"
}- 重要:拉取即消费。请落库后再按 msg_id / 手机号 自行匹配原下发短信。
- 回复内容为 urlencode 后的字符串,业务使用前需做 URL 解码。
推送用户上行回复
(平台回调您的接收地址)由平台主动推送用户上行回复,每条上行仅推送一次。
回调说明
| 项 | 说明 |
|---|---|
| 注意事项 | 推送使用 POST 方式,请求体为 UTF-8 原始字节流(非表单、非 JSON) |
| 推送格式 | urlencode 后的内容,手机号,扩展号,时间;字段以英文逗号 , 分隔,多条记录以竖线 | 分隔 |
| 内容示范 | TD,158114xxxx,048842426601,20220325123304|退订,1891456xxxx,0615,20211115173903 |
推送字段构成
字段间以英文逗号 , 分隔,多条记录以竖线 | 分隔。下表按原文格式拆解。
| 序号 | 字段 | 说明 | 示例 |
|---|---|---|---|
| 1 | 回复内容 | 经 urlencode 编码的上行内容 | TD |
| 2 | 手机号 | 发送上行短信的号码 | 158114xxxx |
| 3 | 扩展号 | 发送接口传入的 ext | 048842426601 |
| 4 | 时间 | 上行时间,格式 yyyyMMddHHmmss | 20220325123304 |
请求 / 推送示例
POST <您的回调地址> HTTP/1.1
Content-Type: text/plain; charset=utf-8
TD,158114xxxx,048842426601,20220325123304|退订,1891456xxxx,0615,20211115173903接收端应答
接收方应返回 HTTP 200,否则平台可能判定推送失败并重试。- 注意:推送格式中不含 msg_id,与「获取用户上行回复」的 5 字段格式不同,解析时勿混用。
- 回复内容为 urlencode 后的字符串,业务使用前需做 URL 解码。
05
账户、模板与签名
获取余额
https://www.8dx.cn/api/balance查询当前产品账户的可用余额。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | object | 否 | 余额信息 | {"balance": "99999.89"} |
请求示例
curl -G 'https://www.8dx.cn/api/balance' \
-H 'Expect:' \
--data-urlencode 'sp_id=766586' \
--data-urlencode 'password=<MD5_OF_PASSWORD>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"data": {
"balance": "99999.89"
}
}- balance 为字符串形式的金额,做数值比较前需显式转换。
- 余额不足时发送接口返回 code=10011。
模板报备
https://www.8dx.cn/api/add-template提交短信模板供平台审核,审核通过后方可用于发送。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
| template | string | 是 | 模板内容,变量占位符按平台约定书写 | 【测试】您的验证码是%不要告诉他人 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | object | 否 | 模板 ID | {"temp_id": 123456} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"data": {
"temp_id": 123456
}
}- 返回的 temp_id 用于「获取模板审核状态」查询。
- 模板中的 % 为源文档示例里的变量占位写法,实际占位符请与平台客服确认。
获取模板审核状态
https://www.8dx.cn/api/get-template-status按模板 ID 查询审核结果。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
| temp_id | string | 是 | 模板报备接口返回的模板 ID | 123456 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | object | 否 | 审核状态 status:0 待审核 / 1 审核通过 / 2 被驳回 | {"status": "1"} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"data": {
"status": "1"
}
}- status 为字符串,取值 "0" / "1" / "2"。
签名报备
https://www.8dx.cn/api/add-sign提交短信签名供平台审核,审核通过后方可在短信内容中使用。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
| sign | string | 是 | 签名内容,需带【】 | 【测试签名2】 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | object | 否 | 签名 ID | {"sign_id": 285229} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"data": {
"sign_id": 285229
}
}- 返回的 sign_id 用于「获取签名审核状态」查询。
- 未报备签名会导致发送被拦截(WL:QWBB / WL:MQM)。
获取签名审核状态
https://www.8dx.cn/api/get-sign-status按签名 ID 查询审核结果。原文档此章节编号误写为「十一」,本版修正为「十三」。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sp_id | string | 是 | 产品 sp_id(账户产品标识,由平台分配) | 766586 |
| signature | string | 否 | HMAC-SHA1 签名,与 password 二选一,生成方式见「签名生成规则」 | <40位十六进制签名> |
| password | string | 否 | 产品密码经 MD5 处理后的值,与 signature 二选一 | <32位MD5值> |
| sign_id | string | 是 | 签名报备接口返回的签名 ID | 285229 |
响应字段
| 字段名 | 类型 | 返回 | 说明 | 示例 |
|---|---|---|---|---|
| code | int | 是 | 状态码,0 表示成功,其余见「错误码(code)」 | 0 |
| msg | string | 是 | 结果描述:成功为 success,失败为具体提示 | success |
| data | object | 否 | 审核状态 status:0 待审核 / 1 审核通过 / 2 审核未通过 | {"status": "1"} |
请求示例
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>' 响应示例(成功)
{
"code": 0,
"msg": "success",
"data": {
"status": "1"
}
}- status 为字符串,取值 "0" / "1" / "2"。
错误码(code)
接口顶层 code 字段;0 为成功,其余为业务 / 系统错误。
| 错误码 | 说明 |
|---|---|
| 10000 | 服务出错,请稍后再试 |
| 10001 | 参数错误,请确认 |
| 10008 | 账号被锁定,请联系管理员确认 |
| 10011 | 余额不足,请尽快充值 |
| 10100 | 签名校验失败 |
| 10101 | 您的 IP 不在白名单内,请确认 |
| 10102 | 密码错误,请确认 |
| 10200 | 产品 sp_id 必须填写 |
| 10201 | 手机号必须填写 |
| 10202 | 短信内容必须填写 |
| 10203 | 发送时间格式必须为 UNIX 时间戳 |
| 10208 | 短信进拦截,具体原因参考 data 字段 |
| 10209 | 触发防刷,请调整配置 |
错误码(data)
发送被拦截时返回的原因码,常见于单条发送的 data 或批量发送的 failed_data。
| 错误码 | 说明 |
|---|---|
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 | 超频限制 |
签名生成规则
采用 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。 |
| 5 | HMAC-SHA1 | 以产品密码为密钥,对上一步字符串做 HmacSHA1 摘要。 |
| 6 | Base64 | 对摘要结果做 Base64 编码,得到最终 signature。 |
规范化字符串
HTTPMethod + "&" + URLEncode("/") + "&" + QueryString
QueryString 示例:
a=%E5%93%88%E5%93%88&b=haha
最终待签名串示例:
POST&%2F&content=%E3%80%90...&sp_id=766586PHP 参考实现
<?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 升序排列。
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 字段,代替未加密数据。 |
加密后的入参结构
s1 = Base64( AES-128-CBC(明文, key, iv) )
s2 = Base64( iv )
s3 = {"iv": s2, "value": s1}
最终字段值 = Base64( s3 )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 与密文结构。
接入注意事项
上线前请逐项核对,以下均为官方文档明确说明或按其规则推导。
| 事项 | 说明 |
|---|---|
| 禁用 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 错误码。 |
| 第三方接口 | 官方页面注明:第三方短信接口请联系客服确认。 |
Demo 下载
平台官方提供的多语言示例,链接指向接口文档所在服务。
api文档下载
铁布衫官方提供的标准API对接文档。