全国公民身份信息系统Web服务接口调用规范V1[1].0-1092

全国公民身份信息系统（NCIIS）Web服务接口调用规范全国公民身份证号码查询服务中心二〇〇九年十一月第2页共25页目录第一章概述..............................................................................................................3第二章文档描述......................................................................................................4第三章术语和定义..................................................................................................53.1缩略语..........................................................................................................5第四章基本框架......................................................................................................64.1概念模型......................................................................................................64.2应用场景......................................................................................................6第五章接口定义......................................................................................................85.1服务条件模板获取......................................................................................85.2WS号码+姓名核查比对（支持单条和批量）.........................................9第六章HTTPS设置...........................................................................................15第七章客户端调用说明示例................................................................................187.1XFIRE介绍................................................................................................187.2客户端访问代码示例................................................................................197.3常见问题描述............................................................................................24第八章其他............................................................................................................25第3页共25页第一章概述全国公民身份信息系统是以全国公安人口信息管理系统提供的数据为基础，通过互联网和行业专网向政府部门、社会各界、人民群众依法提供公民身份信息服务。公民身份信息核查比对是全国公民身份信息系统(NCIIS)的主要功能，是系统对外服务的核心业务。Web服务接口为典型的行业客户提供了使用全国公民身份信息系统的访问接口，该接口透明的代理了NCIIS现有功能，为客户基于二次开发并将NCIIS现有功能集成到自身业务系统提供了技术基础。本Web服务接口的设计与实现遵循目前WebServices主流技术架构，满足开放系统的标准化规范要求。第4页共25页第二章文档描述本文档用于说明客户端调用全国公民身份信息系统Web服务接口规范。用于进行相关人口信息资源的核查比对访问。如客户端使用Java语言实现，建议使用xFire实现，且版本(xFire1.2.6)需与服务端相同，调用方式参见第八章客户端调用说明示例。如客户端使用非Java语言实现，具体实现方式请参见第三方开发语言技术文档。1．接口描述文档WSDL如需获取客户接入服务平台WebServices的接口描述文档，可以访问以下网址：其中，ipAddress为全国公民身份信息系统开通的客户接入服务器地址(域名为：api.nciic.org.cn)。此WSDL文档描述了客户接入服务WebServices的全部细节和调用的方法。包括消息的格式、传输协议和服务地址等。2．WSDL文档的解析作为服务请求者的客户为顺利与客户接入服务WebServices交互，必须首先获取该WSDL文档，并正确解析得到输入输出的各对象类。本系统的WSDL文档的样例如附录所示。不同的开发平台提供了不同的WSDL自动解析工具。如VS.NET中的WSDL.exe工具、Borland公司的Jbuilder、Bea公司的WeblogicWorkshop等。使用哪一种工具要视集团客户外部应用的系统平台和开发平台具体情况以及客户的使用习惯而定。第5页共25页第三章术语和定义3.1缩略语SOAP简单对象访问协议（SimpleObjectAccessprotocol）WSDLWeb服务描述语言（WebServiceDescriptionLanguage）XFireJavaSOAP框架第6页共25页第四章基本框架4.1概念模型通过Web服务平台为各行业业务系统提供业务协作接口和数据支撑。如图所示，客户端向Web服务平台发送规范的数据访问请求（SOAP请求），Web服务平台接收数据访问请求后调用服务层完成请求处理，并将处理结果返回给客户端（SOAP响应）。4.2应用场景客户端根据服务请求的接口定义规范，开发服务请求应用程序访问所提供的服务。说明：1.客户信息的验证通过授权文件参数来完成。授权文件在合同签署后会使用邮件等方式发送到客户手中（为加密格式）。客户在接口调用时将授权文件中读取的字符串作为服务调用时的一个接口参数传递给服务器端，服务端接收后通过授权文件内容进行身份验证。授权文件的内容包括：客户、用户、帐号、密码、IP地址、具体调用的服务。第7页共25页2.采用SOAP1.2作为消息的封装格式进行服务请求，服务端接收到请求后进行验证，验证通过后以SOAP1.2作为消息的封装返回服务响应内容。第8页共25页第五章接口定义5.1服务条件模板获取接口名称：nciicGetCondition传入参数：StringinLicense参数说明：?xmlversion=1.0encoding=UTF-8?LICENSEUSERINFOKHID…/KHID!--客户ID--YHID…/YHID!--用户ID--ZHID…/ZHID!--帐号ID--PASSWORD…/PASSWORD!--登录口令--IP…/IP!--登陆IP--/USERINFOSERVICEINFOFWID…/FWID!--服务ID--/SERVICEINFO/LICENSE注意：License文件会在签署合同后通过邮件等其他形式得到，License文件本身为加密格式，请参考示例代码编写客户端。如果授权文件中，参数：客户ID、用户ID、帐号ID、密码（登录口令）、服务ID发生变化，则需要重新生成一个新的授权文件。A）、正常返回结果：?xmlversion=\1.0\encoding=\UTF-8\?-ROWSINFOSBM******/SBM/INFO-ROWGMSFHM公民身份号码/GMSFHMXM姓名/XM/ROW-ROWFSD=”**”YWLX=”**”GMSFHMXXXXXX/GMSFHM第9页共25页XMXXXXXX/XM/ROW-ROWFSD=”**”YWLX=”**”GMSFHMXXXXXX/GMSFHMXMXXXXXX/XM/ROW/ROWS注意：1、通过授权文件验证，调用nciicGetCondition方法获取到的条件模版xml文件。填写数据时，依据此模版xml填写（详细说明请参看：inConditions参数说明）。B）、异常返回结果：?xmlversion=1.0encoding=UTF-8?-RESPONSEerrorcode=xxxcode=0countrows=1-ROWS-ROWErrorCodexxx/ErrorCode!--错误代码--ErrorMsgxxxxxxxxx/ErrorMsg!--错误描述--/ROW/ROWS/RESPONSE5.2WS号码+姓名核查比对（支持单条和批量）5.2.1功能描述为获得WEBSERVICE服务许可证的客户提供人口信息快速身份核查比对服务。根据身份证号等信息核查比对系统内有无相匹配的人的基本信息，若存在则返回存在记录数，否则返回零条。分为单条核查比对和批量核查比对两种方式进行核查比对，单条核查比对只能核查比对一条记录的信息，批量核查比对则可以核查比对多条记录的信息，批量核查比对最多可核查比对200条记录。5.2.2接口与参数接口名称：nciicCheck返回值：1：正常返回；2：错误返回（包括返回空结果）传入参数：StringinLicenseStringinConditions第10页共25页参数说明：字段类型描述inLicenseString客户身份校验文件（中心提供）inConditionsString条件XML字符串（由服务定义决定）A）、inLicense参数说明：?xmlversion=1.0encoding=UTF-8?LICENSEUSERINFOKHID…/KHID!--客户ID--YHID…/YHID!--用户ID--ZHID…/ZHID!--帐号ID--PASSWORD…/PASSWORD!--登录口令--IP…/IP!--登陆IP--/USERINFOSERVICEINFOFWID…/FWID!--服务ID--/SERVICEINFO/LICENSE注意：License文件会在签署合同后通过邮件等其他形式得到，License文件本身为加密格式，请参考示例代码编写客户端。如果授权文件中，参数：客户ID、用户ID、帐号ID、密码（登录口令）、服务ID发生变化，则需要重新生成一个新的授权文件。B）、inConditions参数说明：?xmlversion=\1.0\encoding=\UTF-8\?-ROWSINFO