省集中平台与业务应用系统接口规范.doc

云南省电信翼机通集中平台与应用子系统接入方案和接口规范说明书 v2.0云南省电信公司云南省通信产业服务有限公司2012-05-07一、接入方案1.1 消费系统接入方案离线消费系统升级成省集中管理模式，用户侧可部署一台前置机，并在前置机上安装一个前置应用程序（伺服器），用户通过统一登录接口登录到省平台，省平台再转到各相应的子应用系统进行应用管理。子系统应用集中服务器通信前置机消费机消费机VPDNLAN根据上图，数据从消费机端通过用户局域网传输数据到通信前置机。根据以往经验，使用五类或超五类非屏蔽网线过长（一般超过100米）时，会产生丢包现象，为时数据正确，在通信前置机采集消费机数据时需要尽量保证数据的正确和完整。1.2 联网考勤系统和会议签到接入方案联网考勤应用采用白名单与黑名单方式进行。可实现联网跨地域考勤。考勤系统不需要前置机作为数据传输中介。考勤通过EVDO/1X无线或ADSL/LAN有线方式直接连接到翼机通考勤子系统上传考勤数据。子系统应用集中服务器考勤机1X/EVDO/ADSL/LAN1.3 门禁系统接入方案门禁系统不使用省集中管理模式。省翼机通集中平台服务器通信前置机VPDN(1X/EVDO/ADSL/LAN)LAN门禁主控二、统一登录接口2.1 接口定义企业进入子系统由统一登录界面提供登录方法。统一登录界面由省集中平台提供。用户进入 http:/222.221.*.*或指定登录域名进入统一登录界面。用户名 密 码 验证码 YY8M登录注：登录过程均需要有日志记录，失败错误页面跳转省翼机通平台错误页面。在登录完毕之后，将出现统一管理界面，由菜单和框架组成。具体的应用功能由子系统提供。中国电信云南省翼机通平台首页|企业设置|应用子系统|帮助消费子系统机具参数卡片设置消费流水表消费统计表Copyright2011 China Telecom All Rights Reserved.欢迎使用中国电信翼机通平台，本平台以提供翼机通应用业务。翼机通，其主要是利用手机RF-UIM卡 （射频手机卡）实现门禁系统、车库管理、考勤系统、消费系统等各项应用。手机门禁功能是指，通过对手机用户配置密码和权限，手机用户可持手机刷卡开门。欢迎 admin使用本系统其菜单也由统一界面提供，如下：首页首页系统信息退出企业设置企业管理部门管理人事管理应用子系统消费子系统考勤子系统门禁子系统短信子系统帮助帮助主题关于在用户点击应用子系统后，将使用FrameSet框架为子系统提供嵌入式管理界面。提供地址和参数为如下。模版http:/iphost:port/SubLogin.jsp?u=username&f=function&k=keypass参数说明名称说明数据类型长度iphost厂商子系统的IP地址string20port厂商子系统端口string5username登录用户名string20function子系统功能，用于区别同厂家的不同应用。1: 消费 2: 考勤 3: 门禁 4: 会议签到 5: 彩门。string2keypass算法：MD5(password+yyyyMMdd+ipaddress)其中：password: MD5加密后的用户密码。yyyyMMdd: 日期，格式：年月日，例：20120427。ipaddress: 用户的IP地址。string32三、系统接口规范3.1 接口综述通过公网或VPDN接入远程网络，数据发送到服务器，接入方式有VPDN/EVDO/1X/ADSL/LAN等。由于EVDO和1X稳定性与信号有关，丢包率尚难控制，因此建议在有有线网络的情况下，尽量采用ADSL/LAN的接入方式；在无有线网络的情况下，优先采用EVDO无线上网的形式，最后考虑1X上线模式。子应用系统采用主动模式和被动模式，向省平台获取数据（平台信息、人员信息、部门信息、卡片信息、机具信息等），并上传数据至省集中平台。可参考下列示意图：下发数据/上传数据省平台同步接口子应用系统同步程序同步接口Web Servicce同步程序访问省翼机通平台所有接口采用Web Service标准接口。接口分为：消费子系统省翼机通集中共享平台（简称省平台）、考勤子系统省平台、短信子系统省平台。各个部分均需要进行数据交换，以提供正常的应用数据。接口均为双向接口，省平台和子系统均提供，原则上谁拥有原始数据，就由谁主动传数据，被动方也可主动向拥有数据一方请求数据。由于省平台接口采用动态webservice技术,不是单独针对某子应用系统进行开发,子应用系统接口必须满足以下几点1. 接收方面的接口命名空间唯一2. 参数大小写,包结构严格按照下文提供的XML格式进行传输3. 采用soap协议4. 省平台提供的接口,通用入参在供应商子应用系统接入平台时生成,是子应用系统主动与平台通信的唯一标识与依据3.2 接口协议本接口采用WEBSERVICE协议来实时进行数据传递。采用相应的实体作为入参与出参。3.3 服务接口列表服务服务名称说明校企信息同步EntSync校企信息同步，省平台管理所有校企信息数据，校企信息由省平台根据用户订购的应用，下发到各应用子平台；应用子平台也可主动向省平台拉数据。校企群信息同步EntGroupSync校企群信息同步，校企群仅用于联网考勤，校企群可理解成一个集团公司下有多个分公司，校企群就是集团公司的概念。省平台管理所有校企群信息数据，校企群信息由省平台下发到各子平台；子平台也可主动向省平台拉数据。人员信息同步EmployeeSync人员信息同步，省平台管理所有人员信息数据，人员信息由省平台下发到各应用子平台；应用子平台也可主动向省平台拉数据。卡片信息同步CardSync卡片信息同步，省平台管理所有卡片信息数据，卡片信息由省平台下发到各应用子平台；应用子平台也可主动向省平台拉数据。机具信息同步TermInfoSync机具信息同步，省平台管理所有机具信息数据，机具信息由省平台下发到各应用子平台；应用子平台也可主动向省平台拉数据。机具状态信息同步TermStateUpdate机具状态信息同步，各子平台可实时获得机具的状态信息，再传到省平台。校企群注销EntGrounpUnbind校企群注销,校企群业在省平台中注销后，省平台将信息下发到各子平台，子平台将也可主动向省平台拉数据。校企注销EntUnbind校企注销, 校企在CRM中注销后，省平台将信息下发到各子平台，子平台将也可主动向省平台拉数据。用户状态变更EmployeeStateChange当用户的状态发生变更时，省平台或子平台应主动的把数据下发或上传到各平台，以保持数据的同步。按业务规范用户状态有：0：未发卡，1.正常，2.挂失，3. 注销。 企业应用同步EntAppSync企业订购的应用同步，省平台把企业订购的应用下发到各子平台，各子平台开通和注销相应的应用。用户补卡信息同步EmployeeChangeCard用户补（换）卡时，省平台把用户的旧卡号和新卡号下发到各子平台，子平台注销旧卡号，把新卡关联到用户。消费流水同步ConsumeSync消费流水账的数据同步用户实时消费余额查询EmployeeConsumeQuery用户实时消费余额查询，省平台从子平台请求获得用户的实时的消费余额。考勤流水同步AttendSync考勤流水账的数据同步会议签到流水同步AttendCheckSync会议签到流水账的数据同步短信发送服务SendSMS省平台提供统一的短信发送接口，各子平台通过该接口发送C网短信。3.4 接口定义3.4.1校企信息同步 服务名Public EntSyncResponseInfo EntSync (EntInfos ) throws RemoteException; /子平台提供，入参和返回参数见下文描述。Public EntSyncResponseInfo EntSync (通用入参) throws RemoteException;/省平台提供，返回参数Entinfos，入参为通用入参，通用入参见接口协议说明。 接口入参 子平台服务入参名称传输XML格式EntInfos ? ? ? ? ? ? 省平台入参appKeys ? ? 入参参数说明子平台服务入参说明节点名称数据类型长度说明EntInfos校企集，一个校企集下可有多个校企，表示为： EntInfo校企节点,校企表示为： enterpriseIDstring10校企编号groupIDstring10校企群编号，见EntGroup类型。可空enterpriseNamestring200校企名称adminUsernamestring20校企用户登录帐号adminPasswordstring20校企用户登录密码（MD5）statestring1状态 1: 正常 2: 注销 省平台入参数说明参见3.5 通用入参 输出参数 子系统返回值名称XML格式EntSyncResponseInfo 省平台返回值名称传输XML格式EntInfos ? ? ? ? ? ? 输出参数说明子系统返回参数说明节点名称数据类型长度说明ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述EntInfo失败信息列表省平台返回参数说明节点名称数据类型长度说明EntInfos校企集，一个校企集下可有多个校企，表示为： EntInfo校企节点,校企表示为： enterpriseIDstring10校企编号groupIDstring10校企群编号，见EntGroup类型。可空enterpriseNamestring200校企名称adminUsernamestring20校企用户登录帐号adminPasswordstring20校企用户登录密码（MD5）statestring1状态 1: 正常 2: 注销 ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述3.4.2校企群信息同步 服务名如接入方式为非联网,则无此接口Public EntGroupSyncResponseInfo EntGroupSync (EntGroupInfos) throws RemoteException; /子平台提供，入参和返回参数见下文描述。Public EntGroupSyncResponseInfo EntGroupSync (通用入参) throws RemoteException; /省平台提供，返回参数EntGroupInfos，入参为通用入参，通用入参见接口协议说明。 接口入参 子平台服务入参名称XML格式EntGroupInfos ? ? ? ? ? 省平台入参appKeys ? ? 入参参数说明子平台入参说明节点名称类型长度说明EntGroupInfos校企群集节点, 一个校企群集下可有多个校企群EntGroupInfo校企群节点groupIDstring10校企群编号groupNamestring200校企群名称（总部），例：“一心堂总部”adminUsernamestring20校企群用户登录帐号adminPasswordstring20校企群用户登录密码（MD5）statestring1状态 1: 正常 2: 注销 省平台入参数说明参见3.5 通用入参 输出参数子系统返回值。名称XML格式EntGroupSyncResponseInfo 省平台返回值名称XML格式EntGroupInfos ? ? ? ? ? 输出参数说明子平台返回参数说明节点名称数据类型长度说明ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述EntGroupInfostring失败的ID列表省平台返回参数说明节点名称类型长度说明EntGroupInfos校企群集节点, 一个校企群集下可有多个校企群EntGroupInfo校企群节点groupIDstring10校企群编号groupNamestring200校企群名称（总部），例：“一心堂总部”adminUsernamestring20校企群用户登录帐号adminPasswordstring20校企群用户登录密码（MD5）statestring1状态 1: 正常 2: 注销 ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述3.4.3人员信息同步 服务名Public EmployeeSyncResponseInfo EmployeeSync (Employees) throws RemoteException;/ 子平台提供，入参和返回参数见下文描述。Public EmployeeSyncResponseInfo EmployeeSync (通用入参) throws RemoteException;/ 省平台提供，返回参数Employees，入参为通用入参，通用入参见接口协议说明。 接口入参 子平台服务入参名称XML格式Employees ? ? ? ? ? 省平台入参appKeys ? ? 入参参数说明子平台入参说明节点名称类型长度说明Employees人员集节点, 一个人员集下可有多个人员信息子节点Employee人员信息节点employeeIDstring10人员编号employeeNamestring20人员姓名companyIDstring10所属校企编号currentCardIDstring20当前卡片号码statestring人员状态 0:正常 1:注销省平台入参数说明参见3.5 通用入参 输出参数子平台返回值。名称XML格式EmployeeSyncResponseInfo 省平台返回值名称XML格式Employees ? ? ? ? ? 输出参数说明子平台返回参数说明节点名称数据类型长度说明ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）Emplyee失败的ID列表ResponseMessagestring250返回信息描述省平台返回参数说明节点名称类型长度说明Employees人员集节点, 一个人员集下可有多个人员信息子节点Employee人员信息节点employeeIDstring10人员编号employeeNamestring20人员姓名companyIDstring10所属校企编号currentCardIDstring20当前卡片号码statestring人员状态 0:正常 1:注销ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述3.4.4卡片信息同步 服务名Public CardSyncResponseInfo CardSync (Cards) throws RemoteException; / 子平台提供，入参和返回参数见下文描述。Public CardSyncResponseInfo CardSync (通用入参) throws RemoteException; / 省平台提供，返回参数Cards，入参为通用入参，通用入参见接口协议说明。 接口入参 子平台服务入参名称XML格式Cards ? ? ? ? ? ? ? 省平台入参appKeys ? ? 入参参数说明子平台入参说明节点名称数据类型长度说明Cards卡集节点, 一个卡集下可有多个卡信息子节点Card卡信息子节点cardIDstring10卡片编号（非卡号）RFIDstring20RFID卡号（物理卡号）ICCIDstring25UIM卡卡号employeeIDstring10卡片所属用户编号，见Employee类型。MDNstring20用户电话号码cardTypestring1卡片类型0: M1卡片1: 单纯的非接触式CPU卡片2: 13.56M卡3: 2.4G卡片4:贴片卡cardStatestring1卡片状态0: 未发卡 1: 正常2: 挂失 4: 已被注销并补卡5:已被换卡 6:锁定7:注销 8:用户停机9:欠费停机省平台入参数说明参见3.5 通用入参 输出参数子平台返回值。名称XML格式CardSyncResponseInfo省平台返回值名称XML格式Cards ? ? ? ? ? ? ? 输出参数说明子平台输出参数说明节点名称数据类型长度说明ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述Card失败结果ID列表省平台输出参数说明节点名称数据类型长度说明Cards卡集节点, 一个卡集下可有多个卡信息子节点Card卡信息子节点cardIDstring10卡片编号（非卡号）RFIDstring20RFID卡号（物理卡号）ICCIDstring25UIM卡卡号employeeIDstring10卡片所属用户编号，见Employee类型。MDNstring20用户电话号码cardTypestring1卡片类型0: M1卡片1: 单纯的非接触式CPU卡片2: 13.56M卡3: 2.4G卡片4:贴片卡cardStatestring1卡片状态0: 未发卡 1: 正常2: 挂失 4: 已被注销并补卡5:已被换卡 6:锁定7:注销 8:用户停机9:欠费停机ResponseCodestring10响应码（响应码见3.5 ResponseCode响应码说明）ResponseMessagestring250返回信息描述3.4.5机具信息同步 服务名Public TermInfoSyncResponseInfo TermInfoSync (TermInfos) throws RemoteException;/ 子平台提供，入参和返回参数见下文描述。Public TermInfoSyncResponseInfo TermInfoSync (通用入参) throws RemoteException;/ 省平台提供，返回参数TermInfos，入参为通用入参，通用入参见接口协议说明。 接口入参 子平台服务入参名称XML格式TermInfos ? ? ? ? ? ? ? ? 省平台入参appKeys ? ? 入参参数说明子平台入参说明节点名称数据类型长度说明TermInfos机具集节点, 一个机具集下可有多个机具信息子节点TermInfo机具信息子节点termIDstring10机具编号termNamestring20机具名称termTypestring1机具类型0: 消费机 1: 补助机 2: 充值机 3: 考勤机 4: 门禁机CompanyIDstring10机具所属校企编号，见EntInfo类型termStatestring1机具状态1: 正常2: 拆机startUseTimestring12机具启用时间，格式：2012-01-01IPAddressstring20机具IP地址，若是自动分配保留空。格式：01PASSstring50机具内置密钥种子下发。省平台入参数说明参见3.5 通用入参 输出参数子系统