异地退管系统接口技术方案

异地居住人员领取社会保险待遇资格协助认证信息系统接口技术方案本方案适用于与部级异地居住人员领取社会保险待遇资格协助认证信息系统（简称异地退管系统）衔接的各级业务管理系统。一、术语定义1功能标识：指异地退管系统通过接口对外提供的各类业务功能编号，四层六位，规则如下：业务编码（1位字母）流程编码（2位数字）环节编码（2位数字）操作编码（1位数字）（1）业务编码：表示功能所属的业务，以1位字母表示，如“R”表示异地居住退休人员管理业务。（2）流程编码：与业务编码一起表示功能所属的业务流程，以2位数字表示，如“R01”表示异地居住退休人员集中库管理流程。（3）环节编码：与业务编码和流程编码一起表示功能所属的业务环节，以2位数字表示，如“R0101”表示异地居住退休人员信息上传环节。（4）操作编码：表示功能的操作类别，以1位数字表示，“1”表示上传操作，“2”表示查询操作。例如“R03011”表示协助认证流程的协助认证通知环节中的上传协助认证通知功能。2数据集：指按照同一规则组合起来的数据集合体，一个数据集可以包含一条或多条数据记录。3数据文件：是业务数据在交换过程中的一种载体形式。数据文件以操作系统中的一个文件形式存在，有两种文件格式：txt文件格式，文件内部由报文头、一个或多个数据集构成的报文体、报文尾三部分组成；excel文件格式，有标题行和数据行两部分组成。4字符流：是业务数据在交换过程中的一种载体形式。字符流是在接口调用时在内存中的一个字符串或者流对象，内部存储格式与数据文件相同。二、接入技术模式（一）远程登录模式地方业务操作人员可在金保工程业务专网环境中，通过IE浏览器登录部级异地退管系统，人工实现异地退管数据的传输与交换，在线办理部分业务和实现查询统计。此种模式以TXT文件或EXCEL文件的形式进行数据传输，具体实现机制如下：1上传业务数据：通过业务管理系统导出相关数据文件，并按接口数据规范组织成TXT文件或EXCEL文件。通过金保工程业务专网登录部级异地退管系统，使用上传功能将业务数据（TXT文件或EXCEL文件）上传到部端。部级异地退管系统读取收到的文件，解析校验文件中的业务数据明细并保存。2接收业务数据：通过金保工程业务专网登录部级异地退管系统，使用下载功能查询下载属于本地区或下属地区接收的业务数据。部级异地退管系统将数据按接口数据规范组织成TXT文件或EXCEL文件并下载给接收方用户。（二）前置系统接入模式异地退管系统提供专用的接口API，供各地通过后台方式与异地退管系统实现传输与交换，详见异地退管系统接口开发手册（以下简称接口开发手册）。接口API包括两种类型，供不同开发模式选择：一是使用java语言开发的jar包，二是使用C语言开发的dll和lib。前置系统与部级异地退管系统、本地业务管理系统的交互方式如下图所示：1前置系统功能前置系统是业务管理系统与异地退管系统间通信的中间环节。各地需根据本地业务管理系统建设情况及业务要求定制前置系统功能。为保证接口的稳定性，部级异地退管系统提供的接口为纯技术接口，地方可在前置系统中通过各种参数组合完成对此接口的封装，形成适合当地的业务接口，供本地业务管理系统调用。前置可以存储数据（数据库或文件形态均可），也可以不存储数据。基本情况有三类。（1）同步转发功能。在本地业务管理系统直接实现报文数据的组织与解析，与前置系统交换标准格式的报文数据。前置系统接到本地业务管理系统发送的报文数据后，进行电子签名，然后转发给部级异地退管系统。同样，前置系统从部级异地退管系统查询下载报文数据后，进行验签，通过后转发给本地业务管理系统。此同步机制是异地数据交互的首选方案。业务管理系统或前置系统与部级异地退管系统在数据交互期间（可以是实时，也可是每天定时），处于实时数据交换状态，业务人员或前置系统可以在发送数据时立即获知是否传递成功，不成功的可立即下载错误文件。此机制下，前置系统功能开发内容相对较少。（2）异步转发功能。异步转发功能与同步转发基本相同。不同是，数据先在前置系统落地，再与部级异地退管系统通过同步机制交换。此机制下，业务人员或前置系统不能在发送数据时立即获知是否传递成功。前置系统需要利用后台轮询或人工触发等功能实现与部级异地退管系统的交互，开发内容相对较多。（3）数据指标转换与转发功能。本地业务管理系统产生业务指标数据，发给前置系统。前置系统将业务指标数据进行代码、格式校验后，转换为报文数据，再行签名并发送。前置系统从部级异地退管系统收到交互的报文数据后，验签并解析为业务指标数据，再传递给本地业务管理系统，这种情况下，前置系统需要部署数据库，并具备数据指标转换与解析功能，开发内容最多。另外，除上述由业务触发的直接转发模式外，在从部级异地退管系统下载数据时，前置系统也可先行统一下载数据，再供业务管理系统下的各行政区按业务权限使用数据。此时业务管理系统下的各行政区统一使用一个节点，并在业务管理系统内部设定数据访问权限。2前置系统与异地退管系统交互模式前置系统与部级异地退管系统间的数据传输和交换，遵循异地退管系统提供的接口API及规范要求。目前异地退管系统提供了TXT文件和字符流的报文机制，两种机制都是同步方式，即每次发送的报文都将即时返回结果。上传业务数据：通过金保工程业务专网，调用异地退管系统的上传接口API，将需要交换的业务数据按接口数据规范组织成报文，上传到部级异地退管系统。系统读取收到的报文，解析校验文件中的业务数据明细并保存，即时还回本次操作是否成功及错误信息。接收业务数据：通过金保工程业务专网，调用异地退管系统的下载接口API，查询并获取属于本节点接收的业务数据。异地退管系统按接口数据规范组织成字符流并下载给接收方用户。3前置系统与本地业务管理系统交互模式各地应根据本地业务管理系统的架构技术特点，选择前置系统与本地业务管理系统连接的技术方案，方便本地业务管理系统调整接口。以下提供两种架构下的建设建议：（1）C/S传统架构系统。考虑到C/S传统架构系统客户端的维护量，不建议在客户端中嵌入与前置系统的交互代码，应建立与前置系统的统一接入点。为此，建议通过数据库DBLINK等技术实现业务管理系统数据库与前置机数据库间的数据摆渡。（2）B/S/S或C/S/S架构系统。此架构下，本地业务管理系统可通过中间层直接调用前置系统接口，实现技术较多，如API、SERVICE、FILE、JMS等。（三）嵌入式接入模式此模式下，将前置模式中的同步转发功能部署在了本地业务管理系统中，其他无差别。具体参见前置模式中的描述。三、接口功能描述异地退管系统提供标准的接口功能供本地业务管理系统调用。调用方式为，在相应的业务功能点调用异地退管系统提供的API函数，将业务功能标识及所需的业务数据上传到异地退管系统（或从异地退管系统中接收下来）。API已内嵌交换数据文件在发送前的自动签名和接收后的自动验签功能。异地退管系统接口提供的业务功能如下表所示，查询条件参数见接口开发手册。（一）异地居住退休人员管理序号功能点说明功能标识入参出参1.本地在外地居住退休人员上传参保地将异地居住退休人员基本信息发送至部级异地退管系统R01011IC81数据集接口反馈代码2.外地在本地居住退休人员查询居住地通过部级异地退管系统下载异地居住退休人员基本信息R01012查询条件接口反馈代码，IC81数据集3.本地在外地居住退休人员删除上传参保地删除部级异地退管系统中本经办机构异地居住的离退休人员基本信息R01021IC97数据集接口反馈代码4.本地在外地居住供养亲属上传参保地将异地居住供养亲属基本信息发送至部级异地退管系统R02011IC82数据集接口反馈代码5.外地在本地居住供养亲属查询居住地通过部级异地退管系统下载异地居住供养亲属基本信息R02012查询条件接口反馈代码，IC82数据集6.本地在外地居住供养亲属删除上传参保地删除部级异地退管系统中本经办机构异地居住供养亲属基本信息R02021IC97数据集接口反馈代码（二）协助认证管理序号功能点说明功能标识入参出参1.协助认证通知上传(参保地)参保地将协助认证通知发送至部级异地退管系统R03011IC83数据集接口反馈代码2.协助认证通知下载(居住地)居住地通过部级异地退管系统下载协助认证通知R03012查询条件接口反馈代码，IC83数据集3.协助认证结果上传(居住地)下载协助认证通知的居住地，办理完业务后，进一步通过上传方式反馈结果，将协助认证结果发送至部级异地退管系统R03021IC84数据集接口反馈代码4.协助认证结果下载(参保地)参保地通过部级异地退管系统下载协助认证结果R03022查询条件接口反馈代码，IC84数据集（三）异地居住人员变更管理序号功能点说明功能标识入参出参1.人员变动信息上传(居住地)居住地通过上传方式，将人员变动信息发送至部级异地退管系统R04011IC85数据集接口反馈代码2.人员变动信息下载(参保地)参保地通过部级异地退管系统下载人员变动信息，以用于核实情况并进一步处理后续变更业务R04012查询条件接口反馈代码，IC85数据集（四）其他功能序号功能点说明功能标识入参出参1.撤销业务上传业务发起方对已上传的业务（业务接收方未下载时）进行撤销处理C01011AE86数据集接口反馈代码2.申请撤销业务上传业务发起方对业务接收方已下载的业务进行申请撤销处理C01021AE86数据集接口反馈代码3.申请撤销业务查询业务发起方按条件查询已上传的申请撤销业务数据；业务接收方按条件查询被申请撤销的业务数据C01022查询条件接口反馈代码，AE86数据集4.确认撤销业务上传业务接收方对业务发起方上传的申请撤销业务进行撤销确认处理C01031AE86数据集接口反馈代码5.确认撤销业务查询业务发起方按条件查询已上传的确认撤销业务数据；业务接收方按条件查询被确认撤销的业务数据C01032查询条件接口反馈代码，AE86数据集6.查询错误数据列表上传的业务数据发生错误后，查询所有错误数据的列表，具体错误信息描述文件需要再调用下载错误数据方法下载C05012查询条件接口反馈代码，AE95数据集7.下载错误数据上传的业务数据发生错误后，从服务器端下载错误信息C05022上传文件名或流标识ID错误数据文件或流8.经办机构信息查询下载各地可以查询下载全国社保机构信息（包括当前有效和历史），也可导出社保机构信息E01012查询条件接口反馈代码，AF01，AF42，AF43数据集9.机构代码同步查询全国所有经办机构行政区划代码、节点代码、入网状态信息E01022查询条件接口反馈代码，AA26数据集四、接口数据规范异地退管系统对交互的数据格式做了严格规定，三种接入模式均需按照接口数据规范组织交互的报文数据。（一）报文规范异地退管系统对外提供的接口API可支持TXT文件和字符流两种交互方式。两种方式接口的参数对象形式不同，内部的数据格式和规范完全一致。文件、字符流统称为报文。报文内部采用TXT文本格式，包含报文头、报文体（业务数据集）、报文尾三部分，具体规范如下：1报文名命名规范系统内的报文命名必须具有唯一性，业务管理系统生成报文时的命名规则如下：报文格式（1）发起方行政区划代码（6）生成时间（8）报文序号（6）功能标识（6）报文类型（1）（1）报文名称的长度为28位；（2）报文名称只能由英文字母和数字组成；（3）报文不采用压缩格式；（4）报文名称（格式：FAAAAAAYYYYMMDDNNNNNNRRRRRRT）的组成结构为：第1位（F）：报文格式，1表示TXT；第27位（AAAAAA）：发起方行政区划代码，只能等于6位长度； 第815位（YYYYMMDD）：生成文件的日期；第1621位（NNNNNN）：生成报文的序号，对同一发送方同一天的多个报文应不相同，即每日唯一，从000001开始递增；第2227位（RRRRRR）：功能标识的编号（R01011/R01012/R01021等）；第28位（T）：报文类型，0表示正确数据报文，1表示数据格式错误报文，2表示业务逻辑错误报文，9表示系统错误报文。2报文头规范数据的开头两行要求加入报文头数据集，以“HEAD”标识，包含的数据项如下：名称长度值含义（作用）报文版本号201 标明报文所包含的数据集版本，当前版本号为01日期8文件生成日期日期数据格式统一为YYYYMMDD功能标识6R01011/R01012/R03021等用于标明文件内数据所属的功能类型发送人6发起方的行政区划代码本次记录数本报文包含的记录数（不含报文头、数据集名称、报文尾），最大5000条（本地在外地居住的退休人员和本地在外地居住的供养亲属最大200000条），从1开始编写记录总数需要传输的总记录数，大于等于本次传输记录数，从1开始编写行政区划版本号10当前最新的经办机构行政区划代码的版本号，从1开始编写3报文体规范（1）业务数据集封装格式报文体是业务数据。一个报文可由一个或多个不同的数据集组成，每个数据集由一到多条信息记录构成。不同的数据集表示不同类的业务数据，同一数据集之间的数据记录结构相同。 每次交互的数据至少包括一个数据集，数据集用数据集名称标识，数据集与信息记录之间加入一个换行符（“n”）； 每行信息记录的数据项之间采用“|”分隔，数据项的值为空时也要有该数据项的占位信息（即表示为“|”，中间无空格，空格将被视为具体的值来对待）；数据项为变长数据，前后不应有空格，只写数据项本身的内容； 每行信息记录数据项的顺序（位置）与接口指标说明对应业务指标说明中的序号一致； 在每行信息记录数据的最后一个数据项之后跟一个换行符（“n”），即各条信息记录之间用换行符分隔； 信息记录的内容包含特殊字符时，需要进行转义：l “|”转义为“&vl;”l “换行符(n)”转义为”&nl;”l “&”转义为”&” 报文体中的汉字应使用GBK中文字符集。（2）业务数据集列表序号数据集编码数据集名称使用业务环节数据集内容使用方向1.IC81外地在本地居住退休人员信息异地居住退休人员见接口指标说明上传、查询下载2.IC82外地在本地居住供养亲属信息异地居住供养亲属见接口指标说明上传、查询下载3.IC83协助认证通知协助认证通知见接口指标说明上传、查询下载4.IC84协助认证结果协助认证结果见接口指标说明上传、查询下载5.IC85人员信息变更通知人员信息变更通知见接口指标说明上传、查询下载6.IC97删除上传信息异地居住退休人员删除上传、异地居住供养亲属删除上传见接口指标说明上传7.AE86业务撤销信息撤销业务、申请撤销业务、确定撤销业务见接口指标说明上传、查询下载8.AE90下载确认信息下载确认业务见接口指标说明上传9.AF01、AF42、AF43经办机构信息机构信息查询见接口指标说明查询下载10.AA26机构行政区划代码信息机构行政区划代码同步见接口指标说明查询下载11.AE80、AE81业务状态信息业务状态查询见接口指标说明查询下载12.AE95错误数据列表信息查询错误数据列表见接口指标说明查询下载上表1-5类业务数据集在查询时，返回内容比上传时增加了一个业务环节状态字段，表示此数据集在当前业务环节的处理状态（包括已上传、已下载、申请撤销、已撤销、已注销）。4报文尾规范采用“SITRBEND”10位字符的数据尾标识报文结束。（二）错误信息格式在用户通过远程登录或者后台接口上传业务文件后，异地退管系统将根据报文规范、数据格式要求、业务逻辑要求进行校验（报文校验规则参见附表2，数据格式和业务逻辑校验规则参见附表3）。若发生错误，会在上传界面或者接口返回值中报告错误，并产生错误描述文件。异地退管系统可返回三种错误描述文件，分别是数据格式校验错误文件，业务逻辑校验错误文件和系统错误。三种错误的错误信息格式各不相同，分别说明如下：1数据格式错误此类错误属于客户端构造上传文件时的技术错误，整个报文将被退回。反馈的错误信息文件是自然语言描述的错误信息，供技术人员人工阅读排查错误。具体包括三类情况：（1）报文头格式或者内容错误。如报文头的字段数量不符合规则，记录数超过限制等。此时错误文件仅返回一行错误信息，不会继续解析后续的数据内容。（2）某行数据集的指标数量不正确。此时会返回错误的数据集行数，以及错误信息。（3）数据集内某一指标的格式不正确。此时通过姓名、个人编号、社会保障号码等定位记录，返回数据集中错误值以及错误具体描述。反馈地方的数据格式错误文件，报文名的最后一位为“1”。2业务逻辑错误格式数据格式校验通过后，部级异地退管系统会进行业务逻辑校验。同一个上传报文可以包含多个业务数据，系统进行分别处理。校验通过的人员记录入库，进入后续业务处理，校验不通过的人员记录会生成错误文件返回，提示上传方进行相应的业务异常处理。每条错误信息数据集为原数据集原记录数据内容后增加两个错误信息指标，分别是错误代码和错误信息描述。地方的接口程序可根据错误代码自动判读并进行后续错误处理。反馈地方的业务逻辑错误文件，报文名的最后一位为“2”。错误代码及描述见接口开发手册。3系统错误格式在上传入库过程中如果发生了不可预知的系统错误，会返回系统错误信息，内容一般为服务器端的错误信息以及相应的错误跟踪信息。这些信息用于定位和解决不可预知的系统异常，需要由系统管理维护人员解读和处理。反馈地方的系统错误文件，报文名的最后一位为“9”。（三）报文示例1单数据集报文示例（1）上传数据集示例，太原上传协助认证通知信息如下所示：报文名：114019920100426000001R030110HEAD01|20110110|R03011|140199|1|1|130IC831294641218921000|140199|140299|140199140299010000|140199010000|140199140299000000|太原到大同0|1|140101350101356|19350101|户口所在地地址0|异地居住地址0|100091|01089674523|0|参保地社保机构名称0|01089674523|01089674523|参保地社保机构地址0|100092|联系人0|1|20110110|20110331|经办人0|20100929|协助认证通知备注0SITRBEND（2）查询返回数据集示例，大同查询太原传来的需本地协助认证的协助认证通知信息，如下所示：报文名：114029920100426000001R030120HEAD01|20110110|R03012|140299|1|1|130IC831294641218921000|140199|140299|140199140299010000|140199010000|140199140299000000|太原到大同0|1|140101350101356|19350101|户口所在地地址0|异地居住地址0|100091|01089674523|0|参保地社保机构名称0|01089674523|01089674523|参保地社保机构地址0|100092|联系人0|1|20110110|20110331|经办