ICS35.200CCSL7014IDB14/T3024—2024前言 2規(guī)范性引用文件 3術(shù)語和定義 4接口類型 5接口調(diào)用 26接口描述 37安全要求 DB14/T3024—2024本文件按照GB/T1.1—2020《標(biāo)準(zhǔn)化工作導(dǎo)則第1部分：標(biāo)準(zhǔn)化文件的結(jié)構(gòu)和起草規(guī)則》的規(guī)定起草。本文件由山西省財政廳提出、組織實施和監(jiān)督檢查。山西省市場監(jiān)督管理局對標(biāo)準(zhǔn)的組織實施情況進(jìn)行監(jiān)督檢查。本文件由山西省財政標(biāo)準(zhǔn)化技術(shù)委員會（SXS/TC48）歸口。本文件起草單位：山西省財政科學(xué)研究院、山西寶佳質(zhì)量基礎(chǔ)研究院（有限合伙）。本文件主要起草人：葛強、任巍英、張寶林、韓慧彥、李林駿、張素娥、董阿敏、徐維迪、李斌、石鑫。1DB14/T3024—2024惠民惠農(nóng)財政補貼資金"一卡通"服務(wù)平臺與代發(fā)銀行接口規(guī)范本文件規(guī)定了惠民惠農(nóng)財政補貼資金“一卡通”服務(wù)平臺（以下簡稱“一卡通平臺”）與代發(fā)銀行的接口類型、接口調(diào)用、接口描述和安全要求。本文件適用于代發(fā)銀行接入一卡通平臺的設(shè)計、開發(fā)和應(yīng)用。2規(guī)范性引用文件本文件沒有規(guī)范性引用文件。3術(shù)語和定義下列術(shù)語和定義適用于本文件。3.1代發(fā)銀行省、市、縣（市、區(qū)）區(qū)域內(nèi)，依法設(shè)置的各項財政補貼資金委托代發(fā)銀行。4接口類型一卡通平臺與代發(fā)銀行接口包括BT001身份登錄接口、YH008單筆銀行賬號驗證接口、YH010批量銀行賬號驗證接口、BT009銀行賬號驗證結(jié)果接收接口、YH005補貼明細(xì)接收接口、BT006上卡結(jié)果接收接口、YH011查詢銀行工作狀態(tài)接口、YH012獲取銀行回盤文件接口，接口類型如表1所示。表1接口類型賬號（賬戶名，證件號碼，銀行賬號）信息，驗證準(zhǔn)賬號信息，驗證準(zhǔn)確性后通過接口BT009返回驗證結(jié)果該接口由代發(fā)銀行建設(shè)，由一卡通平臺調(diào)用，傳遞銀行2DB14/T3024—2024表1接口類型（續(xù)）該接口由一卡通平臺建設(shè)，由代發(fā)銀行調(diào)用，用中、驗卡進(jìn)行中、驗卡結(jié)束；未啟動發(fā)放、發(fā)放5接口調(diào)用一卡通平臺與代發(fā)銀行使用各數(shù)據(jù)接口，經(jīng)過身份認(rèn)證、信息驗證、補貼發(fā)放、銀行狀態(tài)查詢、獲取銀行回盤文件五個步驟實現(xiàn)惠民惠農(nóng)財政補貼資金的發(fā)放，各接口調(diào)用如附錄A圖A.1所示，各階段接口調(diào)用方式如下：——身份認(rèn)證：銀行調(diào)用“BT001身份登錄接口”進(jìn)行身份認(rèn)證，認(rèn)證通過后完成后續(xù)階段業(yè)務(wù)；——信息驗證：一卡通平臺調(diào)用“YH008單筆銀行賬號驗證接口”推送單筆銀行賬號信息，銀行驗證準(zhǔn)確性后同步返回驗證結(jié)果；一卡通平臺調(diào)用“YH010批量銀行賬號驗證接口”推送批量銀行賬號信息，銀行驗證準(zhǔn)確性后，調(diào)用“BT009銀行賬號驗證結(jié)果接收接口”返回驗證結(jié)果；——補貼發(fā)放：一卡通平臺調(diào)用“YH005補貼明細(xì)接收接口”推送補貼對象明細(xì)信息，銀行發(fā)放結(jié)束后，調(diào)用“BT006上卡結(jié)果接收接口”返回發(fā)放結(jié)果；——銀行狀態(tài)查詢：一卡通平臺推送成功至銀行后，調(diào)用“YH011查詢銀行工作狀態(tài)接口”，查詢某批次賬號驗證或補貼發(fā)放狀態(tài)；——獲取銀行回盤文件：當(dāng)一卡通平臺網(wǎng)絡(luò)出現(xiàn)問題，銀行未能成功生成回盤詳情文件時，一卡通平臺調(diào)用“YH012獲取銀行回盤文件接口”，令銀行再次生成回盤詳情文件，并讀取詳情文件更新數(shù)據(jù)。3DB14/T3024—2024圖1接口調(diào)用方式6接口描述6.1通用要求6.1.1數(shù)據(jù)類型接口參數(shù)數(shù)據(jù)類型包括數(shù)值型（number）和字符型（string）兩種。4DB14/T3024—20246.1.2數(shù)據(jù)格式接口之間數(shù)據(jù)傳輸采用JSON數(shù)據(jù)格式。6.1.3消息結(jié)構(gòu)組成由消息頭和消息體組成。消息頭格式如表2所示；消息體由head與data組成，head包含唯一標(biāo)識、日期、銀行聯(lián)行號等通用字段，如表3所示，data對應(yīng)不同接口功能性字段，詳見本章各接口請求參數(shù)。表2消息頭格式表3消息體head格式返回消息碼.1數(shù)據(jù)返回編碼如表4所示。表4數(shù)據(jù)返回編碼表 --5DB14/T3024—2024表4數(shù)據(jù)返回編碼表（續(xù)）----.2接口調(diào)用返回編碼如表5所示。表5接口調(diào)用返回編碼表NoContent- 6.1.4調(diào)用策略接口調(diào)用策略包括：——超時時間：在與接口進(jìn)行通信時，時間限制為20秒；——調(diào)用次數(shù)：無限制。6.2參數(shù)要求6.2.1BT001身份登錄接口接口參數(shù)如表6所示。6DB14/T3024—2024表6BT001身份登錄接口回結(jié)果時，uuid為調(diào)用請求報文中的uuidmsg6.2.2YH008單筆銀行賬號驗證接口接口參數(shù)如表7所示。表7YH008單筆銀行賬號驗證接口銀行接收來自一卡通平臺的單筆銀行賬號（賬戶名，證件號碼，銀行賬號）信息，驗證準(zhǔn)確性后同7DB14/T3024—2024表7YH008單筆銀行賬號驗證接口（續(xù)）驗證結(jié)果（-1-驗證不通過；0-未驗證；6.2.3YH010批量銀行賬號驗證接口接口參數(shù)如表8所示。表8YH010批量銀行賬號驗證接口api/bank/acceptValidat8DB14/T3024—2024表8YH010批量銀行賬號驗證接口（續(xù)）接口說明如下：——文件說明：批量銀行賬號文件用于存儲一卡通平臺的批量銀行賬號信息，其命名方式為：接口編碼_CallUser_AreaCode+To+BankNo+_+uuid+.txt，其中uuid須與銀行賬號驗證結(jié)果文件名中的uuid一致；示例：YH010_1501511014336_140000000000To101——文件格式：字段通過@|$分隔，行通過\n分隔；——文件行數(shù)：最大10萬筆；——文件字段說明如表9所示。表9批量銀行賬號文件字段NN-N-N-Y-Y-6.2.4BT009銀行賬號驗證結(jié)果接收接口接口參數(shù)如表10所示。表10BT009銀行賬號驗證結(jié)果接收接口/api/bank/payRes/validate9DB14/T3024—2024表10BT009銀行賬號驗證結(jié)果接收接口（續(xù)）接口說明如下：——文件說明：銀行賬號驗證結(jié)果文件用于存儲銀行返回賬號信息驗證結(jié)果，其命名方式為：接口編碼_CallUser_BankNo+To+AreaCode+_+uuid+.txt,其中uuid須與批量銀行賬號文件名中的uuid一致；示例：BT009_1501511014336_101000000000To14000——文件格式：字段通過@|$分隔，行通過\n分隔；——文件行數(shù)：最大10萬筆；——文件字段說明如表11所示。表11銀行賬號驗證結(jié)果文件字段NN-N-N-2N3YYY-Y 6.2.5YH005補貼明細(xì)接收接口接口參數(shù)如表12所示。DB14/T3024—2024表12YH005補貼明細(xì)接收接口fileName接口說明如下：——文件說明：補貼明細(xì)文件用于存儲一卡通平臺向銀行傳輸上卡明細(xì)數(shù)據(jù)，其命名方式為：接口編碼_CallUser_AreaCode+To+BankNo+_+uuid+.txt,其中uuid須與代發(fā)銀行上卡結(jié)果文件名中的uuid一致；示例：YH005_1501511014336_140000000000To101——文件格式：字段通過@|$分隔，行通過\n分隔；——文件行數(shù)：最大10萬筆；——文件字段說明如表13所示。表13補貼明細(xì)文件字段NN DB14/T3024—2024表13補貼明細(xì)文件字段（續(xù)）N-N單位：分N-1NYYY Y-6.2.6BT006上卡結(jié)果接收接口接口參數(shù)如表14所示。表14BT006上卡結(jié)果接收接口/api/bank/payRes/resultFfileNameDB14/T3024—2024表14BT006上卡結(jié)果接收接口（續(xù)）接口說明如下：_CallUser_BankNo+To+AreaCode+_+uuid+.txt，其中uuid須與補貼明細(xì)文件文件名中的uuid一致；示例：BT006_1501511014336_101000000000To140——文件格式：字段通過@|$分隔，行通過\n分隔；——文件行數(shù)：最大10萬筆；——文件字段說明如表15所示。表15上卡結(jié)果文件字段NN N N單位：分N-1NYY1N3YYY-Y-6.2.7YH011查詢銀行工作狀態(tài)接口接口參數(shù)如表16所示。DB14/T3024—2024表16YH011查詢銀行工作狀態(tài)接口6.2.8YH012獲取銀行回盤文件接口接口參數(shù)如表17所示。表17YH012獲取銀行回盤文件接口一卡通平臺主動向銀行獲取回盤文件，防止接收數(shù)據(jù)DB14/T3024—2024表17YH012獲取銀行回盤文件接口（續(xù)）7安全要求7.1基礎(chǔ)策略7.1.1網(wǎng)絡(luò)層采用IP和端口進(jìn)行限制：采用IP白名單只允許特定的IP地址和端口號訪問API接口，以防止未授權(quán)的訪問和攻擊。7.1.2協(xié)議層采用HTTPS傳輸協(xié)議：使用HTTPS協(xié)議對數(shù)據(jù)進(jìn)行加密，并使用SSL證書驗證服務(wù)器身份，以保證數(shù)據(jù)傳輸?shù)陌踩浴?.2數(shù)據(jù)加密采用SM4算法對敏感數(shù)據(jù)進(jìn)行加密，保障數(shù)據(jù)安全。7.3數(shù)據(jù)完整性為了確保數(shù)據(jù)在傳輸過程中的完整性和真實性，采用以下方式：——使用HTTPS協(xié)議：通過使用HTTPS協(xié)議，所有的數(shù)據(jù)在傳輸過程中都會被加密，防止數(shù)據(jù)被竊取或篡改。確保數(shù)據(jù)傳輸?shù)臋C密性和完整性；——接口參數(shù)約定：通過制定接口參數(shù)的約定，確保數(shù)據(jù)在傳輸過程中不被修改。定義接口請求的參數(shù)格式、數(shù)據(jù)結(jié)構(gòu)和校驗規(guī)則，確保傳輸?shù)臄?shù)據(jù)內(nèi)容符合預(yù)期，并防止惡意篡改；——使用jwt的數(shù)字簽名算法：對數(shù)據(jù)進(jìn)行簽名，確保數(shù)據(jù)的完整性和真實性。通過在數(shù)據(jù)中添加數(shù)字簽名，接收方可以驗證數(shù)據(jù)是否在傳輸過程中被篡改。7.4驗證和授權(quán)采用用戶名密碼進(jìn)行用戶身份驗證，驗證通過后才授權(quán)訪問，確保只有合法用戶能夠訪問API接口。7.5請求限制在訪問API接口之前，必須先進(jìn)行身份驗證，獲取訪問令牌（token），并在請求中攜帶