文档说明

服务器API地址

前缀：

新正式环境:https://spgw-api.gouboyun.tv/

以上具体域名地址以客服提供为主。

完整的API地址为：前缀+具体接口路径

比如，单条下发接口为：

https://spgw-api.gouboyun.tv + /api/sms/send

调用接口说明

如果参数格式是JSON的话：提交request请求时必须添加header头：Content-Type\:application/json
所有的接口的返回形式都是统一为：
- 正常返回

   {
      "code": "0",
      "msg": "OK",
      "success": true,
      "timestamp":时间戳（毫秒）,
      "data": 某种类型的数据，比如字符串，数字，字典等等
   }

- 错误返回

{
      "code": 具体的错误码,
      "msg": "具体的错误信息字符串",
      "success": false,
      "timestamp":时间戳,
}

签名方式说明

signType的值大小写均可
version参数:1 纯数字
属性值为空的不参与签名（null和空字符串）
部分接口字段不参与签名,见具体接口参数说明

参数按ASCII码升序排序拼接成queryParam形式（可固定参数字段从A-Z排序）,最后拼接key=xxxx(apiKey秘钥),使用MD5加密（32位，16进制字符串，utf-编码）,并转大写!

如:原参数,

{
    "appId":"100001",
    "timestamp":187789654135468,
    "sign":"",
    "version":"1",
    "signType":"md5",
    "phone":"136xxxxxxxx",
    "content":"【示例】验证码:1234"
}

排序后:appId=100001&content=【示例】验证码:1234&phone=136xxxxxxxx&signType=md5&timestamp=187789654135468&version=1&key=88888888

md5加密:446169e7368dc80bd3b58b70cdc7f3f9

转大写后:446169E7368DC80BD3B58B70CDC7F3F9

API接口

一、提交接口

目前有4种下发方式，对应分别是：

单条发送
批量发送
点对点发送
定时发送(待开发)

1.单条发送

Request

Method: POST
URL: /api/sms/send
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phone":"",
    "content":"",
    "spMsgId":"",
    "extendNo":""
}

参数说明

参数名称	参数类型	参数说明	示例值	是否必填
appId	字符串	分配给客户的账号		是
timestamp	数字类型	时间戳	到毫秒	是
sign	字符串	验签数据		是
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。	是
version	字符串	接口版本（固定为1）	1	是
phone	字符串	发送号码		是
content	字符串	发送内容		是
spMsgId	字符串	客户平台唯一消息ID(匹配回执用)，可以不传，如传请带上唯一消息ID值。		否
extendNo	字符串	扩展码(纯数字),非必填，如传请带上纯数字值。		否

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "msgId":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID

2.单条发送（定时发送）

Request

Method: POST
URL: /api/sms/send/scheduled
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phone":"",
    "content":"",
    "spMsgId":"",
    "extendNo":"",
    "time":""
}

参数说明

参数名称	参数类型	参数说明	示例值	是否必填
appId	字符串	分配给客户的账号		是
timestamp	数字类型	时间戳	到毫秒	是
sign	字符串	验签数据		是
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。	是
version	字符串	接口版本（固定为1）	1	是
phone	字符串	发送号码		是
content	字符串	发送内容		是
spMsgId	字符串	客户平台唯一消息ID(匹配回执用)，可以不传，如传请带上唯一消息ID值。		否
extendNo	字符串	扩展码(纯数字),非必填，如传请带上纯数字值。		否
time	字符串	yyyy-MM-dd HH:mm:ss格式	2025-07-10 15:30:00	是

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "msgId":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID

3.批量发送

Request

Method: POST
URL: /api/sms/batchSend
Headers(ContentType)：application/json;charset=utf-8
Body:

 {
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phones":[{
        "phone":"",
        "spMsgId":""
    },{
        "phone":"",
        "spMsgId":""
    }],
    "content":"",
    "extendNo":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
content	字符串	发送内容	需要经过urlencode，UTF-8编码
extendNo	字符串	扩展码(非必填,纯数字)
phones	Array	发送号码集合（最大1000个），不参与签名
-phone	字符串	发送号码
-spMsgId	字符串	客户消息ID(客户平台的唯一消息ID,匹配回执用)

Response

Response-v1

URL: /api/sms/batchSend
Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "data": [{
      "msgId":"",
      "phone":"",
    }]
  },
  "timestamp": 1718678782312
}

接口在使用了，不方便修改，返回值多了一层data节点, 可以使用/api/sms/batchSend/v2接口发送。

Response-v2

URL: /api/sms/batchSend/v2
Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp": 1718678782312,
  "data": [{
      "msgId":"",
      "phone":"",
  }]
}

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID
phone	字符串	手机号码

4.批量发送（定时发送）

Request

Method: POST
URL: /api/sms/batchSend/scheduled
Headers(ContentType)：application/json;charset=utf-8
Body:

 {
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phones":[{
        "phone":"",
        "spMsgId":""
    },{
        "phone":"",
        "spMsgId":""
    }],
    "content":"",
    "extendNo":"",
    "time":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
content	字符串	发送内容	需要经过urlencode，UTF-8编码
extendNo	字符串	扩展码(非必填,纯数字)
phones	Array	发送号码集合（最大1000个），不参与签名
-phone	字符串	发送号码
-spMsgId	字符串	客户消息ID(客户平台的唯一消息ID,匹配回执用)
time	字符串	yyyy-MM-dd HH:mm:ss格式	2025-07-10 15:30:00

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp": 1718678782312,
  "data": [{
      "msgId":"",
      "phone":"",
  }]
}

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID
phone	字符串	手机号码

5.点对点发送

Request

Method: POST
URL: /api/sms/batchSend/p2p
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "extendNo":"",
    "sendData":[
        {
            "phone":"",
            "content":"",
            "spMsgId":""
        },
        {
            "phone":"",
            "content":"",
            "spMsgId":""
        },
    ],
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
extendNo	字符串	扩展码(非必填,纯数字)
version	字符串	接口版本	1
sendData	Array	发送内容，不参与签名
-phone	字符串	发送号码,最多不超1000个
-content	字符串	发送内容（使用Urlencode编码，UTF-8）
-spMsgId	字符串	客户消息ID

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": [{
      "msgId":"",
      "phone":"",
  }]
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID
phone	字符串	收集号码

6.单条发送(号码加密)

Request

Method: POST
URL: /api/sms/encrypt/send
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phone":"",
    "spMsgId":"",
    "content":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
extendNo	字符串	扩展码(非必填,纯数字)
phone	字符串	发送号码(使用AES加密,加密秘钥使用账号的appKey)	AES使用ECB模式加密, AES/ECB/PKCS7Padding密钥长度:256bit
content	字符串	发送内容
spMsgId	字符串	客户消息ID

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "msgId":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID

7.批量发送(号码加密)

Request

Method: POST
URL: /api/sms/encrypt/batchSend
Headers(ContentType)：application/json;charset=utf-8
Body:

 {
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phones":[
        "phone"："",
        "spMsgId":""
    ],
    "extendNo":"",
    "content":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
extendNo	字符串	扩展码(非必填,纯数字)
content	字符串	发送内容	发送内容支持Urlencode编码
phones	Array	不参与签名.(号码使用AES加密,加密秘钥使用账号的appKey)	AES使用ECB模式加密, AES/ECB/PKCS7Padding密钥长度:256bit
-phone	字符串	手机号码
-spMsgId	字符串	客户消息ID

Response

Body

 {
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": [{
      "msgId":"",
      "phone":"",
  }]
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID
phone	字符串	收集号码(使用AES加密,加密秘钥使用账号的appKey)	AES使用ECB模式加密, AES/ECB/PKCS7Padding密钥长度:256bit

8.点对点发送(号码加密)

Request

Method: POST
URL: /api/sms/encrypt/batchSend/p2p
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "extendNo":"",
    "sendData":[
        {
            "phone":"",
            "spMsgId":"",
            "content":""
        },
        {
            "phone":"",
            "spMsgId":"",
            "content":""
        },
    ],
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
extendNo	字符串	扩展码(非必填,纯数字)
sendData	Array	发送内容，*不参与签名(使用AES加密,加密秘钥使用账号的appKey，只加密号码)****	只加密号码
-phone	收集号码	发送号码(使用AES加密,加密秘钥使用账号的appKey)	AES使用ECB模式加密, AES/ECB/PKCS7Padding密钥长度:256bit
-content	字符串	发送内容	需要经过urlencode，UTF-8编码
-spMsgId	字符串	客户消息ID

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": [{
      "msgId":"",
      "phone":"",
  }]
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID
phone	字符串	收集号码

9.号码实时检测接口(异步)

Request

Method: POST
URL: /api/phone/asyncCheck
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phones":[
       "",
       ""
    ],
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
phones	Array	待检测手机号码，不参与签名

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "batchNo":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
batchNo	字符串	批次号

10.号码实时检测接口(同步)

待实现...

11.空号检测接口(异步)

Request

Method: POST
URL: /api/phone/empty/asyncCheck
Headers：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phones":[
       "",
       ""
    ],
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
phones	Array	待检测手机号码，不参与签名

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": [
      "batchNo":""
  ]
}

响应说明

参数名称	参数类型	参数说明	示例值
batchNo	字符串	批次号

12.空号检测接口(同步)

待实现...

13.身份认证(三要素)

Request

Method: POST
旧接口地址：http://36.133.15.247:8072/vertx/identify/check/single
新接口地址: https://fsgw.hnykxx.com/vertx/identify/check/single
Headers：application/json;charset=utf-8
Body:

{
    "appId":"123",
    "timestamp":"123",
    "sign":"",
    "version":"",
    "signType":"",
    "name":"",
    "idtype":"",
    "idnum":"",
    "photo":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
name	字符串	姓名，不参与签名	张三
idtype	字符串	证件类型；详见证件类型说明，不参与签名	01
idnum	字符串	证件号码，不参与签名	37**
photo	字符串	图片base64，不参与签名1、支持jpg、jpeg、bmp、png格式2、像素不宜太低3、照片请勿反光、污损、模糊或梯度变形4、照片请勿强曝光、逆光、背光等5、照片人脸不要遮挡（头饰、头发等）、勿带口罩墨镜6、照片为生活照，大小建议在16-32KB以内(超出会进行压缩，耗时会增加)

Response

Body

{
    "msg": "处理成功",
    "code": "0",
    "data": {
        "respCode": "10",
        "respDesc": "身份证号与姓名匹配，照片系统判断为同一人",
        "hackScore": "977.20",
        "idnum": "330284444444442737"
    },
    "success": true,
    "timestamp": 1733215845484

证件类型说明：

01	身份证
02	军官证
03	护照
04	户口簿
05	士兵证
06	港澳来往内地通行证
07	台湾同胞来往内地通行证
08	临时身份证
09	外国人居留证
10	警官证
11	营业执照
12	组织商户代码证
13	税务登记证
14	统一社会信用代码证

respCode 说明

10	身份证号与姓名匹配，照片系统判断为同一人
11	身份证号与姓名匹配，照片不能确定是否为同一人
12	身份证号与姓名匹配，照片系统判断为不同人
13	身份证号与姓名不匹配
14	身份证号与姓名匹配，库中无照片
15	身份证号与姓名匹配，照片检测失败
99	其他错误

hackScore 说明

【0,600】	系统判断为不同人
【600,700】	不能确定是否为同一人
【700,1000】	系统判断为同一人

14.身份认证( 二要素)

Request

Method: POST
测试URL: http://120.226.208.2:8072/vertx/identify/check/twoFactor
正式URL: 联系客服
Headers：application/json;charset=utf-8
Body:

{
    "appId":"123",
    "timestamp":"123",
    "sign":"",
    "version":"",
    "signType":"",
    "name":"",
    "idnum":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
name	字符串	姓名，不参与签名	张三
idnum	字符串	证件号码，不参与签名	37**

Response

Body

{
    "msg": "处理成功",
    "code": "0",
    "data": {
        "respCode": "10",
        "respDesc": "身份证号与姓名匹配"
        "isCharge":"1"
    },
    "success": true,
    "timestamp": 1733215845484

respCode 说明

10	身份证号与姓名匹配
13	身份证号与姓名不匹配
16	未知
99	其他错误

isCharge 说明

1	计费
0	不计费

15.身份认证( 运营商三要素)

Request

Method: POST
旧接口地址：http://36.133.15.247:8072/vertx/identify/check/``threeFactor
新接口地址: https://fsgw.hnykxx.com/vertx/identify/check/``threeFactor
Headers：application/json;charset=utf-8
Body:

{
    "appId":"123",
    "timestamp":"123",
    "sign":"",
    "version":"",
    "signType":"",
    "name":"",
    "mobile":"",
    "idnum":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本	1
name	字符串	姓名，参与签名	张三
mobile	字符串	手机号，参与签名	138**
idnum	字符串	证件号码，参与签名	37**

Response

Body

{
    "code": "0",
    "msg": "处理成功",
    "success": true,
    "data": {
        "respCode": "10",
        "respDesc": null,
        "isCharge": "1"
    },
    "timestamp": 1753062608005
}

respCode 说明

10	一致
13	不一致
16	未知
99	其他错误

isCharge 说明

1	计费
0	不计费

16.申请模板

Request

地址： https:fsgw.0yk.co

Method: POST
URL: /vertx/sms/applyTemplate
Headers：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "name":"",
    "type":"",
    "templateContent":""
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳	到毫秒
sign	字符串	验签数据
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。
version	字符串	接口版本（固定为1）	1
name	字符串	模板名称
type	字符串	模板类型	1.精确模板 2.变量模板
templateContent	字符串	模板内容	当为2时，可以传入以下变量: 1.${QQ}2.${手机号}3.${任意字符串_X} X大写，默认时10，X可以修改成对应数字，如20，对应时20个字符的任务字符串，

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "msgId":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID

17.国际短信单条发送

Request

Method: POST
URL: /api/national/sms/send
Headers(ContentType)：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
    "phone":"",
    "content":"",
    "spMsgId":"",
    "extendNo":""
}

参数说明

参数名称	参数类型	参数说明	示例值	是否必填
appId	字符串	分配给客户的账号		是
timestamp	数字类型	时间戳	到毫秒	是
sign	字符串	验签数据		是
signType	字符串	签名方式(暂只支持MD5)	MD5(大小写均可)，验签与提交参数大小写对应。	是
version	字符串	接口版本（固定为1）	1	是
phone	字符串	发送号码		是
content	字符串	发送内容		是
spMsgId	字符串	客户平台唯一消息ID(匹配回执用)，可以不传，如传请带上唯一消息ID值。		否
extendNo	字符串	扩展码(纯数字),非必填，如传请带上纯数字值。		否

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "timestamp":123123123,
  "data": {
      "msgId":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
msgId	字符串	消息ID

二、查询接口(客户主动查询)

1.查询回执状态

Request

Method: POST
URL: /api/sms/queryStatus
Headers：application/json;charset=utf-8
Body:

 {
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳
sign	字符串	签名数据
signType	字符串	签名方式(暂只支持MD5)	验签与提交参数大小写对应。
version	字符串	接口版本

Response

Body

{
  "code": "0",
  "success": true,
  "msg": "OK",
  "data": [{
      "status":"",
      "phone":"",
      "feeCount":1,
      "deliveryMsg":"",
      "deliveryCode":"",
      "deliveryTime":"yyyy-MM-dd HH:mm:ss",
      "extendCode":"",
      "spMsgId":"",
      "msgId":""
  }]
}

响应说明

参数名称	参数类型	参数说明	示例值
status	字符串	状态	DELIVRD和UNDELIV
phone	字符串	手机号码
feeCount	数值	计费条数
deliveryMsg	字符串	回执消息
deliveryCode	字符串	回执错误码(UNDELIV的时候有)
deliveryTime	字符串	回执时间
extendCode	字符串	扩展码
spMsgId	字符串	客户消息ID
msgId	字符串	平台消息ID

2.查询上行消息

Request

Method: POST
URL: /api/sms/queryReply
Headers：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳
sign	字符串	签名数据
signType	字符串	签名方式(暂只支持MD5)	验签与提交参数大小写对应。
version	字符串	接口版本

Response

Body

 {
  "code": "0",
  "success": true,
  "msg": "OK",
  "data": [{
      "replyContent":"",
      "phone":"",
      "replyTime":"yyyy-MM-dd HH:mm:ss",
      "msgId":"",
      "spMsgId":"",
  }]
}

响应说明

参数名称	参数类型	参数说明
replyContent	字符串	回复内容
phone	字符串	手机号码
replyTime	字符串	回复时间
spMsgId	字符串	客户消息ID
msgId	字符串	平台户消息ID

3.查询短信余额

Request

Method: POST
URL: /api/sms/queryAmount
Headers：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳
sign	字符串	签名数据
signType	字符串	签名方式(暂只支持MD5)	验签与提交参数大小写对应。
version	字符串	接口版本

Response

Body

 {
  "code": "0",
  "success": true,
  "msg": "OK",
  "data": {
      "amount":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
amount	字符串	余额

4.查询号码检测余额

Request

Method: POST
URL: /api/phone/queryAmount
Headers：application/json;charset=utf-8
Body:

{
    "appId":"",
    "timestamp":"",
    "sign":"",
    "version":"",
    "signType":"",
}

参数说明

参数名称	参数类型	参数说明	示例值
appId	字符串	分配给客户的账号
timestamp	数字类型	时间戳
sign	字符串	签名数据
signType	字符串	签名方式(暂只支持MD5)	验签与提交参数大小写对应。
version	字符串	接口版本

Response

Body

 {
  "code": "0",
  "success": true,
  "msg": "OK",
  "data": {
      "amount":""
  }
}

响应说明

参数名称	参数类型	参数说明	示例值
amount	字符串	余额

三、通知接口(平台通知客户)

1.状态报告通知(内容支持模版定制)

Request

Method: POST
URL: 客户提供
Headers：application/json;charset=utf-8
Body:

[
    {
      "status":"",
      "phone":"",
      "feeCount":1,
      "deliveryMsg":"",
      "deliveryCode":"",
      "deliveryTime":"",
      "extendCode":"",
      "msgId":"",
      "spMsgId":"",
      "appId":""
    },
    {
      "status":"",
      "phone":"",
      "feeCount":1,
      "deliveryMsg":"",
      "deliveryCode":"",
      "deliveryTime":"",
      "extendCode":"",
      "msgId":"",
      "spMsgId":"",
      "appId":""
    }
]

参数说明

参数名称	参数类型	参数说明	示例值
status	字符串	状态	DELIVRD和UNDELIV
phone	字符串	手机号码
feeCount	数值	计费条数
deliveryMsg	字符串	回执消息
deliveryCode	字符串	回执错误码(UNDELIV的时候有)
deliveryTime	字符串	回执时间
extendCode	字符串	扩展码
spMsgId	字符串	客户消息ID
msgId	字符串	平台消息ID
appId	字符串	发送账号

Response

Body

{
  "status":"0"
}

响应说明

参数名称	参数类型	参数说明	示例值
status	字符串	状态	0

2.上行消息通知(内容支持模版定制)

Request

Method: POST
URL: 客户提供
Headers：application/json;charset=utf-8
Body:

{
  "replyContent":"",
  "phone":"",
  "replyTime":"",
  "msgId":"",
  "spMsgId":"",
  "appId"：""
}

参数说明

参数名称	参数类型	参数说明	示例值
replyContent	字符串	回复内容
phone	字符串	手机号码
replyTime	字符串	回复时间	yyyy-MM-dd HH:mm:ss
spMsgId	字符串	客户消息ID
msgId	字符串	平台户消息ID
appId	字符串	发送账号

Response

Body

 {
  "status": "0"
}

响应说明

参数名称	参数类型	参数说明
status	字符串	状态值

3.号码检测结果通知(内容支持模版定制)

Request

Method: POST
URL: 客户提供
Headers：application/json;charset=utf-8
Body:

{
    "batchNo": "387d628f7aa749c0a9bb9f1d418c9cc5",
    "resultList": [
        {
            "phone": "xxx",
            "type": 1
        },
        {
            "phone": "xxx",
            "type": 1
        }
    ]
}

参数说明

参数名称	参数类型	参数说明	示例值
batchNo	字符串	批次号
phone	字符串	手机号码
type	字符串	类型	实时检测-0.未知1.正常2.空号3.停机4.库无8.关机9.在网不可用10.通话中11.转移动12.转联通13.转电信14.转广电空号检测-1.正常2.空号4.库无5.沉默号6.风险号

Response

Body

{
  "status":"0"
}

响应说明

参数名称	参数类型	参数说明	示例值
status	字符串	状态	0

四、错误码描述

PK:1014	不支持分条短信
PK:1013	发送消息超时
PK:1012	Netty FUTURE 发送时监听返回失败
PK:1010	所有会话通道，都不写可状态
PK:1009	没有可用通道
PK:1008	连接过多
PK:1007	流量错误
PK:1006	错误的接入点，SOAP使用CMPP接入或相反
PK:1005	其它错误
PK:1004	版本错误
PK:1003	CMPP 鉴权错误
PK:1002	CMPP IP错误
PK:0042	转发提交超时
PK:0041	内容频繁发送限制
PK:0034	短信签名无效
PK:0033	地区拦截
PK:0030	直接产生拒绝报告
PK:0027	通道黑名单
PK:0026	分条发送，组包超时
PK:0025	不支持该短信
PK:0024	模版--内容未报备
PK:0023	客户黑名单
PK:0019	本地黑名单
PK:0018	业务状态错误(停用)
PK:0017	账户状态错误(停用)
PK:0016	号码频繁发送限制
PK:0015	号码格式错误手机号码格式可能小于或大于11位或不是三大运营商号码
PK:0014	非法的OP_ISDN号段
PK:0013	非法错误的包时序
PK:0012	防钓鱼
PK:0007	MQ发送失败
PK:0006	手动拒绝下发短信(审核)
PK:0004	未知错误
PK:0003	无法找到下级路由
PK:0002	内容非法(包括拦截关键字)
PK:0001	空号
PK:18	时段错误
PK:16	余额不足
PK:13	系统错误
PK:11	更新状态数据发生错误（请检查CMPP的企业ID是否填写）
PK:10	查询状态数据发生错误
PK:9	IP地址为非绑定的IP地址
PK:8	账号HTTP接口已停用
PK:7	spId或password错误
PK:6	请求超时或timestamp参数错误
PK:4	验签失败
PK:2	参数未正确填写
PK:1	HTTP请求输入数据JSON格式错误
PK:3	参数不能为空

运营商状态码

三大运营商常见状态码

五、示例代码

1.Java示例

package com.qmmj.test;

import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.*;

public class HttpDemo {
    // 接口地址
    public static final String API_URL = "http://192.168.2.100:8088/api/sms/send";  // TODO 替换接口地址
    // 请求账号
    public static final String APPID = "200186";  // TODO 替换成自己的账号
    // 请求账号密钥
    public static final String APP_KEY = "ac39a0def747476cb0ed18b8dfc50bc2";  // TODO 替换成自己的账号密钥
    // 签名类型
    public static final String SIGN_TYPE = "MD5";
    // 接口版本
    public static final String VERSION = "1";

    public static void main(String[] args) throws IOException {
        // 组装请求参数
        SortedMap<String, Object> requestMap = new TreeMap<>();
        requestMap.put("appId", APPID);
        requestMap.put("timestamp", System.currentTimeMillis());
        requestMap.put("version", VERSION);
        requestMap.put("signType", SIGN_TYPE);
        requestMap.put("phone", "18873130736");
        requestMap.put("content", "【封神云】测试123");
        requestMap.put("spMsgId", "");// 客户平台的消息ID, 可以不传递
        requestMap.put("extendNo", "");// 扩展码,可以不传递

        String sign = generateSign(requestMap);

        requestMap.put("sign", sign);

        // TODO 使用自己的方法, 将对象转为json字符串
        ObjectMapper mapper = new ObjectMapper();
        String requestJson = mapper.writeValueAsString(requestMap);

        System.out.println(sendJsonPost(requestJson));

    }

    /**
     * 生成签名
     *
     * @param requestMap   请求参数
     * @param removeFields 不参与签名的字段 (在接口文档上面声明了哪些参数不需要参与签名)
     * @return 签名信息
     */
    public static String generateSign(SortedMap<String, Object> requestMap, String... removeFields) {
        StringBuilder paramBuilder = new StringBuilder();
        List<String> removeList = Arrays.asList(removeFields);
        for (Map.Entry<String, Object> entry : requestMap.entrySet()) {
            if (removeList.contains(entry.getKey())) {
                continue;
            }

            String key = entry.getKey();
            Object value = entry.getValue();

            if (value == null || value.toString().isEmpty()) {
                continue;
            }

            paramBuilder.append(key).append("=").append(value).append("&");
        }
        paramBuilder.append("key=" + APP_KEY);

        System.out.println("待签字符串:" + paramBuilder.toString());

        return generateMD5(paramBuilder.toString()).toUpperCase();
    }

    /**
     * 获取32位, 16进制 UTF-8 编码 MD5字符串  TODO 可以使用自己系统的工具类
     *
     * @param input
     * @return
     */
    public static String generateMD5(String input) {
        try {
            // 获取MD5消息摘要实例
            MessageDigest md = MessageDigest.getInstance("MD5");

            // 计算MD5摘要
            byte[] messageDigest = md.digest(input.getBytes(StandardCharsets.UTF_8));

            // 将字节数组转换为16进制字符串
            StringBuilder hexString = new StringBuilder();
            for (byte b : messageDigest) {
                String hex = Integer.toHexString(0xff & b);
                if (hex.length() == 1) {
                    hexString.append('0');
                }
                hexString.append(hex);
            }

            return hexString.toString();

        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("MD5算法不可用", e);
        }
    }

    /**
     * 原生HTTP调用, 请替换成自己系统的组件  TODO 可以使用自己系统的工具类
     *
     * @param requestBody 请求对象的json字符串
     * @return
     * @throws IOException
     */
    public static String sendJsonPost(String requestBody) throws IOException {
        // 创建URL对象
        URL url = new URL(API_URL);

        // 打开连接
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        // 设置请求方法
        connection.setRequestMethod("POST");

        // 设置请求头
        connection.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
        connection.setRequestProperty("Accept", "application/json");

        // 允许输入输出流
        connection.setDoOutput(true);
        connection.setDoInput(true);

        // 写入JSON数据
        try (OutputStream os = connection.getOutputStream()) {
            byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
            os.write(input, 0, input.length);
        }

        // 获取响应状态码
        int responseCode = connection.getResponseCode();

        // 读取响应内容
        StringBuilder response = new StringBuilder();
        try (BufferedReader br = new BufferedReader(
                new InputStreamReader(
                        responseCode >= 400 ? connection.getErrorStream() : connection.getInputStream(),
                        StandardCharsets.UTF_8))) {
            String responseLine;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
        }

        // 关闭连接
        connection.disconnect();

        return response.toString();
    }
}

2.C#示例

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

public class SmsApiClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _appId;
    private readonly string _apiKey;

    public SmsApiClient(string baseUrl, string appId, string apiKey)
    {
        _httpClient = new HttpClient();
        _baseUrl = baseUrl.TrimEnd('/');
        _appId = appId;
        _apiKey = apiKey;
    }

    /// <summary>
    /// 发送短信
    /// </summary>
    /// <param name="phone">手机号码</param>
    /// <param name="content">短信内容</param>
    /// <param name="spMsgId">客户平台唯一消息ID（可选）</param>
    /// <param name="extendNo">扩展码（可选）</param>
    /// <returns>API响应结果</returns>
    public async void SendSmsAsync(string phone, string content, string spMsgId = "", string extendNo = "")
    {
        try
        {
            // 生成时间戳（毫秒）
            TimeSpan ts = DateTime.Now - new DateTime(1970, 1, 1, 0, 0, 0, 0);
            long timestamp = Convert.ToInt64(ts.TotalMilliseconds);

            // 构建请求参数
            var parameters = new Dictionary<string, object>
            {
                ["appId"] = _appId,
                ["timestamp"] = timestamp,
                ["version"] = "1",
                ["signType"] = "MD5",
                ["phone"] = phone,
                ["content"] = content
            };

            // 添加可选参数
            if (!string.IsNullOrEmpty(spMsgId))
                parameters["spMsgId"] = spMsgId;

            if (!string.IsNullOrEmpty(extendNo))
                parameters["extendNo"] = extendNo;

            // 生成签名
            string sign = GenerateSignature(parameters, _apiKey);
            parameters["sign"] = sign;

            // 构建请求体
            var requestBody = new
            {
                appId = _appId,
                timestamp = timestamp,
                sign = sign,
                version = "1",
                signType = "MD5",
                phone = phone,
                content = content,
                spMsgId = spMsgId,
                extendNo = extendNo
            };
            // 序列化为JSON
            string jsonContent = JsonConvert.SerializeObject(requestBody);

            // 发送HTTP请求
            StringContent httpContent = new StringContent(jsonContent, Encoding.UTF8, "application/json");
            HttpResponseMessage response = await _httpClient.PostAsync($"{_baseUrl}/api/sms/send", httpContent);
            response.EnsureSuccessStatusCode();
            // 返回响应内容
            string responseText = await response.Content.ReadAsStringAsync();
            Console.WriteLine("API响应:" + responseText);
        }
        catch (Exception ex)
        {
            throw new Exception($"发送短信失败: {ex.Message}", ex);
        }
    }

    /// <summary>
    /// 生成MD5签名
    /// </summary>
    /// <param name="parameters">参数字典</param>
    /// <param name="apiKey">API密钥</param>
    /// <returns>MD5签名</returns>
    private string GenerateSignature(Dictionary<string, object> parameters, string apiKey)
    {
        // 按ASCII码升序排序参数
        var sortedParams = parameters.OrderBy(kv => kv.Key, StringComparer.Ordinal).ToList();

        // 构建查询字符串
        var queryString = string.Join("&", sortedParams.Select(kv => $"{kv.Key}={kv.Value}"));

        // 拼接密钥
        var signString = $"{queryString}&key={apiKey}";

        // 生成MD5哈希并转为大写
        using (var md5 = MD5.Create())
        {
            byte[] inputBytes = Encoding.UTF8.GetBytes(signString);
            byte[] hashBytes = md5.ComputeHash(inputBytes);

            StringBuilder sb = new StringBuilder();
            for (int i = 0; i < hashBytes.Length; i++)
            {
                sb.Append(hashBytes[i].ToString("X2"));
            }
            return sb.ToString();
        }
    }
}



        private static void Main(string[] args)
        {
                // 配置API参数
                string baseUrl = "http://your-api-Url.com";  // 替换为实际的API域名
                string appId = "your_app_id";                    // 替换为您的AppId
                string apiKey = "your_api_key";                  // 替换为您的ApiKey

                // 创建SMS客户端
                var smsClient = new SmsApiClient(baseUrl, appId, apiKey);

                try
                {
                    // 发送短信
                    smsClient.SendSmsAsync(
                        phone: "13800138000",           // 目标手机号
                        content: "您的验证码是123456",    // 短信内容
                        spMsgId: "MSG_" + DateTime.Now.Ticks,  // 可选：唯一消息ID.可不带MSGID，发送会返回消息ID
                        extendNo: "001"                 // 可选：扩展码
                    );
                }
                catch (Exception ex)
                {
                    Console.WriteLine($"发送失败: {ex.Message}");
                }
        }