一信通-接口规范3.5.0(江苏).doc

一信通平台能力接口规范 中国联通 ConfidentialPage 1 of 21 一信通平台能力接口规范 UMS Fundamental Service API Guide 中国联通 2013 04 08 一信通平台能力接口规范 中国联通 ConfidentialPage 2 of 21 目录目录 1 前言 4 1 1文档概述 4 1 2适用范围 4 1 3缩略词典 4 1 4注意事项 4 2 短信接口定义 5 2 1HTTP 接口 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 2WEB 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 一信通平台能力接口规范 中国联通 ConfidentialPage 3 of 21 2 3SOCKET接口 14 2 3 1通信方式 14 2 3 2消息定义 15 2 3 3常量定义 20 HISTORY 21 一信通平台能力接口规范 中国联通 ConfidentialPage 4 of 21 1 前言 1 1 文档概述 本规范主要讲了第三方应用系统接入一信通平台的协议要求 协议三大状态和协议指令的格 式和响应信息 1 2 适用范围 本规范描述一信通平台 以下简称 UMS 具体的接口协议 供第三方应用系统能够顺利接入 一信通短信网关 1 3 缩略词典 UMSUnified Message System APIApplication Programming Interface CPContent Provider MOMessage Original 消息上行 MTMessage Terminal 消息下行 SMSShort Message Service SPService Provider 1 4 注意事项 指企业使用业务时登录门户的地址 如 一信通平台能力接口规范 中国联通 ConfidentialPage 5 of 21 2 短信接口定义 测试帐户测试模板 您的验证码为测试帐户测试模板 您的验证码为 xxxxxxxx 发送示例 发送示例 您的验证码为您的验证码为 123456 HTTP 接口 采用 GB2312 编码 2 1 1 消息协议 接口地址 8899 sms Api 2 1 2 发送短信 功能描述 功能描述 短信发送 调用格式 调用格式 对 8899 sms Api Send do 进行 post 返回格式返回格式 result 000000000000000000010 000000000 000000000010 注 注 回执信息在接口收到后只保存 6 个小时 6 小时后将会清除 建议查询频次 1 分钟 接 口单次查询返回的回执条数为 1000 2 1 3 2 剩余短信条数查询 功能描述 功能描述 剩余短信条数查询接口 调用格式调用格式 对 8899 sms Api SearchNumber do 进行 post 返回格式返回格式 result 0 000000000000000000010 000000000000000000010 注 注 回执信息在接口收到后只保存 6 个小时 6 小时后将会清除 建议查询频次 1 分钟 接 口单次查询返回的回执条数为 1000 2 2 4 上行回复内容查询接口 功能描述 功能描述 上行回复内容查询 调用方式调用方式 利用 webservice 客户端进行 http 请求 reply 方法 返回格式返回格式 ReplyResponse ReplyRequest请求参数说明请求参数说明 类别类别参数名称参数名称类型类型说明说明 输入In0string企业编号 输入In1string用户名称 输入In2string用户密码 输入In3string保留 空值 一信通平台能力接口规范 中国联通 ConfidentialPage 12 of 21 ReplyResponse返回值返回值 类别类别参数名称参数名称类型类型说明说明 输出resultstring返回码 输出confirm timestring回复时间 格式 yyyy MM dd HH mm ss 输出replysreply 数组多个 relpy 对象组成 输出IdString最后一条回复信息的 ID 返回值返回值错误描述错误描述 0成功 1提交参数不能为空 2账号无效 3账号密码错误 20系统错误 reply 的属性值的属性值 类别类别参数名称参数名称类型类型说明说明 输出callMdnstring接入号 输出mdnstring用户手机号 输出messagestring回复内容 输出reply timestring回复时间 格式 yyyy MM dd HH mm ss 注 注 执行此接口必须以本次查询到的最后一条回复信息所对应的 ID 来同时执行 2 2 5 的中的 上行内容确认接口 否则您是无法查询到新的回复信息的 2 2 5 上行回复内容确认接口 功能描述 功能描述 上行回复内容查询 调用方式调用方式 利用 webservice 客户端进行 http 请求 replyConfirm 方法 返回格式返回格式 ReplyConfirmResponse ReplyConfirmRequest请求参数说明请求参数说明 类别类别参数名称参数名称类型类型说明说明 输入In0string企业编号 输入In1string用户名称 输入In2string用户密码 输入In3string保留 空值 输入In4string最后一条回复信息的 id ReplyConfirmResponse返回值返回值 一信通平台能力接口规范 中国联通 ConfidentialPage 13 of 21 类别类别参数名称参数名称类型类型说明说明 输出resultstring返回码 返回值返回值错误描述错误描述 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 通信过程 短信发送客户端与服务端之间发送的任何一条命令都带有一个序列号 序列号由命令源产生 客户端与服务器端通信开始以后 客户端可以向服务器端发送相应的命令 服务器端对收到 的命令返回应答 一信通平台能力接口规范 中国联通 ConfidentialPage 14 of 21 图 SP 和 SMG 的通信消息样例 SP 为客户端 图 SP 和 SMG 的通信消息样例 SMG 为客户端 命令在客户端和服务器之间的传输是采用类似接力的方式 每条命令和对应的应答仅仅表示 该次命令发送的结果是否正确 比如 客户端向某一个手机发送一条短消息 是通过向本地 服务器端发送一条 Submit 命令实现的 随后 客户端会从服务器端接收到一条 Submit Resp 应答 但是 即使应答表示 Submit 命令已正确接收 也不表示 Submit 命令内的短消息已经 发送到手机上了 而仅仅表示该短消息已经传送到服务器端 服务器端将会作下一步处理 或者发送给 SMSC 或者路由到另外的服务器端 最终由目的 SMSC 发送到手机上 这中间 任何一个环节出现错误 系统会终止信息的继续发送 并且通过向原客户端发送 Report 命令 告诉发送出错的原因 如果 SP 指定要求反馈的话 2 3 1 3 通信结束 如果客户端认为和服务器端的通信已结束 则客户端应该向服务器端发送 Unbind 命令 服务 器端随后返回 Unbind Resp 应答 然后双方断开连接 一信通平台能力接口规范 中国联通 ConfidentialPage 15 of 21 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 Length8Text消息的总长度 字节 Command ID8Text命令 ID Sequence Number16Text序列号 表 消息头的格式 一信通平台能力接口规范 中国联通 ConfidentialPage 16 of 21 2 3 2 1 3 消息体的格式 2 3 2 1 3 11Bind 操作 Bind 操作由 Bind 命令和 Bind Resp 应答组成 客户端首先发送 Bind 命令 服务器端收到 Bind 命令后 对命令发送方进行验证 然后返回 Bind Resp 应答 2 3 2 1 3 1 1Bind 命令的语法 字段字段长度 字节 长度 字节 类型类型说明说明 Sp Code6Text企业编码 Login Name16Text服务器端给客户端分配的登录名 Login Passowrd16Text服务器端和 Login Name 对应的密码 Reserve8Text保留 扩展用 表 Bind 消息格式 2 3 2 1 3 2Bind Resp 应答的语法 字段字段长度 字节 长度 字节 类型类型说明说明 Result2TextBind 执行命令是否成功 0 执行成功 其它 错误码 Reserve8Text保留 扩展用 表 Bind Resp 消息格式 2 3 2 1 4 Unbind 操作 Unbind 操作由 Unbind 命令和 Unbind Resp 应答组成 通信连接建立以后 客户端如果要停 止通信 需要发送 Unbind 命令 服务器端收到 Unbind 命令后 向客户端发送 Unbind Resp 相应 然后双方断开连接 2 3 2 1 4 1Unbind 命令的语法 Unbind 命令没有消息体 2 3 2 1 4 2Unbind Resp 应答的语法 Unbind Resp 应答没有消息体 一信通平台能力接口规范 中国联通 ConfidentialPage 17 of 21 2 3 2 1 5 Submit 操作 发送短信 在 submit 操作是由发送短信方向我们发送消息 我们做服务器端 对方做客户端 2 3 2 1 5 1Submit 命令的语法 字段字段长度 字节 长度 字节 类型类型说明说明 UserCount3Text接收短消息的手机数量 取值范围 1 至 100 UserNumber21Text接收该短消息的手机号 ScheduleTime14Text短消息定时发送的时间 如果为空 表示立刻发送该短 消息 时间内容为 14 个字符 格式为 yyyymmddhhmmss 即默认系统为北京时间 MessageCoding1Text短消息的编码格式 0 纯 ASCII 字符串 1 GBK 编码 2 utf 8 编码 MessageLength8Text短消息的长度 MessageContentMessage LengthText短消息的内容 Reserve8Text保留 扩展用 表 Submit 消息格式 2 3 2 1 5 2Submit Resp 应答的语法 字段字段长度 字节 长度 字节 类型类型说明说明 Result2TextSubmit 命令是否成功接收 0 接收成功 其它 错误码 Reserve8Text保留 扩展用 表 Submit Resp 消息格式 2 3 2 1 6 Deliver 操作 上行回复 Deliver 操作是由我们向发送短信的一方传送手机用户的上行消息 即我们做客户端 发送短 信方做服务器端 2 3 2 1 6 1Deliver 命令的语法 字段字段长度 字节 长度 字节 类型类型说明说明 UserNumber21Text发送短消息的用户手机号 一信通平台能力接口规范 中国联通 ConfidentialPage 18 of 21 MessageCoding1Text短消息的编码格式 短消息的编码格式 0 纯 ASCII 字符串 1 GBK 编码 2 utf 8 编码 MessageLength8Text短消息的长度 MessageContentMessage LengthText短消息的内容 Reserve8Text保留 扩展用 表 Deliver 消息格式 2 3 2 1 6 2 Deliver Resp 应答的语法 字段字段长度 字节 长度 字节 类型类型说明说明 Result2TextDeliver 命令是否成功接收 0 接收成功 其它 错误码 Reserve8Text保留 扩展用 表 Del iver Resp 消息格式 2 3 2 1 7 Report 操作 状态报告 Report 操作是由我们向发送短信的一方传送手机用户的状态报告 即我们做客户端 发送短 信方做服务器端 2 3 2 1 7 1Report 命令的语法 字段字段长度 字节 长度 字节 类型类型说明说明 SubmitSequenceNumber16Text 该命令所涉及的 Submit 或 deliver 命令的序列号 UserNumber21Text 接收短消息的手机号 State1Text 该命令所涉及的短消息的当前执行状态 0 发送成功 1 等待发送 2 发送失败 ErrorCode2Text 当 State 2 时为错误码值 否则为 0 Reserve8Text 保留 扩展用 表 Report 消息格式 2 3 2 1 7 2Report Resp 应答的语法 字段字段长度 字节 长度 字节 类型类型说明说明 一信通平台能力接口规范 中国联通 ConfidentialPage 19 of 21 Result2TextReport 命令是否成功接收 0 接收成功 其它 错误码 Reserve8Text保留 扩展用 表 Report Resp 消息格式 2 3 2 1 8 Active 操作 链路检查 本操作仅适用通信双方用长连接方式时保持连接 因此无消息体 2 3 2 1 8 1Active Resp 应答的语法 字段字段长度 字节 长度 字节 类型类型说明说明 Reserve1Text 表 Active Resp 消息格式 2 3 3 常量定义 2 3 3 1 消息 ID 定义 消息消息 IDID 名称名称消息消息 IDID 取值取值 BIND00000001 BIND RESP80000001 UNBIND00000002 UNBIND RESP80000002 SUBMIT00000003 SUBMIT RESP80000003 DELIVER00000004 DELIVER RESP80000004 REPORT00000005 REPO