行业移动平台组件接口设计说明书.doc

移动平台组件接口设计说明书移动平台接口设计说明书1. 概述1.1. 文档概述本文档描述了短信平台与第三方it系统交互的短信接口。1.2. 术语定义和缩略语缩写词英文解析中文解析crmcustomer relationship managerment客户资源管理erpenterprise resource planning企业资源规划ftpfile transfer protocol文件传输协议gprsgeneral packet radio service通用无线分组业务httphypertext transfer protocol超文本传输协议httpssecure http加密的http协议soapsimple object access protocol简单对象访问协议oaoffice automation办公自动化2. 接口说明2.1. 短消息接口2.1.1. 接口说明第三方it系统通过此接口收发短消息。webservice方式通信收到第三方it系统的发送请求后，通过短信平台中的sms通信协议模块发送sms；当从sms通信协议模块收到sms后，通过此接口将短消息发送给第三方it系统。2.1.2. 流程说明短消息接口包括发送和接收两个流程。图1-1 短消息发送流程示意图发送短信由第三方it系统发起，通过sendsms操作实现。在提交短信发送请求之后，第三方it系统可以主动获取短信发送状态（getsmsdeliverystatus操作），或由短信平台调用接口通知第三方it系统发送状态（notifysmsdeliverystatus操作）。图1-2 短消息接收流程示意图接收短信可以通过两种方式，一种是由第三方it系统发起（getreceivedsms操作），然后短信平台将所接收到的短信发往该第三方it系统；第二种是由第三方it系统提前注册接口，然后短信平台调用接口(notifysmsreceptions)通知第三方it系统接有上行短信(无特殊要求目前采用第一种方式)2.1.3. 数据类型定义. 短信实体(smsmessage)定义1、 message：短信正文（string）2、 receivedaddress：接收方地址（string）3、 sendaddress：发送方地址（string）4、 messageformat:编码格式(int)5、 channelid:通道编号. 短信发送状态(deliverystatus)定义枚举值参数描述0delivered发送成功。1waitingfordelivery等待发送。2waitingfordeliverystatus已发送,等待状态报告。3deliveryfailed发送失败。. 短信发送状态实体(deliveryinformation)定义1、 deliverystatus：发送状态（deliverystatus）2、 receivedaddress：接收方地址（string）3、statuscode：状态码，如果发送失败可确定错误原因（string）2.1.4. 短信发送接口. 调用方式：接口接口定义发起方落地方说明发送短信sendsms第三方it系统短信平台发送文件sendfile第三方it系统短信平台发送之前文件必须通过ftp 上传到短信平台上,文件可重复使用.发送点点通文件sendppfile第三方it系统短信平台发送之前文件必须通过ftp 上传到短信平台上,文件可重复使用.获取发送状态getsmsdeliverystatus第三方it系统短信平台通知发送状态notifysmsdeliverystatus短信平台第三方it系统第三方it系统必须提前注册对应的接口. 接口定义.1. 发送短信接口(sendsms)发起方：第三方it系统落地方：短信平台string sendsms(string operatorid,string password,string destinationaddresses, string message,string wappushurl,int messageformat,int sendmethod,string extendcode,bool deliveryresultrequest,string channelid)备注： .1.1. 请求参数定义参数类型可选性描述operatoridxsd:stringm操作员idpasswordxsd:stringm操作员密码destinationaddressesxsd:string m短消息要被发送到的地址。多个号码以”,”隔开。extendcodexsd:stringo内部扩展号码。messagexsd:stringm在短消息中发送的文本。为十六进制字符串wappushurlxsd:stringo发送wappush地址,当messageformat=15，sendmethod=3时有效messageformatxsd:intm消息编码类型。0:ascii4:binary8:ucs215:含gb汉字sendmethodxsd:intm发送消息选项。0:普通短信1:闪电短信2:长短信3:wap pushdeliveryresultrequestxsd:booleano指示是否需要网络侧返回递交状态报告。true表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。channelidxsd:string0短信通道id,由短信平台指定,如果有多个短信通道,第三方it系统可以指定使用某个短信通道.1.2. 返回值定义1、 成功则返回此次发送信息的唯一标识符，用于用户查询发送状态。2、 如果调用失败,则返回错误代码.2. 发送文件接口(sendfile)发起方：第三方it系统落地方：短信平台 string sendfile(string operatorid,string password,string filename, string message,string wappushurl,int messageformat,int sendmethod,string extendcode,bool deliveryresultrequest,string channelid).2.1. 请求参数定义参数类型可选性描述operatoridxsd:stringm操作员idpasswordxsd:stringm操作员密码filenamexsd:string m号码文件名。通过ftp 上传到短信平台上,文件可重复使用.上传文件须是每行为一个手机号码的txt文件extendcodexsd:stringo内部扩展号码。messagexsd:stringm在短消息中发送的文本。十六进制字符串标示wappushurlxsd:stringo发送wappush地址,当messageformat=15，sendmethod=3时有效messageformatxsd:intm消息编码类型。0:ascii4:binary8:ucs215:含gb汉字sendmethodxsd:intm发送消息选项。0:普通短信1:闪电短信2:长短信3:wap pushdeliveryresultrequestxsd:booleano指示是否需要网络侧返回递交状态报告。true表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。channelidxsd:string0短信通道id,由短信平台指定,如果有多个短信通道,第三方it系统可以指定使用某个短信通道.2.2. 返回值定义1、 成功则返回此次发送信息的唯一标识符，用于用户查询发送状态2、 如果调用失败,则返回错误代码.3. 发送点点通文件接口发起方：第三方it系统落地方：短信平台string sendppfile(string operatorid,string password,string filename,string wappushurl,int messageformat,int sendmethod,string extendcode,bool deliveryresultrequest,string channelid).3.1. 请求参数定义参数类型可选性描述operatoridxsd:stringm操作员idpasswordxsd:stringm操作员密码filenamexsd:string m号码文件名。通过ftp 上传到短信平台上,文件可重复使用.上传文件的类型必须是txt文本文件、excel文件和csv文件。文本文件每行格式为:手机号码 短信内容;csv文件每行格式为:手机号码,短信内容;excel文件每行的格式为:第一列是手机号码 第二列是短信内容。extendcodexsd:stringo内部扩展号码。messageformatxsd:intm消息编码类型。0:ascii4:binary8:ucs215:含gb汉字sendmethodxsd:intm发送消息选项。0:普通短信1:闪电短信2:长短信3:wap pushdeliveryresultrequestxsd:booleano指示是否需要网络侧返回递交状态报告。true表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。channelidxsd:string0短信通道id,由短信平台指定,如果有多个短信通道,第三方it系统可以指定使用某个短信通道.3.2. 返回值定义1、 成功则返回此次发送信息的唯一标识符，用于用户查询发送状态2、 如果调用失败,则返回错误代码.4. 查询短信发送状态接口(getsmsdeliverystatus)发起方：第三方it系统落地方：短信平台deliveryinformation getsmsdeliverystatus(string operatorid,string password, string requestidentifier);.4.1. 请求参数定义参数类型可选性描述operatoridxsd:stringm操作员idpasswordxsd:stringm操作员密码requestidentifierxsd:stringm发送短信时,由短信平台分配的请求标示.4.2. 返回值定义1、 返回发送状态列表。（类型：deliveryinformation数组）.5. 短信发送状态通知接口(notifysmsdeliverystatus)发起方：短信平台平台落地方：第三方it系统限制条件：第三方it系统必须注册接口void notifysmsdeliverystatus(string requestidentifier,deliveryinformation deliverystatus);.5.1. 请求参数定义参数类型可选性描述requestidentifierxsd:stringm标识一个短消息发送请求。deliveryinformationdeliveryinformationm短消息递交状态参数。.5.2. 返回值定义1、 无返回值2.1.5. 短信接收接口. 调用方式：接口接口定义发起方落地方说明接收短信getreceived第三方it系统短信平台上行短信通知notifysmsreception短信平台第三方it系统第三方it系统必须提前注册对应接口. 接口定义.1. 接收短信接口（getreceived）发起方：第三方it系统落地方：短信平台smsmessage getreceived(string operatorid,string password, string extcode, string channelid);.1.1. 请求参数定义参数类型可选性描述operatoridxsd:stringm操作员idpasswordxsd:stringm操作员密码extcodexsd:stringo扩展码channelidxsd:string0短信通道i