junhong_cmp_fiber/docs/第三方文档/SMS_HTTP_1.6.md at 9e67914b1b92f5190947fe35f3d92a315f4baa06

csxj2026/junhong_cmp_fiber

Files

- 添加个人客户微信登录和手机验证码登录接口
- 实现个人客户设备、ICCID、手机号关联管理
- 添加短信发送服务（HTTP 客户端）
- 添加微信认证服务（含 mock 实现）
- 添加 JWT Token 生成和验证工具
- 创建数据库迁移脚本（personal_customer 关联表）
- 修复测试文件中的路由注册参数错误
- 重构 scripts 目录结构（分离独立脚本到子目录）

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-10 11:42:38 +08:00

25 KiB

Raw Blame History

短信网关接口规范(JSON)

version 1.6

| 版本修订历史 | | | | --- | | | --- | --- | | 版本 | 日期 | 说明 | | 1.0 | 2020-06-09 | 接口规范与参数定义 | | 1.1 | 2020-11-01 | 增强接口调用安全性 | | 1.2 | 2021-04-21 | 增加添加短信模板接口 | | 1.3 | 2021-07-01 | 增加查询短信模板接口 | | 1.4 | 2021-11-25 | 增加签名报备与查询接口 | | 1.5 | 2023-06-08 | 统一参数sign计算规则 | | 1.6 | 2025-03-21 | 发送接口新增模板Id参数 |

1. 前言 4

2. 短信批量发送接口 5

2.1 调用地址 5

2.2 请求包头定义 5

2.3 请求参数 5

2.4 响应结果 5

2.5 请求示例 5

3. 短信一对一发送接口 6

3.1 调用地址 6

3.2 请求包头定义 6

3.3 请求参数 6

3.4 响应结果 7

3.5 请求示例 7

4. 回执状态推送接口 8

4.1 调用地址 8

4.2 推送请求包头定义 8

4.3 请求参数 8

4.4 响应结果 9

4.5 推送请求示例 9

5. 上行回复推送接口 9

5.1 调用地址 9

5.2 推送请求包头定义 9

5.3 请求参数 9

5.4 响应结果 10

5.5 推送请求示例 10

6. 回执状态获取接口 10

6.1 调用地址 10

6.2 请求包头定义 10

6.3 请求参数 10

6.4 响应结果 11

6.5 请求示例 11

7. 上行回复获取接口 12

7.1 调用地址 12

7.2 请求包头定义 12

7.3 请求参数 12

7.4 响应结果 13

7.5 请求示例 13

8. 查询余额接口 14

8.1 调用地址 14

8.2 请求包头定义 14

8.3 请求参数 14

8.4 响应结果 14

8.5 请求示例 14

9. 提交短信模板接口 15

9.1 调用地址 15

9.2 请求包头定义 15

9.3 请求参数 15

9.4 响应结果 15

9.5 请求示例 16

10. 查询短信模板接口 16

10.1 调用地址 16

10.2 请求包头定义 16

10.3 请求参数 16

10.4 响应结果 17

10.5 请求示例 17

11. 报备签名接口 18

11.1 调用地址 18

11.2 请求包头定义 18

11.3 请求参数 18

11.4 响应结果 18

11.5 请求示例 18

12. 查询签名接口 19

12.1 调用地址 19

12.2 请求包头定义 19

12.3 请求参数 19

12.4 响应结果 19

12.5 请求示例 19

13. 响应状态码列表 20

前言

本协议基于HTTP服务，使用POST请求方式，请求和应答均为JSON格式数据.。

字段命名方式：驼峰法。

统一请求和响应编码：UTF-8

统一请求Header内容：Content-Type: application/json

请使用接口网关地址替换文档中的服务器地址：http://{address:port}/sms

sign参数计算规则：多个指定参数值组合成字符串后计算MD5 32位小写结果

要求：MD5(userName + timestamp + MD5(password))

假设：userName(帐号名)=test

password(帐号密码)=123

timestamp=1596254400000

计算：MD5(password)=202cb962ac59075b964b07152d234b70

组合字符串：test1596254400000202cb962ac59075b964b07152d234b70

sign结果：MD5(组合字符串)=e315cf297826abdeb2092cc57f29f0bf

短信批量发送接口

1. 调用地址

地址：http://{address:port}/sms**/api/sendMessageMass**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
content	String	是	可选短信内容，与短信模板ID必传其一
templateId	Integer	可选短信模板ID，与短信内容必传其一
params	{Object}	否	当使用短信模板ID且模板包含变量时必填。格式：{"变量名1":"变量值1", "变量名2":"变量值2"}
phoneList	[Array]	是	发送手机号码，JSON数组格式。最大数量不得超过10000个号码，系统将自动去除重复号码。
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
sendTime	String	否	短信定时发送时间，格式：yyyy-MM-dd HH:mm:ss。定时时间限制15天以内。
extcode	String	否	可选，附带通道扩展码
callData	String	否	用户回传数据，最大长度64。用户若传递此参数将在回执推送时回传给用户。

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
msgId	Long	当code=0时，系统返回唯一消息Id
smsCount	Integer	当code=0时，系统返回消耗计费总数

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/sendMessageMass

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"content": "【签名】您的验证码是123456",

"phoneList": ["13500000001", "13500000002", "13500000003"],

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"msgId": 123456,

"smsCount": 3

}

短信一对一发送接口

1. 调用地址

地址：http://{address:port}/sms**/api/sendMessageOne**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
messageList	[Array]	是	数组形式，包含多个JSON对象，对象参数见下表。每个JSON对象包含短信内容和号码数据，最大1000个号码。
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
sendTime	String	否	短信定时发送时间，格式：yyyy-MM-dd HH:mm:ss。定时时间限制15天以内。

messageList由多个JSON对象构成的JSON数组，具体参数列表：

参数名	类型	必填	说明
phone	String	是	发送手机号码
content	String	是	可选短信内容，与短信模板ID必传其一
templateId	Integer	可选短信模板ID，与短信内容必传其一
params	{Object}	否	当使用短信模板ID且模板包含变量时必填。格式：{"变量名1":"变量值1", "变量名2":"变量值2"}
extcode	String	否	可选，附带通道扩展码
callData	String	否	用户回传数据，最大长度64。用户若传递此参数将在回执推送时回传给用户。

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	当code=0时，系统返回处理结果的数组对象集合，对象参数见下表。
smsCount	Integer	当code=0时，系统返回消耗此次请求的计费总数

data由多个JSON对象构成的JSON数组，具体参数列表：

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
phone	String	发送手机号码
msgId	Long	当code=0时，系统返回唯一消息Id
smsCount	Integer	当code=0时，系统返回此号码的计费数

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/sendMessageOne

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"messageList": [

{

"phone": "13500000001",

"content" : "【签名】尊敬的张先生，本次共消费211.45元"

{

"phone": "13500000002",

"content" : "【签名】尊敬的林女士，本次共消费78.00元"

}

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"smsCount": 2,

"data": [

{

"code": 0,

"message": "处理成功",

"msgId": 11600001,

"phone": "13500000001",

"smsCount": 1

{

"code": 0,

"message": "处理成功",

"msgId": 11600002,

"phone": "13500000002",

"smsCount": 1

}

]

}

回执状态推送接口

1. 调用地址

地址：客户需向我司提交接收回执状态地址，由平台主动推送回执状态数据

推送请求方法：POST

1. 推送请求包头定义

Content-Type: application/json;charset=utf-8

1. 请求参数

推送数据为JSON数组形式，每次推送不大于2000条。推送字段如下：

参数名	类型	必填	说明
msgId	Long	是	消息id，对应发送成功时系统响应的msgId
phone	String	是	手机号码
status	String	是	回执状态，DELIVRD成功，其他失败
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
smsCount	Integer	是	此发送号码的计费条数
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回
diffStatus	[Array]	否	当长短信拆分发送后回执状态码不一致时，会将多个片段状态码传递此参数。字符串数组格式，例如：['DELIVRD', 'MK:0001']

1. 响应结果

正常响应HTTP状态码200即可。非200状态码将转换为客户获取形式

1. 推送请求示例

[

{

"msgId": 11600001,

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32",

"status": "DELIVRD",

"smsCount": 1

{

"msgId": 11600002,

"phone": "13500000002",

"receiveTime": "2020-06-09 11:10:32",

"status": "FAILURE",

"smsCount": 1

}

]

上行回复推送接口

1. 调用地址

地址：客户需向我司提交接收上行回复地址，由平台主动推送上行回复数据

推送请求方法：POST

1. 推送请求包头定义

Content-Type: application/json;charset=utf-8

1. 请求参数

推送数据为JSON数组形式，每次推送不大于2000条。推送字段如下：

参数名	类型	必填	说明
content	String	是	上行回复内容
phone	String	是	手机号码
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
destId	String	否	通道端口号
msgId	Long	否	短信发送提交时响应的消息id
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回

1. 响应结果

正常响应HTTP状态码200即可。非200状态码将转换为客户获取形式

1. 推送请求示例

[

{

"content": "好的, 已收到",

"destId": "106203069598",

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32"

{

"content": "OK",

"phone": "13500000002",

"receiveTime": "2020-06-09 11:10:32"

}

]

回执状态获取接口

1. 调用地址

地址：http://{address:port}/sms**/api/getReport**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

此接口每次请求间隔时间不得小于30秒，如果获取条数为limit(默认2000条)表示还有回执未获取，可立即再次请求获取回执。

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
limit	Integer	否	最大获取数，默认2000，可选范围10~10000

1. 响应结果

响应为JSON形式，每次获取不大于limit(默认2000条)，已获取数据不会被再次获取到。

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	获取的回执列表。JSON数组形式，具体字段如下

data包含推送字段如下（与4.3推送参数一致）

参数名	类型	必填	说明
msgId	Long	是	消息id，对应发送成功时系统响应的msgId
phone	String	是	手机号码
status	String	是	回执状态，DELIVRD成功，其他失败
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
smsCount	Integer	是	此发送号码的计费条数
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回
diffStatus	[Array]	否	当长短信拆分发送后回执状态码不一致时，会将多个片段状态码传递此参数。字符串数组格式，例如：['DELIVRD', 'MK:0001']

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/getReport

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{

"msgId": 11600001,

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32",

"status": "DELIVRD",

"smsCount": 1

{

"msgId": 11600002,

"phone": "13500000002",

"receiveTime": "2020-06-09 11:10:32",

"status": "FAILURE",

"smsCount": 1

}

]

}

上行回复获取接口

1. 调用地址

地址：http://{address:port}/sms**/api/getUpstream**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

此接口每次请求间隔时间不得小于30秒，如果获取条数为limit(默认2000条)表示还有上行未获取，可立即再次请求获取上行数据。

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
limit	Integer	否	最大获取数，默认2000，可选范围10~10000

1. 响应结果

响应为JSON形式，每次获取不大于limit(默认2000条)，已获取数据不会被再次获取到。

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	获取的上行列表。JSON数组形式，具体字段如下

data包含推送字段如下（与5.4推送参数一致）

参数名	类型	必填	说明
content	String	是	上行回复内容
phone	String	是	手机号码
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
destId	String	否	通道端口号
msgId	Long	否	短信发送提交时响应的消息id
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/getUpstream

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{

"content": "好的, 已收到",

"destId": "106203069598",

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32"

{

"content": "OK",

"phone": "13500000002",

"receiveTime": "2020-06-09 11:10:32"

}

]

}

查询余额接口

1. 调用地址

地址：http://{address:port}/sms**/api/getBalance**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
balance	Long	当code=0时，系统返回帐号短信余额

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/getBalance

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"balance": 967793

}

提交短信模板接口

1. 调用地址

地址：http://{address:port}/sms**/api/createTemplate**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
content	String	是	模板内容，内容文本中变量符：{%变量%}
type	Integer	否	模板类型，1 - 精准目标，2 - 模糊模板。默认为精确模板
matchPercent	Integer	否	模糊匹配百分比，当type=2时必填，有效范围：60-100
expireDate	String	否	失效日期，格式：yyyy-MM-dd。留空为永久有效

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
templateId	Integer	短信模板Id

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/createTemplate

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf",

"content": "【签名】您的验证码是{%变量%} "

}

响应结果：

{

"code": 0,

"message": "处理成功",

"templateId": 336

}

查询短信模板接口

1. 调用地址

地址：http://{address:port}/sms**/api/queryTemplates**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

此接口每次请求间隔时间不得小于60秒。

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
templateId	Integer	否	短信模板Id

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	JSON对象数组, 返回已生效的短信模板列表。如果指定查询模板Id，只返回此模板已生效内容，不生效则返回空数组。 templateId: 模板Id content: 模板内容 type: 模板类型，1 - 精准目标，2 - 模糊模板 matchPercent: 模板匹配度，type=2时必填

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/queryTemplates

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{ "templateId": 1, "content": "【签名】您的验证码是{%变量%}", "type": 1 },

{ "templateId": 2, "content": "【签名】亲爱的顾客, 您本次共消费12元, 感谢光临", "type": 1, "matchPercent": 80 }

]

}

报备签名接口

1. 调用地址

地址：http://{address:port}/sms**/api/addSignature**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

此接口用于提交报备短信签名，提交后的签名需经过审核方可生效。

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))
signatureList	[Array]	是	报备签名列表，JSON数组格式。数组内填写报备签名，包含完整"【】"符号，例如：["【签名1】", "【签名2】"]

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/addSignature

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf",

"signatureList": ["【签名1】", "【签名2】"]

}

响应结果：

{

"code": 0,

"message": "处理成功"

}

查询签名接口

1. 调用地址

地址：http://{address:port}/sms**/api/querySignature**

请求方法：POST

1. 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

1. 请求参数

此接口每次请求间隔时间不得小于30秒，可查询帐号可用的所有短信签名。

参数名	类型	必填	说明
userName	String	是	帐号用户名
timestamp	Long	是	当前时间戳，精确到毫秒。例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则计算：MD5(userName + timestamp + MD5(password))

1. 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	可用签名列表，JSON数组格式。例如：["【签名1】", "【签名2】"]

1. 请求示例

发送请求：

POST http://{address:port}/sms/api/querySignature

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "test",

"timestamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功"

"data": ["【签名1】", "【签名2】"]

}

响应状态码列表

状态码	说明
0	处理成功
1	帐号名为空
2	帐号名或密码鉴权错误
3	帐号已被锁定
4	此帐号业务未开通
5	帐号余额不足
6	缺少发送号码
7	超过最大发送号码数
8	发送消息内容为空
9	无效的RCS模板ID
10	非法的IP地址，提交来源IP地址与帐号绑定IP不一致
11	24小时发送时间段限制
12	定时发送时间错误或超过15天
13	请求过于频繁，每次获取数据最小间隔为30秒
14	错误的用户扩展码
16	时间戳差异过大，与系统时间误差不得超过5分钟
18	帐号未进行实名认证
19	帐号未开放回执状态
22	缺少必填参数
23	用户帐号名重复
24	用户无签名限制
25	签名需要包含【】符
50	缺少模板标题
51	缺少模板内容
52	模板内容不全
53	不支持的模板帧类型
54	不支持的文件类型
97	此链接不支持GET请求
98	HTTP Content-Type错误, 请设置Content-Type: application/json
99	错误的请求JSON字符串
500	系统异常

25 KiB Raw Blame History Unescape Escape

短信网关接口规范(JSON)

前言

短信批量发送接口

短信一对一发送接口

回执状态推送接口

上行回复推送接口

回执状态获取接口

上行回复获取接口

查询余额接口

提交短信模板接口

查询短信模板接口

报备签名接口

查询签名接口

响应状态码列表

25 KiB

Raw Blame History