1、功能接口与使用方式

云信使平台的业务功能,以HTTPS协议(使用"HTTP+SSL"的HTTPS安全加密方式)作为承载方式提供给用户。云信使平台提供了约10项业务,约100个功能接口。用户系统只需以HTTPS方式向云信使服务器发送XML数据包即可实现功能调用。

云信使接口支持以POST方式提交数据(不支持GET方式)。为了方便无法使用HTTPS加密方式的用户,云信使接口亦提供无须加密的HTTP协议接口(不加密而使用明文传输,传输过程有被嗅探盗取的风险,不推荐使用)。

XML数据包使用简单的嵌套结构,如一个请求获取账户余额的XML数据包,其格式如下所示:
<xml>
   <ActionType>QueryBalance</ActionType>
   <UserName>YouUserName</UserName>
   <Token>YourEncryptPassword</Token>
</xml>

用户只需将该数据包发送到https://api.yunxinshi.com:8081/GlobalInterface.do接口地址,云信使系统立即响应查询余额请求,并以文本方式返回以下XML数据包:
<xml>
   <errcode>0</errcode>
   <errmsg>成功</errmsg>
   <Balance>0.1</Balance>
</xml>

用户系统拆分该XML数据包,即可获取当前余额(0.1元)。
某些功能接口的XML数据包,存在“必填参数”和“可选参数”,“可选参数"用于定义细化的功能和属性,用户在提交数据包时如果未携带“可选参数”,系统会自动采用默认参数,每项业务的开发文档都有参数的详细说明。

2、可用的接口地址列表

为达到高可用性的目标,云信使系统使用多DNS服务器、多运营商网络接入,多服务器负载均衡的方式提供服务,目前可用的服务器地址有:
主接口地址:https://api.yunxinshi.com:8081
备用接口地址:https://api.yunxinshi.net:8081
明文传输的接口地址:http://api.yunxinshi.com:8082
默认情况下使用主接口地址即可,如果需要使用不加密的HTTP方式,使用上述"明文传输的接口地址"即可(不推荐)。

3、回调消息介绍

回调消息有别于功能接口的调用。用户在调用功能接口后可以立即取得调用结果(结果包括:是否成功、序列号)。但对于某些业务而言,功能接口调用的返回结果只是一个任务提交成功与否的结果,服务器返回成功只说明服务器已经接受了这个任务,而对于这个任务而言,还存在将执行过程和执行结果反馈回用户系统的问题。

云信使系统使用“回调消息”机制来通知用户系统其所提交的任务在各个关键节点执行的消息。即用户系统提供给云信使系统一个回调消息地址(Web URL形式),云信使系统将XML格式的回调消息,POST到用户所提供的地址。以短信发送为例,该机制说明如下:
步骤(1):用户首先构造发送短信的XML数据包,提交到云信使服务器,云信使立即返回本次发送任务的提交结果和提交序列号。
步骤(2):云信使系统接受提交后,将短信提交到运营商网关开始发送。当该消息被手机用户成功接收后,云信使系统使用回调消息机制,将此次发送成功的状态报告通知用户系统。回调给用户系统的短信状态报告数据包格式如下所示:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>SMS</Business>
   <Event>Report</Event>
   <SN></SN>
   <Phone></Phone>
   <Status></Status>
   <SubmitTime></SubmitTime>
   <SendTime></SendTime>
   <ReceiveTime></ReceiveTime>
   <Time></Time>
</xml>

用户根据开发文档说明对该XML数据包进行拆解,即可获取本次短信发送的状态报告。

4、配置回调消息地址

用户使用回调消息机制来接收消息,必须先配置回调消息地址,如果回调消息地址为空,则云信使系统会自动丢弃需要回调的消息。用户登录业务管理系统后,通过“业务管理”-“回调消息地址配置”来配置地址。如下图所示:



每个业务的回调地址可以各自独立配置,也可以将所有业务配置成统一的地址,如果配置成统一的地址,则通过回调数据包中的Business标签内容来区分业务类型。

对于新注册的账号,系统提供了一个临时的地址(http://api.yunxinshi.com:8081/ReceiveEventDemo.do)用于接收回调消息,推送到这个地址的消息将临时保存到当天23:59:59,用户登录业务管理系统后,通过“接口调试工具”-“回调数据列表”可以查看这些数据。该地址仅用于开发调试,当用户投入正式生产环境后,需要根据实际情况更改为用户系统的地址。用户更改接收地址时,系统会自动检测接收地址是否有效,用户需要在接收地址页面中返回字符串0方能通过检测。

云信使系统向用户系统推送回调消息后,用户系统需要立即返回字符串0以表示该消息已被成功接收,如果云信使系统未接收到正确的返回,则重复推送该消息(每条消息不管推送几次,都有不变的PushSN序列号,用户可以根据该序列号来判断消息的重复性),相同的消息最多尝试推送3次,如果云信使系统推送三次仍未接收到正确的返回,则丢弃该消息。