06苏州移动中小企业信息化平台接口规范 v16.doc

苏州移动中小企业信息化平台接口规范版本履历版本号.修订日期修订人审核人修改内容V1.52009-10-27罗海平V1.62009-10-29宋凯1. 增加了参数 ParamMap。 增加只有针对特殊产品才传入OrderCode的参数2. 删除了原2.3.6 ISV业务健康检查章节3. 增加新的章节 【产品业务期限查询接口】V1.612009-11-26冯宇梁1. 1.企业业务受理接口（ISV10101）增加只有针对特殊产品才传入OrderCode的参数目 录1General Summary（总体规范）21.1.技术方案21.2.接口协议21.2.1.基本协议21.2.2.消息格式21.3.消息安全性31.3.1.数据安全31.3.2.加密算法41.3.3.密钥处理41.3.4.网络安全52Interface Specification（接口描述）52.1SaaS接口概述52.2SaaS管理平台提供ISV应用系统接口(ISV应用系统SaaS管理平台)72.2.1SSO鉴权接口72.2.2SSO心跳接口102.2.3客户端登录接口112.2.4产品访问鉴权接口132.2.5企业信息接口152.2.6企业员工信息接口172.2.7企业部门信息接口202.2.8企业通讯录信息接口232.2.9ISV消息通知接口252.3ISV应用系统提供SaaS管理平台接口(SaaS管理平台ISV应用系统)272.3.1企业客户业务受理接口272.3.2企业客户员工业务受理接口312.3.3角色列表同步（读取）接口342.3.4用户角色权限同步（读取）接口362.3.5用户角色权限同步（更新）接口382.3.6产品业务期限查询接口40附录一：PDU通用HEAD（消息头）1附录二：数据类型1附录三：消息类型1附录四：算法说明5附录五：接口WSDL6General Summary（总体规范）1.1. 技术方案本系统对外集成通信接口采用WebService技术作为SaaS平台与外部各系统之间的主要通信接口。1.2. 接口协议1.2.1. 基本协议双方的消息交互采用SOAP（Simple Object Access Protocol，简单对象访问协议）协议。1.2.2. 消息格式所有的协议数据单元PDU(Protocol Data Unit)由如下表的消息头和消息体组成： PDU组成描述Message Head消息头Message Body消息体完整的消息格式如下例所示：消息头属性一消息头属性二消息头属性三加密后的消息体其中未加密的消息体格式，如下例所示：消息体属性一消息体属性二消息体属性三1.3. 消息安全性1.3.1. 数据安全采用DES算法对数据进行加密。DES加密只针对消息体，对消息头不加密。不同的ISV应用系统采用不同的密钥对本系统向SaaS管理平台发送的消息进行加密。各个ISV应用系统的密钥由SaaS平台管理员在SaaS管理平台上设定新密钥的启用时间，SaaS系统自动生成新密钥；密钥生成后，SaaS平台管理员通过线下的方式给到ISV应用系统，ISV应用系统进行配置。SaaS和ISV应用系统在新密钥启用时间到来时同时启用新的密钥。SaaS管理平台接收到ISV应用系统的消息后，根据消息头中的AppID获取对应ISV应用系统的密钥后，即可对消息体进行解密。SaaS管理平台向ISV应用系统发送消息时，根据该应用系统对应的密钥对消息体进行加密。ISV应用系统接收到SaaS管理平台发送的消息后可直接采用自身的密钥对消息体解密。：对于特殊情况，ISV也可以选择不加密消息，直接传送明文。1.3.2. 加密算法具体消息体的加密算法为：Base64(DES(MD5(消息体) + 消息体)1.3.3. 密钥处理对于Key,做如下处理：n Key与IV一致n Key的长度为64bitn Key的格式为：ODD(MD5(Key)u 对Key进行MD5 hashu 对hash值取奇数位子串经过上述处理的Key，再对消息体进行加密或解密。 算法示例: public static string DESEncrypt(string data, string key) if(String.IsNullOrEmpty(data) | string.IsNullOrEmpty(key)throw new ArgumentNullException(The params cannt be null.);DES des = DES.Create();MD5 md5Hasher = MD5.Create();byte keyHashBytes = md5Hasher.ComputeHash(Encoding.UTF8.GetBytes(key);byte keyBytes = ArrayUtil.GetOddArray(keyHashBytes);byte ivBytes = ArrayUtil.GetOddArray(keyHashBytes);/IV is same as KeyMemoryStream memoryStream = new MemoryStream();CryptoStream cryptoStream = new CryptoStream(memoryStream, des.CreateEncryptor(keyBytes, ivBytes), CryptoStreamMode.Write);StreamWriter writer = new StreamWriter(cryptoStream);writer.Write(data);writer.Flush();cryptoStream.FlushFinalBlock();writer.Flush();return Convert.ToBase64String(memoryStream.GetBuffer(),0,(int)memoryStream.Length); 1.3.4. 网络安全SaaS管理平台接口采用如下的手段保证和ISV应用系统之间通信的网络安全：IP鉴权及业务应用ID控制列表。1. ISV应用系统接入SaaS管理平台时需提供其业务系统出访IP和URL（根据其业务特性确定）2. SaaS管理平台为ISV应用系统的每一个业务分配一个全局唯一的业务应用ID3. SaaS管理平台侧防火墙配置安全策略，只有有效的IP和业务应用ID才能访问SaaS管理平台4. ISV应用系统端配置相应策略，以拒绝非SaaS管理平台的接口调用Interface Specification（接口描述）1.1 SaaS接口概述SaaS接口提供两个webmethod的webservice供ISV调用：ResponseInfo SaaSISVInterface(RequestInfo req)和String SaaSISVInterfaceXMLString(String strXML)，两个方法的功能一样，只是参数和返回类型不同。ISV可以选择使用其中的一个方法来调用接口，具体的功能和返回信息由消息头的操作码：操作码决定，也就是说接口调用只有一个入口。反之，ISV提供给SaaS调用的接口也一样，只有一个入口，两个方法为：ResponseInfo ISVSaaSInterface(RequestInfo req)和String ISVSaaSInterfaceXMLString(String strXML)。：1.如果是非dotnet的应用请尽量实现字符串方法，以减少信息对象在不同平台之间转换带来的风险。2.ISV实现接口时方法名称必须和本文档描述的一致（ISVSaaSInterface 和ISVSaaSInterfaceXMLString）。另外，平台还支持URL（网页）方式的接口，ISV可以直接向该一个URL地址POST数据，在返回流（Response）中就是满足接口规范接口的返回信息。具体的Request信息格式为：Msg“XML文件的字符串”，Response的格式就是本规范中描述的返回消息格式。SaaS和ISV的应用系统可以看做是接口的两个相关人。他们各自需要提供接口供对方消费。SaaS管理平应提供如下接口供ISV调用：l SSO鉴权接口l SSO心跳接口l 客户端登录接口l 产品访问鉴权接口l 企业信息接口l 企业员工信息接口l 企业部门信息接口l 企业通讯录信息接口l ISV消息通知接口ISV应用系统应提供如下接口供SaaS调用：l 企业客户业务受理接口l 企业客户员工业务受理接口l 角色列表同步（读取）接口l 用户角色权限同步（读取）接口l 用户角色权限同步（更新）接口1.2 SaaS管理平台提供ISV应用系统接口(ISV应用系统SaaS管理平台)1.2.1 SSO鉴权接口 接口描述用户使用ISV应用系统之前，首先需要登录SaaS管理平台。登录成功后，SaaS管理平台为用户生成平台访问身份认证Token（令牌）。用户在访问平台中各ISV应用系统时，各ISV应用系统将通过本接口对访问者进行统一的Token认证。以便对用户进行统一的SSO鉴权认证。 交互流程1 用户先登录SaaS平台, 再从SaaS平台提供的入口访问ISV应用a) 用户输入帐号和密码登录到SaaS管理平台，SaaS管理平台为用户产生Token。b) 用户通过平台ISV产品链接或直接登录ISV应用系统，访问ISV应用系统。c) ISV应用系统将用户Token发送到平台进行鉴权。d) SaaS管理平台将鉴权结果结果信息返回ISV应用系统。2 用户直接访问ISV的应用系统a) 用户直接访问ISV应用系统。b) ISV应用系统发现用户没有登录，将页面导向到SaaS平台的登录页面。c) 用户输入帐号和密码登录到SaaS管理平台，SaaS管理平台为用户产生Token。d) 用户通过平台ISV产品链接或直接登录ISV应用系统，访问ISV应用系统。e) ISV应用系统将用户Token发送到平台进行鉴权。f) SaaS管理平台将鉴权结果结果信息返回ISV应用系统。 应用场景1 用户先登录SaaS平台,再从SaaS平台提供的入口访问ISV的应用系统2 用户直接访问ISV的应用系统 接口定义消息类型编码SYS10101请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式应用提供商编号应用（产品）编号令牌名称说明数据类型长度（字节）ISVID应用提供商编号String16AppID应用（产品）编号String16Token令牌（可转换为Guid的串）String36返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述企业客户编号用户ID用户类型名称说明数据类型长度（字节）ResultCode返回结果代码（0: 有效Token；1: 无效Token）String16ResultDesc返回结果文字描述String256CorpID企业客户编号String16UserID用户ID（可转换成Guid类型）String36UserType用户类型：(1: 企业管理员；0:企业普通用户)String11.2.2 SSO心跳接口 接口描述为实现用户的单点登录，SaaS管理平台必须能够感知到用户当前是否处于存活状态。用户登录到ISV应用系统以后，SaaS管理平台无法确定用户是否在线，默认情况下，一定时间（如30分钟）后，SaaS管理平台将会自动杀死用户的进程。所以ISV应用系统必须定时调用该接口通知SaaS管理平台更新用户的存活期，以保证用户的Token在用户由ISV应用系统中返回到SaaS管理平台后仍然有效，可以继续访问其他ISV应用系统的功能。 交互流程1 用户登录到ISV应用系统通过SaaS管理平台统一鉴权。2 ISV应用系统定时（30分钟内）间隔一段时间后向SaaS管理平台发送心跳请求。3 SaaS管理平台刷新用户Token存活期为初始值（如30分钟）。4 SaaS管理平台发送心跳响应结果到ISV应用系统（如Token不存在或刷新失败等。） 应用场景 接口定义消息类型编码SYS10102请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式令牌名称说明数据类型长度（字节）Token令牌（可转换为Guid的字符串）String36返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述名称说明数据类型长度（字节）ResultCode返回结果代码（0:成功；1:失败）String16ResultDesc返回结果文字描述String2561.2.3 客户端登录接口我们的服务器和他们服务器的接口 接口描述ISV的智能客户端可以通过本接口进行客户端登录鉴权。v 对于ISV的B/S架构应用应统一使用SaaS平台集成验证进行登录鉴权。v 由于是C/S结构,可能会影响其余B/S应用的SSO登录体验 交互流程1 用户在客户端输入用户名及密码。2 ISV客户端将用户名，密码及其他系统配置信息通过接口发送到ISV服务端3 ISV服务端通过Web Service调用SaaS平台的登录鉴权接口4 SaaS平台服务端将登录验证结果发回ISV服务端5 ISV服务端将登录验证结果发回至客户端 应用场景 接口定义消息类型编码SYS10201请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式应用提供商编号 应用系统编号用户名密码名称说明数据类型长度（字节）ISVID应用提供商编号String16AppID应用系统编号String16Username用户名String64Password密码String64返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述令牌名称说明数据类型长度（字节）ResultCode返回结果代码(0: 有效用户帐号；1: 无效帐号或密码)String16ResultDesc返回结果文字描述String256Token令牌(可转换为Guid的字符串)String361.2.4 产品访问鉴权接口 接口描述在用户访问某一个ISV产品应用时，ISV可以通过调用本接口，对用户所在公司是否对产品具有访问权限（用户所在公司是否已订购相应产品）进行强制验证，从而保证用户对产品访问的安全检测。v 此接口需配合SSO鉴权接口一起使用。 交互流程1 用户访问某一个ISV应用产品。2 ISV应用将登录鉴权时获得的用户Token及AppID发送至服务端。3 SaaS应用平台服务端验证用户对产品的访问资格。4 SaaS平台服务端将验证结果发送回客户端。 应用场景 接口定义消息类型编码SYS10202请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式令牌应用ID名称说明数据类型长度（字节）Token令牌(可转换为Guid的串)String36AppID应用(产品)编号String16返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述名称说明数据类型长度（字节）ResultCode返回结果代码（0: 有产品权限；1: 无产品权限）String16ResultDesc返回结果描述String2561.2.5 企业信息接口 接口描述对于需要企业信息的ISV应用，则实现该接口，以接受企业信息更新。 交互流程1 管理员在平台中更新企业信息。2 ISV定期（按需）从SaaS平台获取最新的企业信息。3 SaaS平台将最新的企业信息返回至ISV。4 ISV应用系统更新本地数据系统。 应用场景 接口定义消息类型编码SYS10301请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式企业客户编号名称说明数据类型长度（字节）CorpID企业客户编号String16返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述企业客户编号企业客户名称企业客户简称企业客户英文名称企业客户英文简称企业FQDN企业营业执照号企业法人企业管理员联系电话企业管理员联系手机企业管理员联系邮件企业地址企业邮寄地址 邮编企业电话传真号码邮箱地址企业WEB网址企业LogoURL 变更时间名称说明数据类型长度（字节）ResultCode返回结果代码(0: 处理成功；1: 处理失败)String16ResultDesc返回结果描述String256CorpID企业客户编号String16CorpName企业客户名称String64ShortName企业客户简称String32EnglishName企业客户英文名称String128EngShortName企业客户英文简称String32FQDN企业FQDNString256CorpLicense企业营业执照号String64LegalPerson企业法人String64AdminPhone 企业管理员联系电话String32AdminMobile企业管理员联系手机String32AdminEmail 企业管理员联系邮件String80Address企业地址String256MailingAddress企业邮寄地址String256ZipCode邮编String6Phone企业电话String32Fax传真号码String32Email邮箱地址String80WebSite企业WEB网址String100CorpLogoURL企业Logo URLString256UpdateTime变更时间，格式为YYYYMMDDHHmmssfffString171.2.6 企业员工信息接口 接口描述对于需要企业员工信息的ISV应用，则实现该接口，以接受企业员工信息更新。 交互流程1 管理员在平台中更新企业员工信息。2 ISV定期（按需）从SaaS平台获取最新的企业员工信息。3 SaaS平台将最新的企业员工信息返回至ISV。4 ISV应用系统更新本地数据系统。 应用场景 接口定义消息类型编码SYS10302请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式企业客户编号用户ID ,n名称说明数据类型长度（字节）CorpID企业客户编号String16UserIDs用户ID列表(以逗号分割，用户ID是Guid的串);至少包含一个用户ID String返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述企业客户编号用户ID用户名称别名性别用户登录名用户AD 帐号用户SAM帐户邮箱地址联系地址HomeAddress身份证出生日期部门ID 职务办公电话移动电话变更时间名称说明数据类型长度（字节）ResultCode返回结果代码（0: 成功；1: 失败）String16ResultDesc返回结果描述String256CorpID企业客户编号String16UserID用户ID(Guid)String36StaffName用户名称String32Alias别名String32Sex性别F女 M男String1UserName用户登录名String20ADAccount用户AD 帐号String50SAMAccount用户SAM帐户String20Email邮箱地址String80Address联系地址String256CardID证件号String32Birthday出生日期格式为YYYYMMDDString8DeptID部门IDString16Position职务String32OfficePhone办公电话String24MobilePhone移动电话String24UpdateTime变更时间，格式为YYYYMMDDHHmmssfff（必填）String171.2.7 企业部门信息接口 接口描述对于需要企业部门信息的ISV应用，则实现该接口，以接受企业部门信息更新。 交互流程1 管理员在平台中更新企业部门信息。2 ISV定期（按需）从SaaS平台获取最新的企业部门信息。3 SaaS平台将最新的企业部门信息返回至ISV。4 ISV应用系统更新本地数据系统。 应用场景 接口定义消息类型编码SYS10303请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式企业客户编号部门ID,n名称说明数据类型长度（字节）CorpID企业客户编号String16DeptIDs部门ID 列表(以逗号分割)String256返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述企业客户编号部门ID 上级部门ID 部门名称部门描述部门电话部门传真号变更时间名称说明数据类型长度（字节）ResultCode返回结果代码(0: 处理成功；1: 处理失败)String16ResultDesc返回结果描述String256CorpID企业客户编号String16DeptID部门IDString16ParentID上级部门ID，无上级部门填0String16DeptName部门名称String32DeptDesc部门描述String100DeptPhone部门电话String32DeptFax部门传真号String32DeptMgrID部门负责人用户ID(可转换为Guid的串)String36UpdateTime变更时间，格式为YYYYMMDDHHmmssfffString171.2.8 企业通讯录信息接口 接口描述对于需要企业通讯录信息的ISV应用，则实现该接口，以接受企业通讯录信息更新。 交互流程1 管理员在平台中更新企业通讯录信息。2 ISV定期（按需）从SaaS平台获取最新的企业通讯录信息。3 SaaS平台将最新的企业通讯录信息返回至ISV。4 ISV应用系统更新本地数据系统。 应用场景 接口定义消息类型编码SYS10304请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式企业客户编号联系人ID ,n名称说明数据类型长度（字节）CorpID企业客户编号String16ContactIDs联系人ID列表(以逗号分割).如果 是空串,则表示获取所有联系人String返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述企业客户编号联系人ID联系人全名 联系人名字 联系人中间名 联系人姓氏 职位电子邮件公司电话家庭电话移动电话家庭住址邮政编码变更时间名称说明数据类型长度（字节）ResultCode返回结果代码(0:处理成功；1: 处理失败)String16ResultDesc返回结果描述String256CorpID企业客户编号String16ContactID联系人IDString16FullName联系人全名String64FirstName联系人名字String24MiddleName联系人中间名String16LastName联系人姓氏String24Title职位String32Email电子邮件String80CompanyPhone公司电话String32HomePhone家庭电话String32Mobile移动电话String24HomeAddress家庭住址String256Zipcode邮政编码String6UpdateTime变更时间，格式为YYYYMMDDHHmmssfffString171.2.9 ISV消息通知接口 接口描述ISV产品中会发生一些事件，比如：剩余金额不够时或者产品中重要信息被更改时等等，此时ISV产品需要向用户发送一些消息通知。目前平台提供三种消息，分别为短信通知，邮件通知和Web站内消息通知。ISV可以使用这些通知方式来通知相应的产品用户。 交互流程1 ISV调用平台消息通知接口。2 SaaS平台将消息根据类型发送出去。 接口定义消息类型编码SYS10601请求消息消息格式Request通用消息头（ref: 附录）加密后的消息体未加密的消息体格式企业客户编号 用户类型（是否管理员）用户ID消息类型消息标题消息内容名称说明数据类型长度（字节）CorpID企业客户编号String16UserType用户类型（是否管理员）(1: 企业管理员；0:企业普通用户)String1UserID用户ID（可转化成Guid），如果UserType为1，则该项传递的任何值都被忽略；如果UserType为0，则需要准确的相应用户IDString36MessageType消息类型， 0001为Web站内消息，0010为短信消息，0100为邮件通知。如果想同时发送多种消息，则对这三种基本消息格式做叠加，如0011：是同时发送站内消息和短信通知，0101是同时发送站内消息和邮件通知，0110是同时发送短信消息和邮件通知，0111是同时发送三种消息。注意：同时发送多类消息时，需要注意内容长度，比如同样的消息，邮件可能就是一封，但短信可能就是多条，所以在发送消息时注重用户的可读性。String4MessageSubject消息标题，其中可以含有占位符(ref:占位符)string=256MessageBody消息内容，其中可以含有占位符(ref:占位符)，如果还想发送Html的邮件，请将Text消息和Html消息之间使用关键词stone进行分割，但必须Html中的都变成>String=8000返回消息消息格式Response通用消息头（ref: 附录）加密后的消息体未加密的消息体格式返回结果代码返回结果描述名称说明数据类型长度（字节）ResultCode返回结果代码，更多结果代码，请（ref: 消息返回码定义）(0: 处理成功；1: 处理失败)String16ResultDesc返回结果描述String25 占位符定义占位符含义AppName对