DB14-T 3024-2024 惠民惠农财政补贴资金“一卡通”服务平台与代发银行接口规范

ICS35.200CCSL7014IDB14/T3024—2024前言 2规范性引用文件 3术语和定义 4接口类型 5接口调用 26接口描述 37安全要求 DB14/T3024—2024本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。本文件由山西省财政厅提出、组织实施和监督检查。山西省市场监督管理局对标准的组织实施情况进行监督检查。本文件由山西省财政标准化技术委员会（SXS/TC48）归口。本文件起草单位：山西省财政科学研究院、山西宝佳质量基础研究院（有限合伙）。本文件主要起草人：葛强、任巍英、张宝林、韩慧彦、李林骏、张素娥、董阿敏、徐维迪、李斌、石鑫。1DB14/T3024—2024惠民惠农财政补贴资金"一卡通"服务平台与代发银行接口规范本文件规定了惠民惠农财政补贴资金“一卡通”服务平台（以下简称“一卡通平台”）与代发银行的接口类型、接口调用、接口描述和安全要求。本文件适用于代发银行接入一卡通平台的设计、开发和应用。2规范性引用文件本文件没有规范性引用文件。3术语和定义下列术语和定义适用于本文件。3.1代发银行省、市、县（市、区）区域内，依法设置的各项财政补贴资金委托代发银行。4接口类型一卡通平台与代发银行接口包括BT001身份登录接口、YH008单笔银行账号验证接口、YH010批量银行账号验证接口、BT009银行账号验证结果接收接口、YH005补贴明细接收接口、BT006上卡结果接收接口、YH011查询银行工作状态接口、YH012获取银行回盘文件接口，接口类型如表1所示。表1接口类型账号（账户名，证件号码，银行账号）信息，验证准账号信息，验证准确性后通过接口BT009返回验证结果该接口由代发银行建设，由一卡通平台调用，传递银行2DB14/T3024—2024表1接口类型（续）该接口由一卡通平台建设，由代发银行调用，用中、验卡进行中、验卡结束；未启动发放、发放5接口调用一卡通平台与代发银行使用各数据接口，经过身份认证、信息验证、补贴发放、银行状态查询、获取银行回盘文件五个步骤实现惠民惠农财政补贴资金的发放，各接口调用如附录A图A.1所示，各阶段接口调用方式如下：——身份认证：银行调用“BT001身份登录接口”进行身份认证，认证通过后完成后续阶段业务；——信息验证：一卡通平台调用“YH008单笔银行账号验证接口”推送单笔银行账号信息，银行验证准确性后同步返回验证结果；一卡通平台调用“YH010批量银行账号验证接口”推送批量银行账号信息，银行验证准确性后，调用“BT009银行账号验证结果接收接口”返回验证结果；——补贴发放：一卡通平台调用“YH005补贴明细接收接口”推送补贴对象明细信息，银行发放结束后，调用“BT006上卡结果接收接口”返回发放结果；——银行状态查询：一卡通平台推送成功至银行后，调用“YH011查询银行工作状态接口”，查询某批次账号验证或补贴发放状态；——获取银行回盘文件：当一卡通平台网络出现问题，银行未能成功生成回盘详情文件时，一卡通平台调用“YH012获取银行回盘文件接口”，令银行再次生成回盘详情文件，并读取详情文件更新数据。3DB14/T3024—2024图1接口调用方式6接口描述6.1通用要求6.1.1数据类型接口参数数据类型包括数值型（number）和字符型（string）两种。4DB14/T3024—20246.1.2数据格式接口之间数据传输采用JSON数据格式。6.1.3消息结构组成由消息头和消息体组成。消息头格式如表2所示；消息体由head与data组成，head包含唯一标识、日期、银行联行号等通用字段，如表3所示，data对应不同接口功能性字段，详见本章各接口请求参数。表2消息头格式表3消息体head格式返回消息码.1数据返回编码如表4所示。表4数据返回编码表 --5DB14/T3024—2024表4数据返回编码表（续）----.2接口调用返回编码如表5所示。表5接口调用返回编码表NoContent- 6.1.4调用策略接口调用策略包括：——超时时间：在与接口进行通信时，时间限制为20秒；——调用次数：无限制。6.2参数要求6.2.1BT001身份登录接口接口参数如表6所示。6DB14/T3024—2024表6BT001身份登录接口回结果时，uuid为调用请求报文中的uuidmsg6.2.2YH008单笔银行账号验证接口接口参数如表7所示。表7YH008单笔银行账号验证接口银行接收来自一卡通平台的单笔银行账号（账户名，证件号码，银行账号）信息，验证准确性后同7DB14/T3024—2024表7YH008单笔银行账号验证接口（续）验证结果（-1-验证不通过；0-未验证；6.2.3YH010批量银行账号验证接口接口参数如表8所示。表8YH010批量银行账号验证接口api/bank/acceptValidat8DB14/T3024—2024表8YH010批量银行账号验证接口（续）接口说明如下：——文件说明：批量银行账号文件用于存储一卡通平台的批量银行账号信息，其命名方式为：接口编码_CallUser_AreaCode+To+BankNo+_+uuid+.txt，其中uuid须与银行账号验证结果文件名中的uuid一致；示例：YH010_1501511014336_140000000000To101——文件格式：字段通过@|$分隔，行通过\n分隔；——文件行数：最大10万笔；——文件字段说明如表9所示。表9批量银行账号文件字段NN-N-N-Y-Y-6.2.4BT009银行账号验证结果接收接口接口参数如表10所示。表10BT009银行账号验证结果接收接口/api/bank/payRes/validate9DB14/T3024—2024表10BT009银行账号验证结果接收接口（续）接口说明如下：——文件说明：银行账号验证结果文件用于存储银行返回账号信息验证结果，其命名方式为：接口编码_CallUser_BankNo+To+AreaCode+_+uuid+.txt,其中uuid须与批量银行账号文件名中的uuid一致；示例：BT009_1501511014336_101000000000To14000——文件格式：字段通过@|$分隔，行通过\n分隔；——文件行数：最大10万笔；——文件字段说明如表11所示。表11银行账号验证结果文件字段NN-N-N-2N3YYY-Y 6.2.5YH005补贴明细接收接口接口参数如表12所示。DB14/T3024—2024表12YH005补贴明细接收接口fileName接口说明如下：——文件说明：补贴明细文件用于存储一卡通平台向银行传输上卡明细数据，其命名方式为：接口编码_CallUser_AreaCode+To+BankNo+_+uuid+.txt,其中uuid须与代发银行上卡结果文件名中的uuid一致；示例：YH005_1501511014336_140000000000To101——文件格式：字段通过@|$分隔，行通过\n分隔；——文件行数：最大10万笔；——文件字段说明如表13所示。表13补贴明细文件字段NN DB14/T3024—2024表13补贴明细文件字段（续）N-N单位：分N-1NYYY Y-6.2.6BT006上卡结果接收接口接口参数如表14所示。表14BT006上卡结果接收接口/api/bank/payRes/resultFfileNameDB14/T3024—2024表14BT006上卡结果接收接口（续）接口说明如下：_CallUser_BankNo+To+AreaCode+_+uuid+.txt，其中uuid须与补贴明细文件文件名中的uuid一致；示例：BT006_1501511014336_101000000000To140——文件格式：字段通过@|$分隔，行通过\n分隔；——文件行数：最大10万笔；——文件字段说明如表15所示。表15上卡结果文件字段NN N N单位：分N-1NYY1N3YYY-Y-6.2.7YH011查询银行工作状态接口接口参数如表16所示。DB14/T3024—2024表16YH011查询银行工作状态接口6.2.8YH012获取银行回盘文件接口接口参数如表17所示。表17YH012获取银行回盘文件接口一卡通平台主动向银行获取回盘文件，防止接收数据DB14/T3024—2024表17YH012获取银行回盘文件接口（续）7安全要求7.1基础策略7.1.1网络层采用IP和端口进行限制：采用IP白名单只允许特定的IP地址和端口号访问API接口，以防止未授权的访问和攻击。7.1.2协议层采用HTTPS传输协议：使用HTTPS协议对数据进行加密，并使用SSL证书验证服务器身份，以保证数据传输的安全性。7.2数据加密采用SM4算法对敏感数据进行加密，保障数据安全。7.3数据完整性为了确保数据在传输过程中的完整性和真实性，采用以下方式：——使用HTTPS协议：通过使用HTTPS协议，所有的数据在传输过程中都会被加密，防止数据被窃取或篡改。确保数据传输的机密性和完整性；——接口参数约定：通过制定接口参数的约定，确保数据在传输过程中不被修改。定义接口请求的参数格式、数据结构和校验规则，确保传输的数据内容符合预期，并防止恶意篡改；——使用jwt的数字签名算法：对数据进行签名，确保数据的完整性和真实性。通过在数据中添加数字签名，接收方可以验证数据是否在传输过程中被篡改。7.4验证和授权采用用户名密码进行用户身份验证，验证通过后才授权访问，确保只有合法用户能够访问API接口。7.5请求限制在访问API接口之前，必须先进行身份验证，获取访问令牌（token），并在请求中携带