网易企业邮箱集成接口技术白皮书v111HZ.docx

1、网易企业邮箱集成接口技术白皮书v111HZ网易企业邮箱集成接口技术白皮书稳定可靠，安全无忧V1.1.HZ修订历史记录版本日期修订说明编制审核0.12012-4-28文档第一版，完成部门帐号同步接口、单点登录接口、未读邮件数量接口和添加自定义登录框湛舜研0.22012-5-9完成文档概述和接口综述，修改各接口介绍中的文字错误徐亭湛舜研1.02012-5-14修改2.6申请流程，修改6.2 接口规范，强调域名一致与域名值为客服提供的代码串徐亭湛舜研1.1修改1.3术语解析：RSA算法，增加URL湛舜研目 录1 关于文档 11.1 目标 11.2 读者 11.3 术语定义 11.4 如何获得帮助 1

2、2 接口综述 22.1 目标 22.2 功能概述 22.3 总体架构 22.4 前提条件 32.5 应用步骤 32.6 申请流程 43 部门帐号同步接口 53.1 接口说明 53.2 接口规范 53.2.1 技术规范 53.2.2 使用规范 53.3 加密参数说明（enc值） 63.3.1 操作说明（action值） 63.3.2 操作参数说明 83.3.3 URL示例 93.3.4 操作示例 103.4 应用示例 114 单点登录接口 124.1 接口说明 124.2 接口规范 124.2.1 技术规范 124.2.2 使用规范 124.3 应用示例 135 未读邮件数量接口 145.1 接

3、口说明 145.2 接口规范 145.2.1 技术规范 145.2.2 使用规范 145.3 应用示例 156 自定义登录框接口 166.1 接口说明 166.2 接口规范 166.2.1 技术规范 166.2.2 数据规范 166.2.3 注意事项 176.3 应用示例 17关于文档目标这份文档帮助客户或经销商详细了解网易企业邮箱接口集成的具体功能和操作方法。读者这份文档的预期读者为客户IT相关负责人、经销商客服和技术支持人员。术语解析 HTTP协议超文本传输协议(HTTP)是一种通信协议，它允许将超文本标记语言(HTML)文档从web服务器传送到Web浏览器。 URL统一资源定位符（URL

4、，英语UniformResourceLocator的缩写）也被称为网页地址，是因特网上标准的资源的地址。统一资源定位符 URL 是对可以从因特网上得到的资源的位置和访问方法的一种简洁的表示。 RSA加密算法RSA加密算法是是目前最有影响力的公开密钥密码体制加密算法，它能够抵抗到目前为止已知的所有密码攻击，已被ISO推荐为公钥数据加密标准，从提出到现在的三十多年里，经历了各种攻击的考验，逐渐为人们接受，普遍认为是目前最优秀的公钥方案之一。如何获得帮助如对文档有任何疑问，欢迎致电 400-6281-163 或发邮件 kf 进行咨询并作深入的了解。接口综述目标网易企业邮箱拥有多个集成接口供客户使用，

5、并能与其他业务系统进行集成。功能概述网易企业邮箱提供多种集成接口与客户应用系统进行无缝集成，可实现与用户应用系统中组织架构同步和未读邮件数同步，并且可以在用户应用系统或者用户网站登录首页实现单点登录或者嵌入自定义登录的入口，解决了网易企业邮箱系统与客户应用系统的集成数据共享问题。采用公私钥加密技术和服务请求IP地址过滤等方案保障数据交互接口的安全。总体架构前提条件接口类型前提条件部门账号同步系统的可扩展性、有固定的登录IP单点登录系统的可扩展性未读邮件数系统的可扩展性、有固定的登录IP自定义登录从企业域名对应的网站或系统登录应用步骤1. 引用RSA工具包：RSA-1.1.1.jar2. 生成密

6、钥：ease.domainmail.Utils.createKeyPair(); 执行结果如下：Generating a pair of RSA key . pubKey:30819f300d06092a864886f70d010101050003818d003081890281810085802e30d10d33197354c6c2d0785526ff17b4741048745f17e8e91cb38c70dd60e9bce1bf9b73d9215ccb56ad68c5efcf3d7f62677cd685cb1664601b57f1535138ea1e60apriKey:3082027602

7、0100300d06092a864886f70d0101010500048202603082025c0201000281810085802e30d10d33197354c6c2d0785526ff17b4741048745f17e8e91cb38c70dd60e9bce1bf9b73d9215ccb56ad68c5efcf3d7f62677cd685cb1664601b57f1535138ea1e60a42e8ccbb813ba8f7c91d27fcfde305cd1edc04a5aa26afba8e04c87c786113c2616f2fb8b6f5b9e0c55fb141eb96ae742

8、6d35fbe9de581fccb6210201024-bit RSA key GENERATED.3. 把公钥和IP地址告诉接口提供方进行授权。(注：单点登录接口不需要限定IP，可以不提供)4. 生成操作参数（原始字符串）。5. 参数加密：ease.domainmail.Utils.encrypt(String priKey, String source);其中，priKey是私钥，source是原始字符串，返回加密后的字符串。6. 组装完整URL请求地址。7. 发送POST请求。8. 返回操作结果。申请流程注：上述流程图中红色字体部分的是客户申请需提供的资料 部门帐号同步接口接口说明部门帐

9、号同步接口通过HTTP协议访问接口并提交同步指令，支持创建、更新和删除部门或子部门，创建、禁用、删除和恢复用户，修改帐号密码和属性。接口规范技术规范1. 客户按网易企业邮箱提供的算法（标准RSA算法，1024位密钥长度）生成公私钥，将公钥提供给网易企业邮箱，私钥自行妥善保管，通过接口提交URL链接参数必须使用RSA私钥加密，禁止明文传输。国内银行的网银通讯也是采用此类加密传输方式，可以有效防止数据被盗用或篡改，给予用户数据安全保护的最高级别。2. 客户还需要提供访问接口的服务器IP地址。网易企业邮箱会对IP地址进行服务授权，进一步增强接口的安全性。3. 接口仅支持HTTP协议，使用POST方法

10、访问。使用规范1. POST请求到URL： 2. *： 真实URL中替换为实际操作要填入的参数值。3. cid：用于标识企业，由网易企业邮箱分配提供，实际用的是orgid。4. enc：加密操作参数。a) enc的第一个参数固定为action，表示要执行的操作。b) 后面的参数是action操作参数，参数之间用“&”分隔。5. 参数值使用URLEncoder.encode(String,utf-8)编码，以保证不存在特殊字符干扰参数值的解析。6. 返回值采用code+文字说明的方式。如：200rn：操作成功；500rn：操作失败；4*rn：没有权限。加密参数说明（enc值）操作说明（actio

11、n值）操作名操作说明操作参数参数属性备注createOrg创建部门ouid必填 录入项org_unit_name必填 录入项parent_org_unit_id选填匹配项 录入项创建下级部门时使用updateOrg更新部门ouid必填 匹配项org_unit_name选填 录入项更新部门名称u_desc选填 录入项更新部门描述deleteOrg删除部门ouid必填 匹配项要求该部门下没有邮箱帐号createUser创建帐号account_name必填 录入项nickname必填 录入项password必填 录入项department选填匹配项 录入项job_no选填 录入项exp_time选填

12、 录入项address_right选填 录入项privacy_level选填 录入项updateUser更新帐号account_name必填 匹配项nickname选填 录入项更新姓名department选填匹配项 录入项更新所属部门status选填 录入项禁用/恢复帐号job_no选填 录入项更新工号exp_time选填 录入项更新过期时间address_right选填 录入项可否使用企业通讯录privacy_level选填 录入项是否在企业通讯录显示delta_quota选填 录入项分配额外容量deleteUser删除帐号account_name必填 匹配项禁用帐号7天，7天后彻底删除re

13、coverUser恢复帐号account_name必填 匹配项删除帐号7天内可以恢复updateUserPwd更新帐号密码account_name必填 匹配项password必填 录入项需确保用户记住新改的密码注意： 操作名区分大小写！ 参数属性为“匹配项”，参数值必须匹配数据库中已有数据，否则操作失败，POST返回值为500。参数属性为“录入项”，参数值将存入网易企业邮箱数据库。操作参数说明参数名类型名称说明部门参数ouidString部门ID部门唯一标识，由企业通过接口创建部门时建立，并要求记录好部门与ouid之间的对应关系parent_org_unit_idString父级部门ID标识部

14、门在组织架构所处位置org_unit_nameString部门名称同一级的部门名称不允许重复u_descString部门描述添加部门文字介绍和简单描述帐号参数account_nameString邮箱帐号邮箱帐号作为邮箱地址前缀，邮箱用户的唯一标识，企业内同一域内不可重复nicknameString姓名用户的姓名显示于企业通讯录passwordString密码帐号的登录密码departmentString所属部门ID使用部门参数的ouidstatusint状态0表示正常，1表示禁用job_noString工号用户的工号信息exp_timeDate过期时间格式：yyyy-MM-dd address

15、_rightint能否使用企业通讯录0不能，1可以（默认）privacy_levelint是否在企业通讯录显示0不显示，2显示（默认）delta_quotaint额外的空间需申请开通容量自主分配功能URL示例以创建用户为例：（公司的cid为abc123）原始参数：action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsxRSA加密后参数：1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef7

16、50a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e22479

17、1682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039完整的请求地址： 接口解析之后的地址（即原始请求）： dept_1&password=1qaz2wsx操作示例1. 创建部门2. 更新部门 ABC销售事业部3. 创建子部门4. 删除部门5. 创建用户 dept_1&password=1qaz2wsx6. 修改用户属性7. 删除用户8. 恢复用户9. 修改用户密码注意：红色部分需

18、要RSA加密应用示例以创建用户为例（假设客户域名为，cid值为abc123）： 原始参数：action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsxRSA加密后参数：1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158

19、866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff9

20、2f0179fef63ce4b0f9074f53554cc087e52e288585269039完整的请求地址： 接口解析之后的地址（即原始请求）： dept_1&password=1qaz2wsx单点登录接口接口说明采用RSA加密算法的HTTP协议接口，客户提交邮箱帐号及加密信息，网易企业邮箱解密验证通过后，给予浏览器页面自动跳转登录访问邮箱。接口规范技术规范1. 客户按网易企业邮箱提供的算法（标准RSA算法，1024位密钥长度）生成公私钥，将公钥提供给网易企业邮箱，私钥自行妥善保管。通过接口提交URL参数必须使用RSA私钥进行摘要签名，以确保URL请求能验证通过。2. 接口使用HTTPS协

21、议，每个请求URL只有一次请求有效，每个URL生成后5分钟内有效。使用规范1. POST或GET请求到URL：2. *：真实URL中替换为实际操作要填入的参数值。3. domain：企业邮箱注册域名，用于标识客户。4. account_name：需要单点登录的邮箱帐号。5. time：生成URL的服务器当前时间(单位ms，至现在所经过的 UTC 毫秒数)。6. lang：单点登录后邮箱页面使用的语言版本，此参数可以不填，默认为中文。7. enc：加密串用于验证URL提交方的身份。Enc的参数原文为account_name、domain、time三个参数值按顺序连起来，中间不要任何符号间隔。8. 参数值使用URLEncoder.encode(String,utf-8)编码，以保证不存在特殊字符干扰参数值的解析。9. 返回值采用code+文字说明的方式。如：200rn：操作成功；500rn：操作失败；4*rn：没有权限。应用示例% page contentType=text/h