一信通接口规范江苏样本.doc

一信通平台能力接口规范
UMS Fundamental Service API Guide

中华人民共和国联通
-04-08
目录
1. 前言 4
1.1 文档概述 4
1.2 合用范畴 4
1.3 缩略词典 4
1.4 注意事项 4
2. 短信接口定义 5
2.1 HTTP接口 5
2.1.1 消息合同 5
2.1.2 发送短信 5
2.1.3 回执接口 7
2.1.4 剩余短信条数查询 7
2.1.5 上行回答内容查询接口 8
2.1.6 上行回答内容确认接口 9
2.2 Web Service接口 9
2.2.1 消息合同 9
2.2.2 发送短信 9
2.2.3 回执接口 11
2.2.4 上行回答内容查询接口 11
2.2.5 上行回答内容确认接口 12
2.2.6 内容审核 13
2.3 Socket接口 14
2.3.1 通信方式 14
2.3.2 消息定义 15
2.3.3 常量定义 20
HISTORY 21

1. 前言
1.1 文档概述
本规范重要讲了第三方应用系统接入一信通平台合同规定，合同三大状态和合同指令格式和响应信息。
1.2 合用范畴
本规范描述一信通平台（如下简称UMS）详细接口合同，供第三方应用系统可以顺利接入一信通短信网关。
1.3 缩略词典
UMS Unified Message System
API Application Programming Interface
CP Content Provider
MO Message Original 消息上行
MT Message Terminal消息下行
SMS Short Message Service
SP Service Provider
1.4 注意事项
指公司使用业务时登录门户地址，如

2. 短信接口定义
测试帐户测试模板：您验证码为{xxxxxxxx}
发送示例： 您验证码为123456

2
2.1 HTTP接口
采用GB2312编码
2.1.1 消息合同
接口地址： :8899/sms/Api/

2.1.2 发送短信
功能描述：短信发送
调用格式：对 :8899/sms/Api/Send.do进行post
返回格式：result=&description=错误描述&faillist=失败号码列表

POST参数阐明：
类别
参数名称
类型
阐明
输入
SpCode
string
公司编号
输入
LoginName
string
顾客名称
输入
Password
string
顾客密码
输入
MessageContent
string
短信内容，最大1000个字符（短信内容规定编码为gb2312或gbk）
输入
UserNumber
string
手机号码(各种号码用”,”分隔)，最多1000个号码
输入
SerialNumber
string
流水号，20位数字，唯一 （规则自定义,建议时间格式精准到毫秒）
输入
ScheduleTime
string
预约发送时间，格式:yyyyMMddhhmmss,如‘01’，及时发送请填空（预约时间要写当前时间5分钟之后时间，若预约时间少于5分钟，则即时发送）
输入
ExtendAccessNum
string
接入号扩展号（默认不填，扩展号为数字，扩展位数由当前所配接入号长度决定，整个接入号最长20位）
输入
f
string
提交时检测方式
1 --- 提交号码中有效号码仍正常发出短信，无效号码在返回参数faillist中列出

不为1 或该参数不存在 --- 提交号码中只要有无效号码，那么所有号码都不发出短信，所有号码在返回参数faillist中列出

GET：:8899/sms/Api/Send.do?SpCode=000001
&LoginName=admin&Password=admin&MessageContent=短信内容&UserNumber=&SerialNumber=&ScheduleTime=&f=1

返回值：
返回值
错误描述
0
发送短信成功
1
提交参数不能为空
2
账号无效或权限局限性
3
账号密码错误,
4
预约发送时间格式不对的，应为yyyyMMddHHmmss
5
IP不合法,
6
号码中具有无效号码或不在规定号段或为免打扰号码
7
非法核心字
8
内容长度超过上限，最大402字符
9
接受号码过多，最大1000
10
黑名单顾客
11
提交速度太快
12
您尚未订购[普通短信业务]，暂不能发送该类信息
13
您[普通短信业务]剩余数量发送局限性，暂不能发送该类信息
14
流水号格式不对的
15
流水号重复
16
超过发送上限（操作员帐户当天发送上限）
17
余额局限性
18
扣费不成功
20
系统错误
21
密码错误次数达到5次
24
帐户状态不正常
25
账户权限局限性
26
需要人工审核
28
发送内容与模板不符
29
扩展号太长或不是数字&accnum=
32
同一号码相似内容发送次数太多
实际返回内容为“result=&description=错误描述&faillist=失败号码列表”

2.1.3 回执接口
2.1.3.1 HTTP接口
功能描述：公司方通过调用http回执接口获取短信回执信息。
调用格式： :8899/sms/Api/report.do

post参数阐明：
类别
参数名称
类型
阐明
输入
SpCode
string
公司编号
输入
LoginName
string
顾客名称
输入
Password
string
顾客密码

返回成果参数阐明：
类别
参数名称
类型
阐明
输入
out
string
回执成果，每条回执按分号隔开，每个字段按逗号隔开，每条回执共包括3个字段，第1个字段为流水号，第2个字段为被发送手机号码，第3个字段为回执成果，0表达到功，其她值表达失败

实际返回内容为“00000001,,0;00000001,,0;00000001,,0;”
注：回执信息在接口收到后只保存6个小时，6小时后将会清除，建议查询频次1分钟，接口单次查询返回回执条数为1000.

2.1.3.2剩余短信条数查询
功能描述：剩余短信条数查询接口
调用格式： 对:8899/sms/Api/SearchNumber.do进行post
返回格式：result=0&description=剩余条数(涉及套内和可超发条数)&number=条数

post参数阐明：
类别
参数名称
类型
阐明
输入
SpCode
string
公司编号
输入
LoginName
string
顾客名称
输入
Password
string
顾客密码

返回值:
返回值
错误描述
0
查询剩余条数成功
1
提交参数不能为空
2
账号无效,
3
账号密码错误,
5
IP不合法,
20
系统错误

2.1.4 上行回答内容查询接口
功能描述：短信上行回答查询
调用格式：对 :8899/sms/Api/reply.do进行post
POST参数阐明：
类别
参数名称
类型
阐明
输入
SpCode
string
公司编号
输入
LoginName
string
顾客名称
输入
Password
string
顾客密码

返回值
错误描述
0
成功
1
提交参数不能为空
2
账号无效,
3
账号密码错误,
20
系统错误

reply属性值:
类别
参数名称
类型
阐明
输出
mdn
string
手机号码
输出
callmdn

接入号
输出
content
string
回答内容
输出
reply_time
string
回答时间，格式yyyy-MM-dd HH:mm:ss
输出
id
string
回答id编号
:8899/sms/Api/reply.do?SpCode=000001&LoginName=admin&Password=admin
注：执行此接口必要以本次查询到最后一条回答信息所相应ID来同步执行2.1.5中上行内容确认接口，否则您是无法查询到新回答信息。

2.1.5 上行回答内容确认接口
功能描述：短信上行回答查询
调用格式：对 :8899/sms/Api/ replyConfirm.do进行post
POST参数阐明：
类别
参数名称
类型
阐明
输入
SpCode
string
公司编号
输入
LoginName
string
顾客名称
输入
Password
string
顾客密码
输入
id
string
上次查询返回最后一条回答id号

返回值
错误描述
0
成功
1
提交参数不能为空
2
账号无效,
3
账号密码错误,
20
系统错误
:8899/sms/Api/replyConfirm.do?SpCode=000001&LoginName=admin&Password=admin&id=211128

2.2 Web Service接口
2.2.1 消息合同
接口地址：:8899/sms_hb/services/Sms?wsdl
2.2.2 发送短信
功能描述：短信发送
调用格式： 运用Web Service客户端进行HTTP祈求SMS办法

返回格式：SmsResponse

SmsRequest祈求参数阐明：
类别
参数名称
类型
阐明
输入
In0
string
公司编号
输入
In1
string
顾客名称
输入
In2
string
顾客密码
输入
In3
string
短信内容，最大402个字符
输入
In4
string
手机号码(各种号码用”,”分隔)，最多1000个号码
输入
In5
string
流水号，20位数字，唯一 （规则自定义,建议时间格式精准到毫秒）
输入
In6
string
预约发送时间，格式:yyyyMMddhhmmss,如‘01’， 及时发送请填空
输入
In7
string
提交时检测方式
1 --- 提交号码中有效号码仍正常发出短信，无效号码在返回参数faillist中列出
不为1 或该参数不存在 --- 提交号码中只要有无效号码，那么所有号码都不发出短信，所有号码在返回参数faillist中列出
输入
In8
string
保存（空值）
输入
In9
string
接入号扩展号（默认不填，扩展号为数字，扩展位数由当前所配接入号长度决定，整个接入号最长20位）
输入
In10
string
保存（空值）

SmsResponse返回值:
返回值
错误描述
0
发送短信成功
1
提交参数不能为空
2
账号无效或未开户
3
账号密码错误,
4
预约发送时间格式不对的，应为yyyyMMddHHmmss
5
IP不合法,
6
号码中具有无效号码或不在规定号段,
7
非法核心字
8
内容长度超过上限，最大402字符
9
接受号码过多，最大1000

11
提交速度太快
12
您尚未订购[普通短信业务]，暂不能发送该类信息
13
您[普通短信业务]剩余数量发送局限性，暂不能发送该类信息
14
流水号格式不对的
15
流水号重复
16
超过发送上限（操作员帐户当天发送上限）
17
余额局限性
18
扣费不成功
20
发送失败
24
账户状态不正常
25
账户权限局限性
26
需要人工审核
28
发送内容与模板不符
29
扩展号太长或不是数字&accnum=
32
同一号码相似内容发送次数太多

实际返回内容为“result=0&description=发送成功&faillist=”

2.2.3 回执接口
功能描述：短信回执
调用方式：运用Web Service客户端进行HTTP祈求report办法
返回格式：ReportResponse
ReportRequest祈求参数阐明：
类别
参数名称
类型
阐明
输入
In0
string
公司编号
输入
In1
string
顾客名称
输入
In2
string
顾客密码

ReportResponse返回值:
类别
参数名称
类型
阐明
输入
out
string
回执成果，每条回执按分号隔开，每个字段按逗号隔开，每条回执共包括3个字段，第1个字段为流水号，第2个字段为被发送手机号码，第3个字段为回执成果，0表达到功，其她值表达失败

实际返回内容为“00000001,,0；00000001,,0;00000001,,0;”
注：回执信息在接口收到后只保存6个小时，6小时后将会清除，建议查询频次1分钟，接口单次查询返回回执条数为1000.

2.2.4 上行回答内容查询接口
功能描述：上行回答内容查询
调用方式：运用webservice客户端进行http祈求reply办法
返回格式：ReplyResponse
ReplyRequest祈求参数阐明：
类别
参数名称
类型
阐明
输入
In0
string
公司编号
输入
In1
string
顾客名称
输入
In2
string
顾客密码
输入
In3
string
保存（空值）

ReplyResponse返回值:
类别
参数名称
类型
阐明
输出
result
string
返回码
输出
confirm_time
string
回答时间，格式yyyy-MM-dd HH:mm:ss
输出
replys
reply数组
各种relpy对象构成
输出
Id
String
最后一条回答信息ID

返回值
错误描述
0
成功
1
提交参数不能为空
2
账号无效,
3
账号密码错误,
20
系统错误

reply属性值:
类别
参数名称
类型
阐明
输出
callMdn
string
接入号
输出
mdn
string
顾客手机号
输出
message
string
回答内容
输出
reply_time
string
回答时间，格式yyyy-MM-dd HH:mm:ss

注：执行此接口必要以本次查询到最后一条回答信息所相应ID来同步执行2.2.5中上行内容确认接口，否则您是无法查询到新回答信息。

2.2.5 上行回答内容确认接口
功能描述：上行回答内容查询
调用方式：运用webservice客户端进行http祈求replyConfirm办法
返回格式：ReplyConfirmResponse
ReplyConfirmRequest祈求参数阐明：
类别
参数名称
类型
阐明
输入
In0
string
公司编号
输入
In1
string
顾客名称
输入
In2
string
顾客密码
输入
In3
string
保存（空值）
输入
In4
string
最后一条回答信息id

ReplyConfirmResponse返回值:
类别
参数名称
类型
阐明
输出
result
string
返回码

返回值
错误描述
0
成功
1
提交参数不能为空
2
账号无效,
3
账号密码错误,
4
时间格式不对的,格式为：yyyy-MM-dd HH:mm:ss
20
系统错误

2.3 Socket接口
2.3.1 通信方式
SP和SMG之间通信由客户端向服务器端发起连接。连接建立后来，由客户端向服务器端发送命令，服务器端必要对接受到每一条命令返回一条应答消息。SP和SMG互为客户端和服务器端。
2.3.1.1 通信初始化
客户端有命令要向服务器端发送时，由客户端一方面通过Bind命令向服务器端发起连接。服务器端依照Bind命令之中登录名和密码，对客户端合法性进行验证，然后返回一条Bind_Resp应答给客户端。如果验证通过，则客户端和服务器端通信开始，否则中断连接。
2.3.1.2 通信过程
短信发送客户端与服务端之间发送任何一条命令都带有一种序列号，序列号由命令源产生。
客户端与服务器端通信开始后来，客户端可以向服务器端发送相应命令，服务器端对收到命令返回应答。

图 SP和SMG通信消息样例(SP为客户端)

图 SP和SMG通信消息样例(SMG为客户端)

命令在客户端和服务器之间传播是采用类似接力方式，每条命令和相应应答仅仅表达该次命令发送成果与否对的。例如，客户端向某一种手机发送一条短消息，是通过向本地服务器端发送一条Submit命令实现，随后，客户端会从服务器端接受到一条Submit_Resp应答。但是，虽然应答表达Submit命令已对的接受，也不表达Submit命令内短消息已经发送到手机上了，而仅仅表达该短消息已经传送到服务器端，服务器端将会作下一步解决，或者发送给SMSC，或者路由到此外服务器端，最后由目SMSC发送到手机上。这中间任何一种环节浮现错误，系统会终结信息继续发送，并且通过向原客户端发送Report命令告诉发送出错因素(如果SP指定规定反馈话)。
2.3.1.3 通信结束
如果客户端以为和服务器端通信已结束，则客户端应当向服务器端发送Unbind命令，服务器端随后返回Unbind_Resp应答，然后双方断开连接。
2.3.1.4 接口地址
:18888

2.3.2 消息定义
系统中消息分二种：基于TCP/IP消息和鉴权消息，系统中每个消息包最大不超过2K字节。
2.3.2.1 基于基于TCP/IP消息定义
专用SGIP合同中定义消息由消息头和消息体构成。
项目
阐明
消息头
消息头某些
消息体
消息体某些
表 消息构成
2.3.2.1.1 数据类型
消息中运用到如下数据类型
类型
阐明
Integer
无符号整数
Text
定长字符串，左对齐存储，空余位置补’\0’
表 消息数据类型

消息中所有Integer类型字段均采用网络字节顺序。所有消息中序列号字段均占12个字节，分为3个4字节整数；通信传播时每个整数都使用网络字节顺序，但整多顺序并不变化。也就是说，通信传播时候，序列号字段应当按照三个持续4字节整数来解决。
2.3.2.1.2 消息头格式
字段
长度（字节）
类型
阐明
Message Length
8
Text
消息总长度(字节)
Command ID
8
Text
命令ID
Sequence Number
16
Text
序列号
表 消息头格式
2.3.2.1.3 消息体格式
2.3.2.1.3.1 1Bind操作
Bind操作由Bind命令和Bind_Resp应答构成。客户端一方面发送Bind命令，服务器端收到Bind命令后，对命令发送方进行验证，然后返回Bind_Resp应答。
2.3.2.1.3.1.1 Bind命令语法
字段
长度（字节）
类型
阐明
Sp Code
6
Text
公司编码
Login Name
16
Text
服务器端给客户端分派登录名
Login Passowrd
16
Text
服务器端和Login Name相应密码
Reserve
8
Text
保存，扩展用
表 Bind消息格式
2.3.2.1.3.2 Bind_Resp应答语法
字段
长度（字节）
类型
阐明
Result
2
Text
Bind执行命令与否成功。
0：执行成功
其他：错误码
Reserve
8
Text
保存，扩展用
表 Bind_Resp消息格式
2.3.2.1.4 Unbind操作
Unbind操作由Unbind命令和Unbind_Resp应答构成。通信连接建立后来，客户端如果要停止通信，需要发送Unbind命令；服务器端收到Unbind命令后，向客户端发送Unbind_Resp相应，然后双方断开连接。
2.3.2.1.4.1 Unbind命令语法
Unbind命令没有消息体
2.3.2.1.4.2 Unbind_Resp应答语法
Unbind_Resp应答没有消息体。
2.3.2.1.5 Submit操作(发送短信)
在submit操作是由发送短信方向咱们发送消息，咱们做服务器端，对方做客户端。
2.3.2.1.5.1 Submit命令语法
字段
长度（字节）
类型
阐明
UserCount
3
Text
接受短消息手机数量，取值范畴1至100
UserNumber
21
Text
接受该短消息手机号
…
…
…
…
ScheduleTime
14
Text
短消息定期发送时间，如果为空，表达立即发送该短消息。时间内容为14个字符，格式为“yyyymmddhhmmss” ，即默认系统为北京时间
MessageCoding
1
Text
短消息编码格式。
0：纯ASCII字符串
1：GBK编码
2：utf-8编码
MessageLength
8
Text
短消息长度
MessageContent
Message Length
Text
短消息内容
Reserve
8
Text
保存，扩展用
表 Submit消息格式
2.3.2.1.5.2 Submit_Resp应答语法
字段
长度（字节）
类型
阐明
Result
2
Text
Submit命令与否成功接受。
0：接受成功
其他：错误码
Reserve
8
Text
保存，扩展用
表 Submit_Resp消息格式
2.3.2.1.6 Deliver操作(上行回答)
Deliver操作是由咱们向发送短信一方传送手机顾客上行消息，即咱们做客户端，发送短信方做服务器端。
2.3.2.1.6.1 Deliver命令语法
字段
长度（字节）
类型
阐明
UserNumber
21
Text
发送短消息顾客手机号
MessageCoding
1
Text
短消息编码格式。
短消息编码格式。
0：纯ASCII字符串
1：GBK编码
2：utf-8编码
MessageLength
8
Text
短消息长度
MessageContent
Message Length
Text
短消息内容
Reserve
8
Text
保存，扩展用
表 Deliver消息格式
2.3.2.1.6.2 Deliver_Resp应答语法
字段
长度（字节）
类型
阐明
Result
2
Text
Deliver命令与否成功接受。
0：接受成功
其他：错误码
Reserve
8
Text
保存，扩展用
表 Del.iver_Resp消息格式
2.3.2.1.7 Report操作(状态报告)
Report操作是由咱们向发送短信一方传送手机顾客状态报告，即咱们做客户端，发送短信方做服务器端。
2.3.2.1.7.1 Report命令语法
字段
长度（字节）
类型
阐明
SubmitSequenceNumber
16
Text
该命令所涉及Submit或deliver命令序列号
UserNumber
21
Text
接受短消息手机号
State
1
Text
该命令所涉及短消息当前执行状态
0：发送成功
1：等待发送
2：发送失败
ErrorCode
2
Text
当State=2时为错误码值，否则为0
Reserve
8
Text
保存，扩展用
表 Report消息格式
2.3.2.1.7.2 Report_Resp应答语法
字段
长度（字节）
类型
阐明
Result
2
Text
Report命令与否成功接受。
0：接受成功
其他：错误码
Reserve
8
Text
保存，扩展用
表 Report_Resp消息格式
2.3.2.1.8 Active操作(链路检查)
本操作仅合用通信双方用长连接方式时保持连接，因而无消息体。
2.3.2.1.8.1 Active_Resp应答语法
字段
长度（字节）
类型
阐明
Reserve
1
Text

表 Active_Resp消息格式
2.3.3 常量定义
2.3.3.1 消息ID定义
消息ID名称
消息ID取值
BIND
00000001
BIND_RESP
80000001
UNBIND
00000002
UNBIND_RESP
80000002
SUBMIT
00000003
SUBMIT_RESP
80000003
DELIVER
00000004
DELIVER_RESP
80000004
REPORT
00000005
REPORT_RESP
80000005
ACTIVE
00000006
ACTIVE_RESP
80000006

2.3.3.2 错误码定义
返回值
错误描述
0
发送短信成功
1
提交参数不能为空
2
账号无效或未开户
3
账号密码错误,
4
预约发送时间格式不对的，应为yyyyMMddHHmmss
5
IP不合法,
6
号码中具有无效号码或不在规定号段,
7
非法核心字
8
内容长度超过上限，最大402字符
9
接受号码过多，最大1000

11
提交速度太快
12
您尚未订购[普通短信业务]，暂不能发送该类信息
13
您[普通短信业务]剩余数量发送局限性，暂不能发送该类信息
14
流水号格式不对的
15
流水号重复
16
超过发送上限（操作员帐户当天发送上限）
17
余额局限性
18
扣费不成功
20
发送失败
24
账户状态不正常
25
账户权限局限性
26
需要人工审核
28
发送内容与模板不符
29
扩展号太长或不是数字&accnum=
32
同一号码相似内容发送次数太多

Report 状态与短消息状态映射
Report状态
短消息状态
0，发送成功
DELIVERED
1，等待发送
ENROUTE，ACCEPTED
2，发送失败
EXPIRED，DELETED，UNDELIVERABLE，UNKNOWN，REJECTED

HISTORY
Rev_1.0 /03/15
No.
Version
Date
Author
Review
Change Information
1
3.4.0
/03/15
Hong Haijun
Julius Wong