养老保险待遇状态比对查询服务系统接口开发手册.doc

养老保险待遇状态比对查询服务系统接口开发手册（1.0版）2011.7.25目 录1接口api使用说明11.1接口api概述12java接口使用说明12.1java接口类列表12.2java接口api说明22.2.1上传fileuploadagentfileuploadparamsfileuploadresponse62.2.2通用查询commqueryagentcommqueryresponse92.2.3错误文件下载errfiledownloadagenterrfiledownloadparamserrfiledownloadresponse142.2.4证书有效期查询certqueryagent162.3java接口开发举例162.3.1领取人员批量查询领取人员批量查询上传通用查询（查询领取待遇人员批量查询结果）错误文件列表查询错误文件下载183c接口使用说明193.1c接口api说明193.1.1上传fileuploadagentinitsetfileuploadparamsfileuploadsendandreceivegetfileuploadresponsefileuploadagentend213.1.2通用查询commqueryagentinitsetcommqueryparamscommquerysendandreceivegetcommqueryresponsecommqueryagentend233.1.3错误文件下载errfiledownloadagentinitseterrfiledownloadparamserrfiledownloadsendandreceivegeterrfiledownloadresponseerrfiledownloadagentend253.1.4证书有效期查询getcertperiod25附录1比对查询系统反馈的错误代码列表1附录2：接口反馈代码2附录3：查询条件列表6附录4：开发常见问题及解答881 接口api使用说明1.1 接口api概述在采用嵌入式或前置系统接入模式下，基于本手册进行本地后台接口的开发。比对查询业务接口api提供了基于java和c语言的两种接口封装形式，各地可根据本地业务管理系统的开发环境选用。java接口采用jar包形式，c语言采用动态链接库dll形式并提供开发需要的.h头文件和.lib库文件。在实际的运行环境中，需要将jar或者dll文件部署到使用比对查询业务接口的系统库文件目录内，部署接口api的服务器必须能够通过网络直接访问部级养老保险待遇状态比对查询服务系统进行数据交换，同时由于接口会自动对传输的数据进行数字签名，需要在此服务器上部署安装金保工程统一的设备数字证书以及相关认证软件包。2 java接口使用说明2.1 java接口类列表接口名称接口描述fileuploadagent文件上传代理fileuploadparams上传文件参数对象fileuploadresponse上传文件结果返回对象commqueryagent通用查询代理commqueryresponse通用查询返回对象errfiledownloadagent下载错误文件代理errfiledownloadparams下载错误文件参数对象errfiledownloadresponse下载错误结果返回对象certqueryagent查询证书有效期对象2.2 java接口api说明jar包名称：sitrb.jar依赖包：axis 1.4开发环境要求：支持eclipse等各类java开发工具，j2se1.4及以上版本。运行环境要求：jre1.4以及上版本，可以部署在j2ee容器内运行。2.2.1 上传 fileuploadagent上传文件代理类，上传文件时调用此类。构造方法摘要fileuploadagent()初始化一个建新的fileuploadagent对象。方法摘要fileuploadresponse sendandreceive(fileuploadparams upparams)将请求信息发送给服务器,并返回一个fileuploadresponse对象。构造方法详细信息.1 fileuploadagentpublic fileuploadagnet()初始化一个新建的fileuploadagent对象。方法详细信息.2 sendandreceivepublic fileuploadresponse sendandreceive(fileuploadparams upparams)将请求信息发送给服务器,并返回一个fileuploadresponse对象。参数：upparams 上传文件参数对象。返回：fileuploadresponse 上传文件结果返回对象。 fileuploadparams上传文件参数类，用于传入上传文件请求的各种参数。构造方法摘要fileuploadparams()初始化一个建新的fileuploadparams对象。方法摘要void setorgid(string orgid)传入组织机构代码void setbuzztype(string transtype)传入业务数据分类标识void setsendtype(string uptype)传入上传方式，1-以文件方式上传；2-以流方式上传void setuploadfilename (string uploadfilename)传入上传文件的文件名。void setuploadstream(string stream)传入待上传字符流。以文件方式上传时不需传入该值。void setcerttype (string certtype)传入证书类型。public void setxzscope(string xzscope)上传文件所属险种，必须是具体一个险种类型，如110、120、150。构造方法详细信息.1 fileuploadparamspublic fileuploadparams()初始化一个新建的fileuploadparams对象。方法详细信息.2 setbuzztypepublic void setbuzztype(string buzztype)传入本次上传的交易类型。参数：buzztype 本次上传的业务类型代码。返回：无。.3 setdatafiletypepublic void setdatafiletype(string datafiletype)传入数据文件类型。参数：datafiletype 数据文件类型。1txt文件。返回：无。.4 setsendtypepublic void setsendtype(string sendtype)传入上传方式。参数：sendtype 上传方式，1- 以文件方式上传。2- 以流方式上传。返回：无。.5 setfiledatepublic void setfiledate(string senddate)传入文件生成日期。参数：filedate 文件生成日期，格式为yyyymmdd。返回：无。.6 setuploadfilenamepublic void setuploadfilename(string uploadfilename)传入上传文件的文件名。参数：uploadfilename 文件名。返回：无。.7 setuploadstreampublic void setuploadstream(string stream)传入待上传字符流。参数：stream 待上传字符流，当上传方式为文件方式时返回值无意义。返回：无。.8 setcerttypepublic void setcerttype(string certtype)传入证书类型。参数：certtype 证书类型。2设备证书。返回：无。.9 setxzscopepublic void setxzscope(string xzscope)传入险种类型。参数：xzscope ,险种类型：110城镇企业职工基本养老保险，120机关事业单位养老保险，150新型农村社会养老保险，160城镇居民社会养老保险，170城乡居民社会养老保险。返回：无。 fileuploadresponse上传结果返回对象，返回上传文件处理是否成功标志及处理信息。构造方法摘要fileuploadresponse()初始化一个建新的fileuploadresponse对象。方法摘要string geterrorflag()获取上传文件处理是否成功标志。string getretmsg()获取上传文件处理结果信息。string getstackstrace()获取查询操作的错误堆栈构造方法详细信息.1 fileuploadresponsepublic fileuploadresponse()初始化一个新建的fileuploadresponse对象。方法详细信息.2 geterrorflagpublic string geterrorflag()获取上传文件处理是否成功标志。参数：无。返回：string 是否成功标志。0成功，非0失败（具体类型参见错误类型列表）.3 getretmsgpublic string getretmsg()获取上传文件处理结果信息。参数：无。返回：string 上传文件处理结果信息。.4 getstacktracepublic string getstacktrace()获取上传操作的错误堆栈。参数：无。返回：string 上传操作的错误堆栈。2.2.2 通用查询 commqueryagent通用查询代理类，向后台发送各类业务查询请求，后台业务程序按约定格式返回查询结果。构造方法摘要commqueryagent()初始化一个建新的commqueryagent对象。方法摘要void setorgid(string orgid)传入组织机构代码string setcerttype (string certtype)传入证书类型。void setbuzztype(string funcid)传入查询请求业务类型。void setqueryparams(hashmap params)传入查询请求参数。不同的业务查询所需要的参数不尽相同，具体业务查询参数详见接口功能说明部分。string query()将请求信息发送给服务器，查询业务数据，业务程序按约定格式返回结果字符串，具体格式参见数据传输封装规范。public void setxzscope(string xzscope)查询所属险种，具体一个险种类型，如110、120、150。对应上传文件的险种类型。构造方法详细信息.1 commqueryagentpublic commqueryagent ()初始化一个新建的commqueryagent对象。方法详细信息.2 setbuzztypepublic void setbuzztype (string buzztype)传入查询业务类型，具体类型对应业务详见接口功能列表。参数：buzztype 查询请求业务类型返回：无。.3 setdatafiletypepublic void setdatafiletype(string datafiletype)传入数据文件类型。参数：datafiletype 数据文件类型。1txt文件。返回：无。.4 setcerttypepublic void setcerttype(string certtype)传入证书类型。参数：certtype 证书类型。”2” 设备证书返回：无。.5 setqueryparampublic void setqueryparam(hashmap params)传入查询参数。参数：params 查询参数，不同的查询业务所需要的参数不尽相同，全部为string类型，具体参数详见接口功能列表。返回：无。.6 querypublic commqueryresponse query()将查询请求发送到服务器，查询业务数据，业务程序按约定格式返回结果字符串，具体格式参见数据传输封装模范。参数：无返回：commqueryresponse 返回的查询数据。.7 setxzscopepublic void setxzscope(string xzscope)传入险种类型。参数：xzscope ,险种类型：110城镇企业职工基本养老保险，120机关事业单位养老保险，150新型农村社会养老保险，160城镇居民社会养老保险，170城乡居民社会养老保险。返回：无。 commqueryresponse查询结果返回对象，返回下载文件处理是否成功标志,查询得到的信息和文件名。构造方法摘要commqueryresponse()初始化一个建新的filedownloadresponse对象。方法摘要string geterrorflag()获取查询是否成功标志。string getretmsg()获取查询结果信息。string getstackstrace()获取查询操作的错误堆栈string getdownfilename()获取查询结果的文件名称。string getdownstream()获取查询结果。构造方法详细信息.1 commqueryresponsepublic filedownloadresponse()初始化一个新建的filedownloadresponse对象。方法详细信息.2 geterrorflagpublic string geterrorflag()获取下载文件处理是否成功标志。参数：无。返回：string 是否成功标志。0成功，非0失败（具体类型参见错误类型列表）.3 getretmsgpublic string getretmsg()获取下载文件处理结果信息。参数：无。返回：string 下载文件处理结果信息。.4 getdownfilenamepublic string getdownfilename()获取下载后的文件名称。参数：无。返回：string 下载后的文件名称。.5 getstacktracepublic string getstacktrace()获取上传文件处理结果信息。参数：无。返回：string 上传操作的错误堆栈。.6 getdownstreampublic string getdownstream()获取下载的字符流。参数：无。返回：string 下载的字符流。2.2.3 错误文件下载 errfiledownloadagent错误文件下载代理类，下载错误文件时调用此类。构造方法摘要errorfiledownloadagent()初始化一个建新的errorfiledownloadagent对象。方法摘要filedownloadresponse sendanddownloaderrfile(errfiledownloadparams errdownparams)将下载错误文件的请求参数发送给服务器，下载错误文件，并返回一个filedownloadresponse对象。public void setxzscope(string xzscope)下载文件所属险种，是具体一个险种类型，如110、120、150。对应上传文件的险种类型。构造方法详细信息.1 errfiledownloadagentpublic filedownloadagnet()初始化一个新建的filedownloadagent对象。方法详细信息.2 sendanddownloaderrfilepublic filedownloadresponse sendanddownloaderrfile(errfiledownloadparams errdownparams)将请求信息发送给服务器，下载错误文件，并返回一个filedownloadresponse对象。参数：errdownparams 下载错误文件参数对象。返回：filedownloadresponse 下载文件结果返回对象。 errfiledownloadparams下载错误文件参数类，用于传入下载错误文件的各种参数。构造方法摘要errfiledownloadparams()初始化一个建新的errfiledownloadparams对象。方法摘要void setorgid(string orgid)传入组织机构代码string setdatafiletype (string datafiletype)传入数据文件类型。string setorignalfilename (string orignalfilename)传入上传原文件名。string setcerttype (string certtype)传入证书类型。public void setxzscope(string xzscope)下载文件所属险种，是具体一个险种类型，如110、120、150。对应上传文件的险种类型。构造方法详细信息方法详细信息.1 setcerttypepublic void setcerttype(string certtype)传入证书类型。参数：certtype 证书类型。”2” 设备证书返回：无。.2 setdatafiletypepublic void setdatafiletype(string datafiletype)传入数据文件类型。参数：datafiletype 数据文件类型。1txt文件。返回：无。.3 setorignalfilenamepublic void setorignalfilename(string orignalfilename)传入证书类型。参数：orignalfilename 待下载的错误文件名。返回：无。.4 setxzscopepublic void setxzscope(string xzscope)传入险种类型。参数：xzscope ,险种类型：110城镇企业职工基本养老保险，120机关事业单位养老保险，150新型农村社会养老保险，160城镇居民社会养老保险，170城乡居民社会养老保险。返回：无。 errfiledownloadresponse下载文件结果返回对象，返回下载文件处理是否成功标志、处理信息和下载后的文件名。构造方法摘要errfiledownloadresponse()初始化一个建新的filedownloadresponse对象。方法摘要string geterrorflag()获取上传文件处理是否成功标志。string getretmsg()获取上传文件处理结果信息。string getdownfilename()获取下载后的文件名称。当下载数据文件类型为2-字符流时，文件名无意义。string getdownstream()获取下载后的字符流。构造方法详细信息.1 errfiledownloadresponsepublic filedownloadresponse()初始化一个新建的filedownloadresponse对象。方法详细信息.2 geterrorflagpublic string geterrorflag()获取下载文件处理是否成功标志。参数：无。返回：string 是否成功标志。0成功，非0失败（具体类型参见错误类型列表）public string getretmsg()获取下载文件处理结果信息。参数：无。返回：string 下载文件处理结果信息。.3 getstacktracepublic string getstacktrace()获取上传文件处理结果信息。参数：无。返回：string 上传操作的错误堆栈。.4 getdownfilenamepublic string getdownfilename()获取下载后的文件名称。参数：无。返回：string 下载后的文件名称。.5 getdownstreampublic string getdownstream()获取下载的字符流。参数：无。返回：string 下载的字符流。2.2.4 证书有效期查询 certqueryagent方法详细信息public static string getcertperiod()获取证书的有效期参数：无返回：无异常直接返回 有效期 格式为yyyy年mm月dd日 如：2018年01月12日 异常返回 获取本地证书有效期失败+exception2.3 java接口开发举例java接口与界面方式一样，分多个业务类型和环节。现根据业务类型和环节对接口的使用说描述。业务场景为领取人员批量查询。2.3.1 领取人员批量查询 领取人员批量查询上传引入相关包，对文件上传参数对象设置，调用sendandreceiveasync方法，该方法会抛出异常import java.io.inputstreamimport com.icss.client.fileuploadagent;import com.icss.client.fileuploadparams;import com.icss.client.fileuploadresponse;fileuploadparams upparams = new fileuploadparams();/ 对upparams进行封装.fileuploadagent fileupagent = new fileuploadagent();fileuploadresponse fileuploadresponse = fileupagent.sendandreceiveasync(upparams);string errorflag = fileuploadresponse.geterrorflag();/ 针对其中错误做出一些处理(以下以209、211、212和215为例)if (209.equals(errorflag) | 211.equals(errorflag)| 212.equals(errorflag) | 215.equals(errorflag) / 针对错误进行处理 . 通用查询（查询领取待遇人员批量查询结果）commqueryagent commqueryagent = new commqueryagent();map queryparams = new hashmap();/ 对queryparams进行封装.commqueryagent.setqueryparams(queryparams);commqueryresponse commqueryresponse = commqueryagent.query();string errorflag = commqueryresponse.geterrorflag();/ 针对其中错误做出一些处理(以下以209、211、212和215为例)if (209.equals(errorflag) | 211.equals(errorflag)| 212.equals(errorflag) | 215.equals(errorflag) / 针对错误进行处理 . 错误文件列表查询查询出所有的错误文件以便下载错误文件：errfilelistqueryparams querylistparams = new errfilelistqueryparams()/ 对queryparams进行设值封装.errfilelistqueryagent filedownagent = new errfilelistqueryagent();errfilelistqueryresponse errfilelistresponse = filedownagent.sendandgetqueryresult(querylistparams);string errorflag = errfilelistresponse.geterrorflag();/ 针对其中错误做出一些处理(以下以209、211、212和215为例)if (209.equals(errorflag) | 211.equals(errorflag)| 212.equals(errorflag) | 215.equals(errorflag) / 针对错误进行处理 . 错误文件下载errfiledownloadparams errdownparams = new errfiledownloadparams()/ 对errdownparams进行设值封装.errfiledownloadagent filedownagent = new errfiledownloadagent();errfiledownloadresponse errfiledownloadresponse = filedownagent.sendanddownloaderrfile(errdownparams);string errorflag = errfiledownloadresponse.geterrorflag();/ 针对其中错误做出一些处理(以下以209、211、212和215为例)if (209.equals(errorflag) | 211.equals(errorflag)| 212.equals(errorflag) | 215.equals(errorflag) / 针对错误进行处理 .3 c接口使用说明3.1 c接口api说明3.1.1 上传 fileuploadagentinit功能简介初始化上传代理。接口名称long fileuploadagentinit ()参数说明入参说明无出参说明无返回值fileuploadagent的句柄。 setfileuploadparams功能简介设置上传参数。接口名称char *setfileuploadparams(long handle, char* pparamname, char* pparamvalue)参数说明入参说明nhandle：fileuploadagent的句柄；pparamname：参数名称，具体支持的参数见下表；pparamvalue：参数值。出参说明 无返回值“000”为成功，其余为失败，具体错误参见错误代码表。参数表：参数名参数常量定义参数说明组织机构代码upload_orgid请求上传文件的经办机构的行政区划编码业务类型代码upload_buzztype如”t01011”上传方式upload_sendtype“1”-文件方式，”2”-流方式数据文件类型upload_datafiletype传输的数据文件类型,1-txt文件文件名upload_uploadfilename请求上传的文件名证书类型upload_certtype使用的证书类型,”2”-设备证书。文件流upload_uploadstream文件流险种范围upload_xzscope险种范围，如110，310等。具体见java语言中的具体说明 fileuploadsendandreceive功能简介将请求信息发送给服务器，上传数据。 接口名称char* fileuploadsendandreceive (long nhandle)参数说明入参说明fileuploadagent的句柄出参说明 无返回值“000”为成功，其余为失败，具体错误参见错误代码表。 getfileuploadresponse功能简介获取上传文件处理描述信息。接口名称char* getfileuploadresponse(long nhandle,char* pparamname)参数说明入参说明nhandle :fileuploadagent的句柄pparamname：参数名称，具体支持的参数见下表；出参说明 无返回值参数的值参数表：参数名参数常量定义参数说明错误代码upload_errorflag“000”为成功，其余为失败，具体错误参见错误代码表。返回信息描述upload_retmsg返回的具体信息异常堆栈upload_stacktrace异常的代码堆栈 fileuploadagentend功能简介释放上传代理。接口名称char* fileuploadagentend (long nhandle)参数说明入参说明fileuploadagent的句柄出参说明 无返回值“000”为成功，其余为失败，具体错误参见错误代码表。3.1.2 通用查询 commqueryagentinit功能简介初始化通用查询代理。接口名称long commqueryagentinit ()参数说明入参说明无出参说明无返回值commqueryagent的句柄 setcommqueryparams功能简介设置通用查询参数。接口名称char* setcommqueryparams(int nhandle, char* pparamname, char* pparamvalue)参数说明入参说明nhandle：commqueryanget的句柄；pparamname：参数名称，具体支持的参数见下表；pparamname：参数值。出参说明 无返回值“000”为成功，其余为失败，具体错误参见错误代码表。参数表（通用查询除以下参数外还可使用额外参数）：参数名参数常量定义参数说明组织机构代码commquery_orgid请求下载业务数据文件的组织机构代码业务类型commquery_buzztype请求下载的业务数据类型数据类型commquery_datafiletype下载的数据文件类型。1txt文件（目前只支持txt文件）证书类型commquery_certtype使用的证书类型。1-用户证书，2-服务器证书险种范围commquery _xzscope险种范围，如110，310等。具体见java语言中的具体说明 commquerysendandreceive功能简介将请求信息发送给服务器，进行查询操作。接口名称char* commquerysendandreceive (long nhandle)参数说明入参说明commqueryagent的句柄出参说明 无返回值“000”为成功，其余为失败，具体错误参见错误代码表。 getcommqueryresponse功能简介获取通用查询结果。接口名称char* getcommqueryresponse (long nhandle,char* pparamname)参数说明入参说明nhandle :commqueryagent的句柄pparamname：参数名称，具体支持的参数见下表；出参说明 无返回值参数的值参数表：参数名参数常量定义参数说明错误代码commquery_errorflag“000”为成功，其余为失败，具体错误参见错误代码表。返回信息描述commquery _retmsg返回的具体信息异常堆栈commquery_stacktrace异常的代码堆栈数据文件名commquery_downfilename查询结果文件名数据文件内容commquery_downstream查询数据结果 commqueryagentend功能简介释放通用查询代理。接口名称char* commqueryagentend (long nhandle)参数说明入参说明commqueryanget的句柄出参说明 无返回值“000”为成功，其余为失败，具体错误参见错误代码表。3.1.3 错误文件下载 errfiledownloadagentinit功能简介初始化下载代理。接口名称long filedownloadagentinit ()参数说明入参说明无出参说明无返回值errfiledownloadagent的句柄 seterrfiledownloadparams功能简介设置下载错误