国家标准 GB/T38963一2020 个人健康信息码应用接口 Personalhealthinformationcode一Applicationinterface 2020-04-29发布 2020-04-29实施国家市场监督管理总局发布国家标涯花警理委员会国家标准
GB/38963一2020 目次前言引言范围 2 规范性引用文件术语和定义缩略语接口规则 5.1接口方式 5.2服务类型接口说明 6.I概述用户健康信息申报 6.2 用户行程申报接口 63 用户健康信息查询 6.4 6.5健康码调用申请接口 6.6健康码制码请求接口 6.7健康码验码请求接口 6.8用户健康信息纠错接口 l0 接口应用 7.1应用模式 ll 7.2对接模式附录A(资料性附录)健康码BizExtData字段使用说明 12 附录B(资料性附录)接口返回代码说明 13 附录c(资料性附录)健康码制码和验码调用示例 15 参考文献 l6
GB/38963一2020 前言本标准是《个人健康信息码》系列标准之一,该系列标准的结构和名称如下: GB/T38961一2020个人健康信息码参考模型; GB/T38962一2020个人健康信息码数据格式; GB/T38963一2020个人健康信息码应用接口本标准按照GB/T1.1一2009给出的规则起草请注意本文件的某些内容可能涉及专利本文件的发布机构不承担识别这些专利的责任本标准由国务院办公厅电子政务办公室提出本标准由全国信息技术标准化技术委员会(SAC/TC28)归口本标准起草单位;国务院办公厅电子政务办公室,电子技术标准化研究院.公安部第一研究所浙江省大数据发展管理局、广东省政务服务数据管理局、上海市大数据中心,河北省政务服务中心,河南省大数据管理局、贵州省人民政府办公厅,南京市政务服务管理办公室,衡州市营商环境建设办公室,浙江省标准化研究院、杭州市数据资源管理局、合肥市数据资源局、科学院软件研究所、福建正乎软件 1深圳市腾讯计算机系统有限公司、有限公司、北京中盾安信科技发展有限公司、大汉软件股份有限公司支付宝()网络技术有限公司、北京百度网讯科技有限公司、电子科技集团有限公司,阿里巴巴 )有限公司、腾讯云计算(北京)有限责任公司、电科云(北京)科技有限公司本标准主要起草人,卢向东,尹智刚,孙富安,李恒训,.赵波、孙文龙、杨庄奴、周平,于锐、杨林.,国伟王齐春、陈治佳、杨强、陈亚军、于浩、姜舟、徐云、李景曦、王萃、李松渊、马晓、张晓东、温盐、张红振林文昊、钱学文、姜淑娟、李宁、孙茂阳、齐同军、黄颖纯、聂楚江,赵立、江万鑫、王剑冰、黄炜耀、金震宇房迎,罗朝亮、杨鹏、李昊龙、林冠辰、仲里、王舒墨、陈磊、陈昊、侯海实,陈丽平、王永霞、膝一帆、王鹏达焦秀珍
GB/T38963一2020 引言在预防、控制和消除突发公共卫生事件(例如新型冠状病毒感染的肺炎cOVID-19)危害的过程中，需要采集、存储和处理个人健康信息,以实现多种管理用途,主要包括快速获取个人健康的相关信息; -统计某种流行病或疾病的相关信息; -管理不同地域之间的人员流动 -互认健康信息业务等级 2020年2月以来,在cOVID-19疫情防控和复工复产过程中,全国一体化在线政务服务平台(简称 -体化平台”)提供的防疫健康信息码,部分省(区、市)建设使用的“健康码”,作为个人健康信息码的种重要形式,成为快迷采集、存储和处理个人健康信息的一种有效方式个人健康信息码在实际应用过程中,存在码制组成和数据格式不一致,数据不共享和互认机制缺乏等向题,给人员跨地区流动带来了因此,从当前的实践情况和长远的应用需求来看,需要实现个人健康信息码的标雅- 不便一致除突发公共卫生事件的应急处置外,个人健眼信息码在个人医疗,健果养老或其他重大公众活动管理过穆中同样适用本标准中规定的具体事项,法律达规(如《网络安全法(传染病防治法)另有规定的,需遵照其规定执行. IN
GB/38963一2020 个人健康信息码应用接口范围本标准规定了个人健康服务接口的接口规则接口说明和接口应用本标准适用于个人健康信息相关应用系统的设计、开发和系统集成规范性引用文件下列文件对于本文件的应用是必不可少的凡是注日期的引用文件,仅注日期的版本适用于本文件凡是不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件 GB/T226o行政区划代码 GB/T38961一2020个人健康信息码参考模型术语和定义 GB/T38961一2020界定的术语和定义适用于本文件缩略语下列缩略语适用于本文件 HTTP;超文本传输协议(HyperTextTransferProtocol JsON;轻量级的数据交换格式(JavaSeriptObjeetNotation) REST:表述性状态转移(RepresentationalStateTransfer web;全球广域网(worldwideweb 接口规则 5.1接口方式个人健康信息服务系统对外发布服务和接受请求应采用符合REsT架构原则的web服务 5.2服务类型健康码相关的服务类型说明见表1 表1服务类型说明序号服务类型服务名称健康码调用申请接口 1000 2000 健康码制码接口 3000 健康码验码接口
GB/T38963一2020 健康码制码接口中的验证模式说明见表2 表2制码接口中的验证模式说明序号代码模式名称 G100 居民身份网络标识制码 G010 网证数据制码健康码验码接口中的验证模式说明见表3 表3验码接口中的验证模式说明序号代码模式名称 v000 业务验码 V033 身份十业务验码 V034 身份十人像十业务验码 6 接口说明 6.1概述接口类型及说明见表！表4接口类型及说明序号接口类型接口说明用户健康信息申报接口上传用户申报的健康数据信息用户行程申报接口上传用户在规定的时间范围(例如14天)内行程的数据信息查询用户在一定时间段内的个人健康信息和行程信息,默认查询时用户健康信息查询接口段为相关部门规定的时长例如14天客户端向服务端发起业务申请例如制码、验码等)前需通过该接口健康码调用申请接口申请会话权限健康码制码请求接口向健康码应用系统后台发送制码请求健康码验码请求接口向健康码应用系统后台发送验码请求用户健康信息纠错接口向健康码应用系统后台发送纠正相关信息的请求 6.2用户健康信息申报 6.2.1调用方式用户健康信息申报接口应通过互联网或政务外网调用
GB/38963一2020 6.2.2参数要求用户健康信息申报接口参数要求见表5 表5用户健康信息申报接口参数要求类别参数是否必填数据类型说明字符串授权账号是 Accountld AccessToken 字符串授权令牌按GB/T38961一2020中4.2确定的形式拼接,并用密钥加密是字符串 BizExtData 后的值,参见附录A Phone 否字符串联系电话可填写直系亲属电话号码是 Date 字符串申报时间,时间格式为YYYY-MM-DDHH:MM:SS 字符串是 City 当前所在的城市(州、盟等输人字符串所在的具体地址,例如;社区的名称 Area 参数字符串当前所在的县级行政区划代码,应符合GB/T2260规定 Xzqhdm 在卫生健康主管部门规定的时间范围内是否曾经在高风险字符串 IsEpidemicAreaRisk 是地区居住或在高风险地区停留,1.,是/2.否在卫生健康主管部门规定的时间范围内是否接触过高风险 sPatientContactRisk 字符半人员《确诊或疑似病例),1l.是2.否/3.不确定 Symptom 是字符串当前症状(多选),多项症状用“”分隔字符串体温,应填写数字单位为摄氏度(C Temperature 是字符串返回情况说明 head.message 是输出参数字符串返回值代码,其取值及含义参见附录 head.status 返回数据格式统一采用字符串格式示例 "head" "message";"接口调用成功" "status""0" 6.3用户行程申报接口 6.3.1调用方式用户行程申报接口应通过互联网或政务外网调用
GB/T38963一2020 6.3.2参数要求用户行程申报接口参数要求见表6 表6用户行程申报接口参数要求类别是否必填数据类型说明参数字符串授权账号 Accountld AccessTokenm 是字符串授权令牌按GB/T38961一2020中4.2确定的形式拼接,并用密钥加是字符串 BizExtData 密后的值,参见附录A 否 Phone 字符串联系电话(可填写直系亲属电话号码” 在卫生健康主管部门规定的时间范围内停留过的地方(精 StopoverCity 是字符串确到地市级)的市级行政区划代码,在多地市停留时用英文逗号分隔,例如.330100,330200 在卫生健康主管部门规定的时间范围内停留过的地方(精是字符串确到地市级)的行政区划名称,多个时用英文逗号分隔,例输人 StopoverCityName 参数如;“××市,××市” 在卫生健康主管部门规定的时间范围内停留过的地址细否字符串化后的县级)的代码,应使用GB/T2260规定的县级行政 StopoverCounty 区划代码,用英文逗号分隔,例如:330102,330206 在卫生健康主管部门规定的时间范围内停留过的地址细 Stopover(CountyName 字符串化后的县级)的名称,应使用行政区划名称,多个时用英文逗号分隔,例如;“××市××区,××市××区” 申报行程的时间，时间格式为YYYY-MM-DDHH 是 Date 字符串 MM:Ss PathStatus 否字符串行程的校验状态,0;未校验,l;校验成功,2;校验失败 head.message 是字符串返回消息输出参数返回码,其取值及含义参见附录B 是 head.status 字符串 6.4用户健康信息查询 6.4.1调用方式用户健康信息查询接口应通过互联网或政务外网调用 6.4.2参数要求用户健康信息查询接口的参数要求见表7
GB/38963一2020 表7用户健康信息查询接口参数要求类别参数是否必填数据类型说明字符串授权账号 Accountld 是字符串授权令牌 AccessToken 按GB/T389612020中4.2确定的形式拼接,并用密钥加密是字符串 BizExtData 后的值,参见附录A 查询起始时间,在卫生健康主管部门规定的时间范围内取输人值,格式为YYYY-MM-DDHH:MM:SS 参数否字符串 StartDate 以14天为例,2020-02-1608.30.00查询,则starDate可取 2020-02-0208;30;00至2020-02-1608;30;00的任意时间查询截止时间在卫生健康主管部门规定的时间范围内取 EndDate 否字符串值,不早于StartDate,格式为YYYY-MM-DDHH:MMSS BizType 否字符串业务类型字符串返回消息是 head.message 字符串返回码,其取值及含义参见附录B head.status JsON 用户身份的脱敏信息 person 输出 yqReports JsON 用户申报的健康信息参数 yqWarn 是 JsON 健康风险信息否 healthyReport JSON 从各地区汇集的健康证明信息目录数据否 xcgi JsON 卫生健康主管部门规定的时间范围内行程数据返回值见示例1,示例2 示例1: "head"; "message";"接口调用成功" "0" 'status' "data"; person: 兴并关关×314",//个人身份证件号码脱敏信息 "desensitizeCardld";"131*关关×关关 "desensitizeName";"张× //姓名脱敏信息 yqReports:[》, awarn yq warnType";"确诊"/风险类型 "brg";"2020-02-10"，//发病日期 /确诊日期 "qzrq";"2020-02-10" "jerq";"2020-02-10" 1/接触日期 "elx""聚餐"，//接触类型
GB/T38963一2020 "mdtrtDate";"2020-02-10"，人院时间 "dscgDate";"2020-02-20" /出院时间 healthyReport:[ "name";"o" //10;红码(高风险);01;黄码(中风险);00绿码(低风险) "healthyStaus";"00" "date";"2020-03-02"，//健康风险等级评估时间(取值见GB/T38962一2020) /健康风险等级评估原因(取值见GB/T38962一2020) "reason" "dataSource";"××省" //来源省份 "name "healthyStau";"o1" "date";"2020-03-02" "reason";"体温超过37.3C" "dataSource";"××省， xcgi[ "stopoverCity";"330100,330200" 'stopoverCityName";"××市,××市" stopoverCounty";"330102,330205" erCountyName";"××市××区,××市××区" stOpOve "date";"2020-03-12" 'pathStatus "fxd 7/风险等级.0和空:;代表未查询到风险信息1;低风险2:中风险3;高风险 'stopoverCity";"330100,330200" rCityName";"××市,××市" SODKOe rCounty";"330102,330205" stopove "stopoverCountyName";"××市××区,××市××区" "date":"2020-03-11" "pathStatus" "fxdj";"0,0" 示例2: "head" 'nmessage";"接口调用成功" status""0" "data" yqDatas;[},] yqReports;[ , ]
GB/T38963一2020 yqwarn; warnType";"无" healthyReport:[}，， xcgj;[ 力 , 6.5健康码调用申请接口 6.5.1调用方式客户端向服务端发起业务申请,作为后续操作的凭证,应通过互联网或政务外网调用 6.5.2参数要求健康码调用申请接口参数要求见表8，表8健康码调用申请接口参数要求是否必填数据类型类别参数说明 bizPackage.orgCode 字符串机构标识 bizPackage.appld 是字符串应用标识否字符串应用用户标识 bizPackage.appUserld .biaType 字符串业务类型 bizPackage." 输人 bizPackage.bizData.authMode 是字符串制码/验码模式参数服务类型为2000,同时制码模式为G010时必 bizPackage.bizData.applyData 否字符串填,其值由网证认证控件接口的getA AplyDne 方法生成 bizPack 字符串 kage签名值的Base64编码串 sign 是 bizPackage.resultCode 字符串结果返回码,取值及含义参见附录B的表B,2 字符串结果描述否 bizPackage.resultDesc 输出字符串业务流水号 bizPackage.,bizData,bsn 参数是 bizPackage.bizData.randomNumber 字符串随机数是字符串bizPackage签名值的Base64编码串 Sign
GB/T38963一2020 返回数据格式统一采用JsON格式示例 "bizPackage"; 'resultCode""0" "resultDese "bizData"; "bsn" "randomNumber” "sign”" 健康码调用申请、健康码制码请求、健康码验码请求的接口调用示例参见附录C 6.6健康码制码请求接口 6.6.1调用方式健康码制码请求接口应通过互联网或政务外网调用 6.6.2 参数要求健康码制码请求接口参数要求见表9 表9健康码制码请求接口参数要求类别参数是否必填数据类型说明字符串 bizPackage,orgCode 是机构标识是字符串 bizPackage,appld 应用标识否字符串应用用户标识 PkeapU Jserld izPackage,bsnm 是字符串业务流水号 bizPackage.bizType 字符串业务类型是输人参数 bizPackage.bizData.authMode 是字符串制码模式,与调用申请匹配,见表2 bizPackage.bizData.bizExtData 是字符串业务扩展数据,参见附录A 制码模式为G100时,值为居民身份网络标识; bizPackage.bizData.identityData 是字符串制码模式为G010时,值为网证数据 bizPa 是字符串 hecknge签名值的Bhase6编码串 sign bizPackage,resultCode 字符串结果返回码,取值及含义参见附录B的表B2 否 bizPackage.resltDese 字符串结果描述输出是 bizPackage.bizData.imgStream 字符串二维条码图像文件流参数 bzPackage.bizData,width 是字符串位图边长 ign 是字符串 bizPackage签名值的Base64编码串
GB/38963一2020 返回数据格式统一采用JsON格式示例 "bizPackage";: "resultCode";"o" "resultDesc" "bizData": "imgStream "width" 'sign" 6.7健康码验码请求接口 6.7.1调用方式健康码验码请求接口应通过互联网或政务外网调用 6.7.2参数要求健康码验码请求接口的参数要求见表10 表10健康码验码请求接口参数要求类别参数是否必填数据类型说明 bizPackage.orgCode 是字符串机构标识字符串是 bizPackage.appld 应用标识字符串用户标识是 bizPackage.userld 是字符串业务类型 bizPackage.bizType izPackage.bizData.authMode 字符串验码模式,与调用申请匹配,见表3 输人参数 bizPackage.bizData.randomNumber 字符串随机数,验证模式为V033、v034时必填是 bizPackage.bizData.qrCode 字符串健康码字符串根据验证模式确定,验证模式为v034时必填 bizPackage.bizData.photoData 字符串否取值为人像照片数据(加密)Base64编码串是字符串bizPackage签名值的Base64编码串 sign ultCode 是字符串结果返回码,取值及含义参见附录B的表B2 izPackage.resulr bizPackage.resultDesc 字符串结果描述是 bizPackage.,bizData.bizExtData 字符串业务扩展数据,参见附录A 输出参数 bizPackage.bizData.gbMark 否字符串居民身份网络标识 bizPackage.bizData.appUserld 否字符串应用用户标识 sign 是字符串bizPackage签名值的Base64编码串
GB/T38963一2020 返回数据格式统一采用JsON格式示例 "bizPackage": "resultCode";"o", "resultDesc" "bizData": " "bizExtData" "gbMark" Jserld" "appUs6 "sign" 6.8用户健康信息纠错接口 6.8.1调用方式针对健康信息查询页面中的错误信息,用户可发起纠错申请用户健康信息纠错接口应通过互联网或政务外网调用 6.8.2接口参数要求用户健康信息纠错接口的参数要求见表11 表11用户健康信息纠错服务参数要求类别参数是否必填数据类型说明 Accountld 字符串授权账号是 AccessToken 字符串授权令牌 2020中4.2确定的形式拼接,并用密钥加密按GB/T38961 BzExtData 字符串后的值,参见附录A 是 ErrorType 字符串错误类型输人字符串问题标题 Title 参数字符串问题详细描述 Description Date 字符串纠错反馈时间,格式YYYY-MMDDHH.MM,ss City 是字符串当前所在城市,使用行政区划代码是 Phone 字符串电话号码否 Remarks 字符串其他说明返回消息是 head.message 字符串输出参数字符串返回码,其取值及具体含义参见附录B head.status 10
GB/38963一2020 返回数据格式统一采用JsON格式示例 "head": 'message""接口调用成功"， "status""0" 接口应用 7.1应用模式具体防疫业务管理由各地区负责，一体化平台健康码服务主要为地方应用服务,提供综合的大数据分析比对支撑,为各地区提供健康码标准和相关数据查询接口服务各地区可在一体化平台返回的个人防疫风险提示信息基础上,结合本地区数据资源开发健康码服务,在本地区平台上直接面向组织和个人服务各地区自行决定风险等级和如何使用风险等级信息(例如企事业复工复产、社区网格化管理、各地通行等). 各地区应负责所辖地的健康码服务的投诉处理 7.2对接模式已建设健康码相关应用的地区,可按照本标准与一体化平台对接各地区应用软件应能识别由一体化平台生成的健康码,实现基于一体化平台健康码的互联互通一体化平台提供跨地区的个人健康信息查询服务各地区可在此基础上,结合本地区个人健康信息数据,进行风险等级划分和评估尚未建设健康码的地区,可直接将一体化平台健康码作为本地区健康码使用各地区应结合本地区数据资源疫情防控与复工复产要求和卫生健康部门的指导意见,确定管辖范围内人员的风险等级 11
GB/T38963一2020 附录 A 资料性附录) 健康码BizExtData字段使用说明健康码中用户信息以“姓名|身份证件号码|号码类型|国籍代号授权时间”的格式组成,用公钥加密取得加密串后,填到“BizExtData”字段,并发送制码请求示例: Stringargs) publicstaticvoidmain throwsNoSuchAlgorithmException，lnvalidKeySpecExceptionCertificateException. FileNotFoundException 读取公钥私钥 RSAPublicKeypubliekey RSAUtils.getPubicKeyString; RsAPri RsAUl.EetRsAPim rivatekeyprivatekey rivatekey; "张× |110101关翼关关替× 暑#0101l1l1lCHN20200320120001" String println("明文;" System.out.println str System.out.,println("\n公钥加密私钥解密"); 明文和公钥加密,得到密文 StringencodedDatn RSAUtils.publieEnerypt(str，publieKey); encodedlData); RSAUtils.privateDecrypt(encodedData，privateKey); StringdecodedData decodedData) VSem.O11ttO11mtm \n私钥加密公钥解密") 传明文和私钥加密,得到密文 ncodedData RSAUtils.privateEnerypt(str，privatekKey); System.out.,println("密文 encodedlData); 传人文和私钥,得到明文 decodedData=RSAUtils.publiecDecrypt(encodedData，publicKey); ystem.out.println("解密后文字:”十decodedData) 应用软件扫码验证通过取得“izExtData"并作为参数调用人员信息查询接口 12
GB/38963一2020 录附 B 资料性附录接口返回代码说明用户健康信息申报、用户行程申报、用户健康信息查询及用户健康信息纠错等接口的返回值见表B.1 表B.1用户健康信息及行程相关接口返回值返回值编码编码描述接口调用成功第三方接口连接超时证照源未提供此服务接口未找到匹配的信息 10 11 身份验证不通过 12 要求必填的输人参数值为空 15 参数格式不正确 25 返回内容未找到指定数据项其他异常 99 健康码调用申请、健康码制码请求、健康码验码请求等接口的返回值见表B.2 表B.2二维条码接口返回值编码描述返回值编码成功网关网关内部异常、访问后台服务失败等,对应HTTP状态码;404、.500,503 I20000 1120001 网关;网关层系统繁忙(过载保护),对应HTTP状态码503 110000 网关;无法解析的请求,缺少关键字段,对应HTP状态码400 1110001 网关;身份获取失败、验签失败等,对应HTTP状态码;401 I110002 网关;应用无权限访问,对应HTTP状态码;403 Il10003 网关;服务调用次数上限,对应HTTP状态码;403 B120100 申请服务;系统异常申请服务;业务异常 Bl1o1o1 B11o102 申请服务;请求参数不合法 B120200 制码服务;系统异常 B110201 制码服务;业务异常 B110202 制码服务;请求参数不合法 B110203 制码服务;网证不存在 13
GB/T38963一2020 表B.2(续返回值编码编码描述制码服务网证已失效 Bll10204 B110205 制码服务;二维条码生成失败 B110206 制码服务;流水号失效 B110302 验码服务;请求参数不合法 B120300 验码服务;系统异常 B110301 验码服务;业务异常 B110303 验码服务:居民身份网络标识不一致验码服务;无效二维条码 B110304 B110305 验码服务;流水号失效 B110306 验码服务;二维条码已失效或已过期注:业务层返回HTTP状态码统一为200 14
GB/38963一2020 录附 C 资料性附录健康码制码和验码调用示例健康码调用申请、制码和验码相关代码见示例示例: publicstaticvoidmain(String自args)throwsException 7/1、健康码制码调用申请 ereateApply) StringgbMark "1234567890";//居民身份网络标识 "becdathklmmrs"，/业务扩展数扮 StringbizExtData //2、健康制码 eCode(gbMk if(create bizExtData //3、健康码验码调用申请 S alidatCodeApply()) /4、健康码验码 validateCode(; 15
GB/T38963一2020 参考文献 [1]GB/T38962一2020 个人健康信息码数据格式 16

个人健康信息码应用接口GB/T38963-2020详解

随着个人健康信息码的推广和应用，其与各种健康管理、医疗服务系统的接口也变得愈加重要。为此，中国国家标准化管理委员会制定并发布了最新版个人健康信息码应用接口标准GB/T38963-2020。

什么是个人健康信息码应用接口？

个人健康信息码应用接口是指不同系统之间实现数据交互、传输、共享的一种协议。该接口规范了个人健康信息码数据格式、数据元素、数据项之间的映射关系等，在保证数据安全性的前提下，实现了数据高效流通和共享。

GB/T38963-2020标准概述

GB/T38963-2020是由中国国家标准化管理委员会发布的个人健康信息码应用接口标准。该标准主要规定了基本信息、医疗健康信息、生活方式和行为信息以及检测结果信息等方面的数据交换规范，旨在为个人健康信息管理系统提供一个统一的数据接口标准。

该标准包含三部分内容：信息模型、接口规范和数据元素定义。其中，信息模型描述了个人健康信息码各项数据的逻辑关系和数据流向；接口规范规定了不同系统之间交互时使用的协议和技术要求；数据元素定义规定了各个数据项的名称、编码、类型、长度和取值范围等信息。

GB/T38963-2020的实现意义

GB/T38963-2020的发布对于个人健康信息码的应用具有重要意义。首先，该标准的出台使得不同系统之间能够更加高效地共享和传输个人健康信息码数据，促进了数据的整合和优化利用。其次，该标准的实施可以提高个人健康信息的安全性和可靠性，保障个人隐私和数据安全。最后，该标准的实施可以推动个人健康信息化、智能化的发展，为人民群众提供更加优质、高效的健康服务。

结语

GB/T38963-2020的发布标志着我国个人健康信息码应用接口标准化进程取得了重要进展。未来，我们有理由相信，在国家政策和技术支持的推动下，个人健康信息码应用接口将会得到更广泛的应用和发展。