人力資源社會(huì)保障業(yè)務(wù)協(xié)同平臺(tái)接口規(guī)范

1人力資源社會(huì)保障業(yè)務(wù)協(xié)同平臺(tái)接口規(guī)范本文件規(guī)定了人力資源社會(huì)保障業(yè)務(wù)協(xié)同平臺(tái)的集成對(duì)接要求、接口定義要求和接口安全要求。本文件適用于各類信息系統(tǒng)接入人力資源社會(huì)保障業(yè)務(wù)協(xié)同平臺(tái)的服務(wù)接口的設(shè)計(jì)開發(fā)。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款，其中，注日期的引用文件，僅該日期對(duì)應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本(包括所有的修改單)適用于本文件。GB/T2260中華人民共和國行政區(qū)劃代碼GB/T39786—2021信息安全技術(shù)信息系統(tǒng)密碼應(yīng)用基本要求LD/T02.2—2022人力資源社會(huì)保障電子認(rèn)證體系規(guī)范第2部分：電子認(rèn)證系統(tǒng)技術(shù)規(guī)范3術(shù)語和定義下列術(shù)語和定義適用于本文件。業(yè)務(wù)協(xié)同平臺(tái)businesscollaborationplatform人力資源社會(huì)保障部為實(shí)現(xiàn)跨系統(tǒng)、跨地區(qū)數(shù)據(jù)交換、業(yè)務(wù)協(xié)同所開發(fā)的基礎(chǔ)支撐平臺(tái)軟件系統(tǒng)。信息系統(tǒng)之間通過調(diào)用服務(wù)接口實(shí)現(xiàn)相應(yīng)業(yè)務(wù)要求的事務(wù)處理單元。調(diào)用方servicecaller服務(wù)發(fā)起方，通過業(yè)務(wù)協(xié)同平臺(tái)調(diào)用服務(wù)接口、請(qǐng)求交易的信息系統(tǒng)。服務(wù)提供方，通過業(yè)務(wù)協(xié)同平臺(tái)提供股務(wù)接口、返回交易響應(yīng)數(shù)據(jù)的信息系統(tǒng)。調(diào)用方(3.3)發(fā)起請(qǐng)求中包含的具體數(shù)據(jù)，由報(bào)文頭和報(bào)文體兩部分組成。服務(wù)方(3.4)接受請(qǐng)求報(bào)文，處理對(duì)應(yīng)的事務(wù)后，返回調(diào)用方(3.3)的數(shù)據(jù)信息，由報(bào)文頭和報(bào)文體兩部分組成。下列縮略語適用于本文件JS0N:JavaSeript對(duì)象簡譜，一種輕量級(jí)的數(shù)據(jù)交換格式(JavaSeript0bjeetNotation)2Nonce:被使用一次的非重復(fù)的隨機(jī)數(shù)值(NumberREST:表述性狀態(tài)傳遞(RepresentationalStateSSL:安全套接字協(xié)議(SecureSocketsLayer)UTF-8:8比特萬國碼的可變長度字符編碼(8-bitUnicodeTransformationFormat)5對(duì)接要求依托業(yè)務(wù)協(xié)同平臺(tái)實(shí)現(xiàn)的數(shù)據(jù)交換、業(yè)務(wù)協(xié)同均在人力資源社會(huì)保障業(yè)務(wù)專網(wǎng)(國家電子政務(wù)外網(wǎng))環(huán)境下實(shí)現(xiàn)。5.2交易約束人力資源社會(huì)保障信息系統(tǒng)之間通過業(yè)務(wù)協(xié)同平臺(tái)開展交易，遵循統(tǒng)一的通訊協(xié)議、數(shù)據(jù)格式規(guī)范業(yè)務(wù)協(xié)同平臺(tái)支持使用HTTP協(xié)議傳輸報(bào)文，統(tǒng)一采用RESTful風(fēng)格的服務(wù)調(diào)用，報(bào)文內(nèi)容參數(shù)采用JSON格式，報(bào)文編碼采用UTF-8。5.3信息系統(tǒng)編碼業(yè)務(wù)協(xié)同平臺(tái)為調(diào)用方和服務(wù)方分配統(tǒng)一的信息系統(tǒng)編碼，用于唯一標(biāo)識(shí)相互通訊的信息系統(tǒng)，便于監(jiān)控、管理系統(tǒng)服務(wù)情況信息系統(tǒng)編碼由十一位字符組成，包含信息系統(tǒng)的部署層級(jí)、所屬地區(qū)和隨機(jī)字符，格式為：a)“Y”為部、省漢語拼音首字母(B或S),“B”表示部級(jí)信息系統(tǒng)，“S”表示省級(jí)信息系b)“XXXXXX”為信息系統(tǒng)部署的部省級(jí)節(jié)點(diǎn)的行政區(qū)劃代碼，部級(jí)節(jié)點(diǎn)的行政區(qū)劃代碼為“100000”,省級(jí)節(jié)點(diǎn)的行政區(qū)劃代碼遵循GB/T2260,如北京市的編碼為“110000”:c)“NNN”為隨機(jī)字符，格式為四位隨機(jī)數(shù)字或大小寫字母。 在共享協(xié)同過程中，對(duì)于調(diào)用方和服務(wù)方達(dá)成一致的交易，調(diào)用方基于信息系統(tǒng)編碼生成業(yè)務(wù)請(qǐng)求流水號(hào)，唯一識(shí)別每一個(gè)交易請(qǐng)求；服務(wù)方基于信息系統(tǒng)編碼生成業(yè)務(wù)響應(yīng)流水號(hào)，唯一識(shí)別每一個(gè)交易反饋。5.4平臺(tái)對(duì)接管理業(yè)務(wù)協(xié)同平臺(tái)采用部省兩級(jí)部署模式，省級(jí)人力資源社會(huì)保障部門負(fù)責(zé)平臺(tái)節(jié)點(diǎn)的本地部署和運(yùn)行維護(hù)。部省兩級(jí)平臺(tái)管理人員負(fù)責(zé)信息系統(tǒng)在平臺(tái)的注冊(cè)，協(xié)助服務(wù)方發(fā)布共享協(xié)同(服務(wù)接口)資源管理資源的可見范圍和可用范圍。調(diào)用方通過業(yè)務(wù)協(xié)同平臺(tái)查詢共享協(xié)同(服務(wù)接口)資源目錄，申請(qǐng)所需的資源(服務(wù)接口),平臺(tái)管理人員協(xié)助服務(wù)方完成審核和授權(quán)。6接口定義要求6.1接口編碼接口編碼為信息系統(tǒng)作為服務(wù)方時(shí)所提供的服務(wù)接口的唯一標(biāo)識(shí)，由十五位字符組成，包含服務(wù)接口的提供方和隨機(jī)字符，格式為：“信息系統(tǒng)編碼+YYYY”。其中：a)信息系統(tǒng)編碼規(guī)則見5.3;b)“YYYY”為隨機(jī)字符，格式為四位隨機(jī)數(shù)字或大小寫字母6.2.1交易報(bào)文構(gòu)成交易報(bào)文結(jié)構(gòu)業(yè)務(wù)協(xié)同平臺(tái)交易報(bào)文分為請(qǐng)求報(bào)文、響應(yīng)報(bào)文兩類，均包括報(bào)文頭(header)和報(bào)文體(body)兩個(gè)部分。請(qǐng)求報(bào)文報(bào)文頭用于對(duì)所有接入業(yè)務(wù)協(xié)同平臺(tái)的信息系統(tǒng)進(jìn)行鑒權(quán)、路由和統(tǒng)計(jì)，包含以下參數(shù)：a)服務(wù)方接口編碼(serviceCode):b)調(diào)用方信息系統(tǒng)編碼(appCode):c)服務(wù)方所在區(qū)域代碼(serviceAreaCode);d)業(yè)務(wù)請(qǐng)求流水號(hào)(serviceReqId);e)業(yè)務(wù)請(qǐng)求時(shí)間(serviceReqTime);.2請(qǐng)求報(bào)文體報(bào)文體傳入調(diào)用方的請(qǐng)求數(shù)據(jù)或服務(wù)方的響應(yīng)數(shù)據(jù)。.3請(qǐng)求報(bào)文結(jié)構(gòu)請(qǐng)求報(bào)文的結(jié)構(gòu)見表1。(字行數(shù))是是6是是規(guī)則為：“調(diào)用方信息系統(tǒng)代碼+8位日期+9位流水號(hào)”,請(qǐng)求流水號(hào)不能重復(fù)是否(字符數(shù))由服務(wù)方確定簽名算法并簽發(fā)公切.若服/是響應(yīng)報(bào)文.1響應(yīng)報(bào)文頭報(bào)文頭用于對(duì)所有接入業(yè)務(wù)協(xié)同平臺(tái)的信息系統(tǒng)進(jìn)行鑒權(quán)、路由和統(tǒng)計(jì)，包含以下參數(shù)a)服務(wù)方接口編碼(serviceCode):b)調(diào)用方信息系統(tǒng)編碼(appCode):c)服務(wù)方所在區(qū)域代碼(serviceAreaCode):d)業(yè)務(wù)請(qǐng)求流水號(hào)(serviceReqId):e)業(yè)務(wù)請(qǐng)求時(shí)間(serviceReqTime)g)服務(wù)方業(yè)務(wù)響應(yīng)時(shí)間(serviceResTine):h)服務(wù)方業(yè)務(wù)響應(yīng)狀態(tài)(commstatus);.2響應(yīng)報(bào)文體同.2。.3響應(yīng)報(bào)文體結(jié)構(gòu)響應(yīng)報(bào)文的結(jié)構(gòu)見表2。表2業(yè)務(wù)協(xié)同平臺(tái)響應(yīng)報(bào)文結(jié)構(gòu)(字符數(shù))是是6是“100000”,服務(wù)方信息系統(tǒng)所在地區(qū)的行是是是“服務(wù)方信息系統(tǒng)代碼+8位日期+9位流是2是(字符數(shù))3否否是交易報(bào)文示例服務(wù)方業(yè)務(wù)成功交易報(bào)文樣例和業(yè)務(wù)異常交易報(bào)文樣例見示例。示例1:"serviceCode":"s110000Y7TappCode":"B100000KJ"serviceAreaCode”:""serviceReqld”:"B100000KJGK2017012210serviceBoqTine":“2017012"serviceBosTine":"20190618"serviceResld”:"S110000Y70P20190618100nsg":“成功”aac002°:4401011*中(+909"serviceCode":"s110000Y70PYTjb"servicehegId?:“B100000KJGK2017012210servicefeqTime":"201701"serviceBesTime":”20190618165713”serviceResId":"S110000Y70P201906181nsg":“調(diào)用失敗”66.2.2報(bào)文體設(shè)計(jì)對(duì)象類型普通請(qǐng)求.1請(qǐng)求報(bào)文對(duì)象類型普通請(qǐng)求是指輸入查詢條件，獲取查詢結(jié)果數(shù)據(jù)。如社會(huì)保障卡狀態(tài)查詢，查詢條件包含社會(huì)保障號(hào)碼、姓名。請(qǐng)求報(bào)文格式見示例。"serviceCode":"S110000Y"appCode":"B100000KJGK"serviceReqId*:“B100000KJGK201701221"serviceReqTine":”2017012"aac003":“張中”,"onc002”:“4401011****注1:anc003為請(qǐng)求條件“姓名”注2:aac002為請(qǐng)求條仕“社會(huì)保障號(hào)碼”對(duì)象類型普通請(qǐng)求一般返回一個(gè)對(duì)象數(shù)據(jù)，即一個(gè)JSON對(duì)象，返回結(jié)果可以放置在對(duì)象報(bào)文中。響應(yīng)報(bào)文格式見示例。"serviceCode":"s110000Y"serviceAreaCode":"110000"servicefeqId":"B100000KJGK20170122100000001"servicelioqTime":”20170122serviceResTime”:"201906"serviceResld*:"S110000Y70P2019061810msg":“成功”b"anc002°:"4401011****9)對(duì)象類型分頁請(qǐng)求對(duì)象類型分頁請(qǐng)求是根據(jù)業(yè)務(wù)場(chǎng)景需要，除請(qǐng)求條件外，還需要將請(qǐng)求頁碼、每頁記錄數(shù)等信息一同提交。如個(gè)人簡歷情況查詢，請(qǐng)求條件為社會(huì)保障號(hào)碼、姓名。請(qǐng)求報(bào)文格式見示例。"serviceCode?:"S110000Y70PYTjb”appCode":"B100000KJCX”."serviceAreaCode”:"serviceReqId*:B100000KJGK201701221"serviceReqTine”:“20170121"aac003°:“張*”"aac002":4401011****注1:aac003為請(qǐng)求條件“姓名”注2:aac002為請(qǐng)求條件“社會(huì)保障號(hào)碼”注3:cpage為當(dāng)前頁碼，注4:rows為每頁數(shù)量、.2響應(yīng)報(bào)文對(duì)象類型分頁請(qǐng)求通常返回多個(gè)對(duì)象數(shù)據(jù)，應(yīng)標(biāo)記返回對(duì)象數(shù)量、分頁參數(shù)，將返回結(jié)果存放在“l(fā)ist”中。響應(yīng)報(bào)文格式見示例。'serviceCode":"s110000Y70PserviceReqld”:"B100000KJGK201701221serviceReqTine”:"2017012210102serviceRosTine:“2019061"serviceResId”:"s110000170P2019061810nsg”:“成功”{"aac002":“4401011****9aac003”:“張*”,.aac002”:"4401011****909aac003”:”張*”aab004”:”杭州公司”aac031*:”2015年03月1日”數(shù)組類型批量請(qǐng)求數(shù)組類型批量請(qǐng)求一般用于一次性請(qǐng)求多條記錄。對(duì)于數(shù)組類請(qǐng)求條件，需要將請(qǐng)求條件存放在“l(fā)ist”中。如一次性查詢多人社會(huì)保障卡狀態(tài)，請(qǐng)求條件包含社會(huì)保障號(hào)碼、姓名。請(qǐng)求報(bào)文見示例"serviceCode”?"s1100007serviceAreaCode":"11000serviceReqTd':"B100000KJG8201701221servicoReqTino":“201701"aac002”:"4401011****"aac002”:"4352311994aac0037:“李*”].2響應(yīng)報(bào)文若存在一次批量請(qǐng)求需要返回多組結(jié)果，則使用業(yè)務(wù)系統(tǒng)定義的對(duì)象標(biāo)識(shí)分級(jí)拼接。如查詢一個(gè)人的檔案信息，其返回結(jié)果包含該人員的基本信息、特殊工種、工作經(jīng)歷等。響應(yīng)報(bào)文見示例。serviceCode":'s110000appCode":“B100000XJCX*."serviceReqld":"B100000KJGK2017012210"serviceReqTine”:"2017012serviceResTin”:“201906"serviceResld”:"S110000170P20190618100nsg”:”成功”"aac002”:“4401011***+9"aab004":“北京市***公司”aae0307:“2010年03月*日”ae031°:“2013年03月**日”aab004””杭州***公司”aac0197:“1”.aa0030°:"2013年03月日","aac031":“2015年03月*日”)注2:list用于存放響應(yīng)結(jié)果的數(shù)組，數(shù)組中可以注4:workHistory為業(yè)務(wù)系統(tǒng)定文7接口安全要求7.1安全機(jī)制7.1.1訪問安全報(bào)文加密解密為保證報(bào)文傳輸?shù)陌踩?，防止?shù)據(jù)被偷窺、泄露，采用軟加密的方式，在調(diào)用方發(fā)送報(bào)文之前，先對(duì)報(bào)文體(body)中待傳入的參數(shù)使用對(duì)稱加密算法的密鑰或者非對(duì)稱加密算法的公鑰進(jìn)行加密，再將密文傳入報(bào)文體(body)中。服務(wù)方使用對(duì)稱加密算法的密鑰或者非對(duì)稱加密算法的私鑰進(jìn)行解密得到明文數(shù)據(jù)。使用5M4分組密碼算法對(duì)報(bào)文進(jìn)行加密、解密過程：a)調(diào)用方使用SW4算法的ECB模式，密鑰(key)為16位純數(shù)字，對(duì)報(bào)文體(body)參數(shù)進(jìn)行加密，加密后的請(qǐng)求報(bào)文結(jié)構(gòu)見示例1:b)服務(wù)方使用密鑰進(jìn)行解密，獲取請(qǐng)求報(bào)文原文：c)服務(wù)方返回報(bào)文之前，對(duì)報(bào)文體(body)中響應(yīng)數(shù)據(jù)使用為調(diào)用方分配的16位純數(shù)字密鑰、同樣采用SM4算法的ECB模式進(jìn)行對(duì)稱加密，返回給調(diào)用方，加密后的響應(yīng)報(bào)文結(jié)構(gòu)見示例2;d)調(diào)用方使用密鑰(key)進(jìn)行解密，獲取原文。“GM/T0002-2012(SM4分組密碼算法》”"serviceCode":"S1100007serviceReqId”:"B100000KJGK20170122100000001”"serviceReqTino":2017012body“:”請(qǐng)求數(shù)據(jù)使用SW4算法加密后密文”示例2:"serviceCode":"s110000"serviceAreaCode":""servlcekegld":"B100000KJCX20170122100servicekeqTine":"2017012"serviceResTine":"2019061"serviccResId":"s110000Y70P20190618100msg":”成功”bods?:”響應(yīng)數(shù)據(jù)使用SNM算法加使用SM2橢圓曲線公鑰密碼算法對(duì)報(bào)文進(jìn)行加密、解密過程：a)調(diào)用方使用服務(wù)方分配的SM2算法的公鑰對(duì)報(bào)文體(body)參數(shù)進(jìn)行加密，加密后的請(qǐng)求報(bào)文結(jié)構(gòu)見示例3;b)服務(wù)方使用密鑰進(jìn)行解密，獲取請(qǐng)求報(bào)文原文：c)服務(wù)方接收到請(qǐng)求報(bào)文后，使用與為調(diào)用方分配的公鑰相配對(duì)的私鑰對(duì)報(bào)文體(body)參數(shù)進(jìn)行解密。服務(wù)方返回報(bào)文之前，對(duì)報(bào)文體(body)中響應(yīng)數(shù)據(jù)使用私鑰進(jìn)行加密，返回給調(diào)用方，加密后的響應(yīng)報(bào)文結(jié)構(gòu)見示例4;d)調(diào)用方使用公鑰進(jìn)行解密，獲取原文。示例3:"serviceCode":"S110000Y"serviceReqld":"B100000KJGK2017012210"serviceReqTine":”20170122body”:"請(qǐng)求數(shù)據(jù)使用SM2算法公鑰加密示例4:"serviceCode?:"S110000Y"serviceAreaCode”:"serviceReqId*:“B100000KJGK20170122100000001”"serviceReqTine":“20170122"serviceResld”:"S110000170P2019061810nsg":“成功”數(shù)字簽名驗(yàn)簽為保證報(bào)文傳輸?shù)耐暾?，防篡改、抵賴，?duì)報(bào)文頭(header)中的參數(shù)進(jìn)行簽名。以使用SM3密碼雜湊算法對(duì)報(bào)文頭參數(shù)進(jìn)行數(shù)字簽名、驗(yàn)簽過程為例。a)調(diào)用方對(duì)報(bào)文頭(header)中的參數(shù)使用SM3算法進(jìn)行加密，將加密結(jié)果作為數(shù)字簽名。過程如下：1)調(diào)用方對(duì)報(bào)文頭(header)中的參數(shù)以首字母的ASCII碼進(jìn)行升序排列，使用“&”字符進(jìn)行拼接，為防止重放攻擊，拼接過程中添加Nonce參數(shù)(見示例1);2)對(duì)拼接后的內(nèi)容，使用SX3算法進(jìn)行加密，并將加密結(jié)果傳入報(bào)文頭(header)中的數(shù)b)服務(wù)方按照同樣的方式對(duì)請(qǐng)求報(bào)文頭(header)中參數(shù)進(jìn)行數(shù)字簽名，將簽名結(jié)果與請(qǐng)求報(bào)文頭(header)中的數(shù)字簽名參數(shù)(signature)進(jìn)行比對(duì)驗(yàn)簽appCode=S110000