DB32∕T 3761.46-2021 新型冠状病毒肺炎疫情防控技术规范 第46部分：苏康码服务接口

ICS13.100DB32C50江苏省地方标准DB32/T3761.46—2021新型冠状病毒肺炎疫情防控技术规范第46部分：“苏康码”服务接口TechnicalspecificationsforCOVID-2019preventionandcontrolPart46:SKMserviceinterface2021-12-09发布2022-01-09实施DB32/T3761.46—2021目次前1言............................................................................II范围..............................................................................2规范性引用文件....................................................................2术语和定义........................................................................2缩略语............................................................................3接口规则..........................................................................3接口详情..........................................................................4接口应用..........................................................................6234567附录A（规范性附录）江苏政务服务生成用户令牌接口参数说明............................7附录B（规范性附录）苏康码扫码核验接口参数说明.....................................11附录C（规范性附录）苏康码证件号码核验接口参数说明.................................13附录D（规范性附录）苏康码证件号码核验接口加解密方法使用说明.......................16IDB32/T3761.46—2021前言DB32/T3761《新型冠状病毒肺炎疫情防控技术规范》目前分为以下部分：——第1部分：医疗机构；——第2部分：学校；——第3部分：农贸市场；——第4部分：工业企业；——第5部分：社区；——第6部分：公共场所；——第7部分：餐饮服务机构；——第8部分：养老机构；——第9部分：职业健康技术服务机构；——第10部分：公共厕所；——第11部分：大型活动场所；——第12部分：临时观察和隔离场所；——第13部分：公共浴室；——第14部分：影剧院；——第15部分：城市轨道交通；——第16部分：考场；——第17部分：建筑工地；——第18部分：殡葬服务机构；——第19部分：远洋船舶；——第20部分：医疗废物处置中心；——第21部分：环卫工人；——第22部分：城镇污水处理厂；——第23部分：放射诊断工作场所；——第24部分：口腔疾病治疗；——第25部分：公共汽电车；——第26部分：入境人员转运车辆；——第27部分：阳性物品污染场所；——第28部分：方舱式应急CT防护要求；——第29部分：封闭和封控区域；——第30部分：高风险人员转运；——第31部分：核酸采样点；——第32部分：无疫小区建设；——第33部分：港口口岸；——第34部分：发热门诊；——第35部分：医院手术室；——第36部分：重症监护室；IIDB32/T3761.46—2021——第37部分：血液净化中心；——第38部分：消化内镜中心；——第39部分：超声医学工作场所；——第40部分：新冠医疗废物管理；——第41部分：预防接种单位；——第42部分：运输机场；——第43部分：客运航班；——第44部分：货运航班；——第45部分：核酸检测信息系统；——第46部分：苏康码服务接口；——第47部分：苏康码赋码转码管理；——第48部分：人员密集型场所快速调查和处置；——第49部分：流行病学调查；——第50部分：德尔塔等变异株密切接触者判定；——第51部分：人群监测。本文件为DB32/T3761的第46部分。本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。III

DB32/T3761.46—2021新型冠状病毒肺炎疫情防控技术规范第46部分："苏康码"服务接口12范围本文件规定了“苏康码”接口的接口规则、接口说明和接口应用。本文件适用于“苏康码”相关应用系统的设计、开发和系统集成。规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T22239信息安全技术网络安全等级保护基本要求；GB/T27766二维条码网格矩阵码；GB/T33560信息安全技术密码应用标识规范；GB/T35273信息安全技术个人信息安全规范；GB/T35274信息安全技术大数据服务安全能力要求。3术语和定义下列术语和定义适用于本文件。3.1个人信息personalinformation以电子或者其他方式记录的能够单独或者与其他信息结合识别特定自然人身份或者反映特定自然人活动情况的各种信息。注1：个人信息包括姓名、出生日期、身份证件号码、个人生物识别信息、住址、通信通讯联系方式、通信记录和内容、账号密码、财产信息、征信信息、行踪轨迹、住宿信息、健康生理信息、交易信息等。注2：个人信息控制者通过个人信息或其他信息加工处理后形成的信息，例如，用户画像或特征标签，能够单独或者与其他信息结合识别特定自然人身份或者反映特定自然人活动情况的，属于个人信息。[GB/T35273-2020,定义3.1]3.2明示同意explicitconsent个人信息主体通过书面、口头等方式主动作出纸质或电子形式的声明，或者自主作出肯定性动作，对其个人信息进行特定处理作出明确授权的行为。[GB/T35273-2020,定义3.1]1DB32/T3761.46—20213.33.4授权同意consent个人信息主体对其个人信息进行特定处理作出明确授权的行为。［GB/T35273-2020,定义3.7]苏康码personalhealthinformationcodeofJiangsu;SKM以江苏省内申报对象的健康数据为基础，结合相关数据比对后动态生成的个人电子健康凭证。通常使用二维条码作为其展示形式。3.5苏康码服务SKMservice对通过身份认证的用户提供生产、验证苏康码或其对应二维条码的服务。3.6单点登录singlesignon;SSO接入JIS的多个应用系统中，用户只需要登录一次就可以访问所有相互信任的应用系统。。3.7票据ticket票据用于统一身份认证平台单点登录到第三方应用时，统一发放给第三方应用的授权凭证信息，用于系统间的授权互信，第三方应用可以通过校验该凭证获得授权令牌（token），票据只能使用一次且具有时效性。3.8令牌token票据用于统一身份认证平台单点登录到第三方应用时，统一发放给第三方应用的授权凭证信息，用于系统间的授权互信，第三方应用可以通过校验该凭证获得授权令牌（token），票据只能使用一次且具有时效性。3.9应用标识appmark应用的身份唯一标识。应用标识为统一身份认证平台分配给第三方的应用的唯一标识，第三方应用系统在调用统一身份认证接口时，应用标识作为参数传入。3.10应用密钥appword2

DB32/T3761.46—2021应用密钥为统一身份认证平台分配给第三方的应用的安全钥匙，在第三方应用系统调用统一身份认证接口服务时，应用标识、应用密钥和当前时间戳按照顺序拼接进行MD5加密作为参数传入。4缩略语下列缩略语适用于本文件。H5：超文本传输协议5（HyperTextTransferProtocol5）HTTPS:超文本传输安全协议（HyperTextTransferProtocoloverSecureSocketLayer）JSON：轻量级的数据交换格式（JavaScriptObjectNotation）REST：表述性状态转移（RepresentationalStateTranser）Web：全球广域网（WorldWideWeb）AES：高级对称加密算法(AdvancedEncryptionStandard)MD5：信息-摘要算法(Message-DigestAlgorithm5)UUID：通用唯一识别码（UniversallyUniqueIdentifier）5接口规则5.1接口方式苏康码服务系统对外发布江苏政务服务生成用户令牌接口、苏康码扫码核验接口、苏康码证件号码核验接口服务和接受请求应采用符合REST架构原则的Web服务；发布苏康码亮码接口应采用符合H5协议原则的Web服务。5.2接口类型接口类型及说明见说明见表1表1接口类型及说明序号接口类型说明1234江苏政务服务生成用户令牌接口苏康码亮码接口向苏康码应用系统后台发起亮码请求前需通过该接口申请生成用户令牌向苏康码应用系统后台发起亮码验请求苏康码扫码核验接口向苏康码应用系统后台发起扫码核验请求苏康码证件号码核验接口向苏康码应用系统后台发起证件号码核验请求6接口详情6.1江苏政务服务生成用户令牌接口接口描述6.1.1该接口实现接入系统能够直接将实名过的自然人个人信息同步至江苏省统一用户身份认证平台中，同时实现生成用户令牌（token）和UUID，将令牌和UUID传递到苏康码H5页面实现苏康码应用单点登录。注：第三方同步至江苏省统一身份认证平台的用户信息，需要本地进行实名认证过，保证登录的用户为用户本人，已存在的用户(通过身份证号码进行判定)会直接生成令牌。3DB32/T3761.46—20216.1.2业务流程本级流程包括：a)b)c)经用户明示同意或授权同意后将本端用户个人信息资料调用省平台：生成用户令牌接口。省平台确认用户是否已经存在，如未存在进行快捷资料创建。省平台返回该用户的令牌（token）信息、用户UUID信息等。6.1.3接入要求本级要求包括：a)b)c)用户在出示苏康码时必须是实名用户。用户的实名信息必须与省政务服务平台统一用户一致。在使用苏康码时，禁止传递明文，如必须传递明文，必须使用HTTPS，加密、使用后台服务进行请求。d)应用侧必须支持流量控制，如：按并发要求为100，如果超出并发需设定流量控制，并提醒用户。6.1.4调用方式江苏政务服务生成用户令牌接口应通过互联网或电子政务外网调用。6.1.5参数说明江苏政务服务生成用户令牌接口参数说明见附录A苏康码亮码接口接口描述该接口实现接收江苏政务服务生成用户令牌接口生成的令牌和UUID后返回用户苏康码展示H5页面功能。6.2.2业务流程本级流程包括：a)将token和用户UUID通过苏康码H5进行信息传递。b)H5显示用户的苏康码。6.2.3接入要求应接入江苏政务服务生成用户令牌接口生成有效的令牌6.2.4调用方式苏康码亮码接口应通过互联网6.2.5参数说明苏康码亮码接口参数要求见表2表2苏康码亮码接口参数要求4

DB32/T3761.46—2021类别参数tokenuuid类型是否必填说明字符串字符串是否令牌输入参数通用唯一识别码返回数据格式统一采用H5页面格式。6.3苏康码扫码核验接口6.3.1接口描述该接口实现接收用户苏康码二维条码信息后返回用户健康状态功能6.3.2业务流程本级流程包括：a)b)c)经用户授权同意后获取用户苏康码二维条码信息。将用户苏康码二维条码信息和其他参数传入苏康码扫码核验接口。苏康码扫码核验接口返回用户最新健康信息。6.3.3接入要求本级要求包括：a)b)c)d)经用户授权同意。用户健康状态仅做核验，不得留存。禁止用于商业用途。使用固定IP地址的前置接口服务器进行调用。6.3.4调用方式苏康码扫码核验接口应通过互联网。6.3.5参数说明苏康码扫码核验接口参数说明见附录B苏康码证件号码核验接口接口描述该接口实现接收用户个人信息后返回用户健康状态功能。6.4.2业务流程本级流程包括：a)b)c)经用户明示同意、授权同意后获取用户个人信息。将用户个人信息和其他参数传入苏康码扫码核验接口。苏康码证件号码核验接口返回用户最新健康信息。6.4.3接入要求本级流程包括：a)经用户明示同意、授权同意。5DB32/T3761.46—2021b)c)d)用户健康状态仅做核验，不得留存。禁止用于商业用途。使用固定IP地址的前置接口服务器进行调用。6.4.4调用方式苏康码证件号码核验接口应通过互联网。6.4.5参数说明苏康码证件号码核验接口参数说明见附录C7接口应用7.1对接模式7.1.1各设区市防疫指挥部门指定的健康码建设运行单位可申请江苏政务服务生成用户令牌接口、苏康码亮码接口，在原有系统中集成苏康码应用，原则上每个设区市仅允许一家建设运行单位对接。7.1.2各设区市防疫指挥部门指定的健康码建设运行单位、省级政务部门可申请苏康码扫码核验接口、苏康码证件号码核验接口并可进行二次封装支持所辖地区、所属行业防疫重点场所的健康码核验工作。7.1.3防疫重点场所可向拥有二封授权的所属设区市的健康码建设运行单位、所属行业的省级政务主管部门申请苏康码扫码核验接口、苏康码证件号码核验接口。7.2安全要求7.2.1申请江苏政务服务生成用户令牌接口、苏康码亮码接口的应用系统应达到GB/T22239等级保护第三级的要求。7.2.2申请苏康码扫码核验接口、苏康码证件号码核验接口的应用系统在采集、加工、利用个人信息时应符合GB/T35273的规定。7.2.3申请使用苏康码扫码核验接口、苏康码证件号码核验接口的应用系统在利用个人信息时应获取用户的明示同意或授权同意，并承诺对相关隐私内容进行保密。7.2.4申请使用苏康码扫码核验接口、苏康码证件号码核验接口的应用系统应遵循GB/T35274建立数据安全保护制度，实施必要的数据安全技术措施。6

DB32/T3761.46—2021AA附录A（规范性附录）江苏政务服务生成用户令牌接口参数说明A.1参数要求江苏政务服务生成用户令牌接口参数要求见表A.1表A.1江苏政务服务生成用户令牌接口参数要求类别参数类型是否必填是说明appmark字符串字符串应用标识时间戳，即当前时间格式为：年月日时分秒time是实例：2019年05月10日12时12分12秒格式应写为20190510121212参数内容为：MD5(appmark+appword+time)即将应用标识、应用密钥、当前时间按顺序连接并进行md5加密，加密后的字母为小写。sign字符串字符串是是注：1、MD5加密方法是32位的原生加密方法，只支持小写形式2、time是时间戳输入参数业务名称（固定值:"createToken"）servicename业务参数，JSON格式。数据固定格式如下{"name":"张三","paperstype":"证件类型","papersnumber":"321334198703452345","mobile":,字符串params是"email":"zhangsan@163.com"}注意：params需要用AES/CBC-256加密方式进行加密后传输。加密秘钥为appword（即应用密钥）retcode字符串字符串字符串是是否返回状态码(000000为成功，其他为失败，详情可见返回状态码说明)输出参数msgdata返回说明返回结果返回数据格式统一采用JSON格式。示例：（1）成功响应{"retcode":"000000",7DB32/T3761.46—2021"msg":"注册成功"，"data":{"token":"1af90f979db301db4035d2382123f8d5d25ae290a5b0dcd3af221aa2bcbb770e","uuid":"P20200505123412334567821"}}（2）失败响应{"retcode":"000001","msg":"认证失败,必填参数为空""data":""}A.2params参数params参数要求见表A.2表A.2params参数要求字段数据类型字符串长度是否必填字段说明name<=255是姓名证件类型（默认为1）paperstype字符串<=255是1身份证2护照3港澳居民来往内地通行证4台湾居民来往大陆通行证证件号码papersnumbermobile字符串字符串<=20是是<=255移动电话email字符串<=255否emailphoneage字符串字符串字符串字符串字符串<=255<=3否否否否否固定电话年龄sex1性别1：男0：女联系地址邮编addresspost<=255<=255A.3返回状态码返回状态码见表A.3表A.3返回状态码返回码值中文描述000000返回成功8DB32/T3761.46—2021000001000002000003000004000005000010000011000012000020000401000402000403000404000409000410000437000438100001100002100003200001200002200003200004200005200006200007200008500000500001500002认证失败，必填参数为空（精确到具体哪个参数为空）认证失败，sign中的appmark或appword值与参数不同认证失败，应用标识不正确认证失败，应用密钥不正确认证失败，接入应用不存在SM2解密错误AES加密错误AES解密错误工商认证接口返回异常请求数据为空请求格式错误报文格式错误系统标识错误或系统标识已被禁用返回数据异常工商系统异常根据法人企业为查询到企业根据法人企业为查询到对应企业认证失败，票据已失效认证失败，票据已过期认证失败，该票据不存在或已过期认证失败，令牌已过期认证失败，令牌已失效认证失败，无效UUID认证失败，票据生成失败认证失败，登录名未被激活认证失败，登录名或密码不正确认证失败，无效令牌认证失败，接口未申请同步失败同步失败，参数为空同步失败，应用标识不正确9DB32/T3761.46—2021500003600001600002600003600004600005600007600008600013600014600015600016600017999999同步失败，应用密钥不正确登录名（或其他必填项）不能为空登录名格式不正确已经存在相同登录名证件号码格式不正确证件号码已存在手机号码格式不正确手机号码重复姓名格式不正确证件类型格式不正确固定电话格式不正确年龄格式不正确性别格式不正确认证失败，其他错误A.4data参数data参数说明见表A.4表A.4data参数说明字段数据类型字符串长度<=255<=255是否必填字段说明tokenuuid否否返回的用户令牌字符串返回的用户通用唯一识别码10DB32/T3761.46—2021BB附录B（规范性附录）苏康码扫码核验接口参数说明B.1参数要求苏康码扫码核验接口参数要求见表B.1表B.1苏康码扫码核验接口参数要求类别参数类型是否必填是说明url字符串字符串码内容，扫出来的苏康码二维条码内容source是来源，用于标识申请单位（例如：nanjing,wuxi,suzhou）position字符串字符串字符串字符串字符串整数型字符串字符串是是是是是是是是位置信息（例如：江苏省,南京市,鼓楼区,XXX街道XXX号）核验人部门（例如：江苏省疾控中心）核验人名称（例如：王XX）输入参数verifierDeptverifierNameverifierPhonetoken核验人手机号（例如：1509999xxxx）进行特殊加密处理生成的64位字符串唯一保持不变。响应状态码resCode输出参数resMessageres响应状态，如：健康码二维码参数不匹配返回结果返回数据格式统一采用JSON格式。示例：（1）成功响应{"resMessage":"OK","resCode":0,"res":{"createTime":1584610731,"level":"red","name":"王大锤","tip":"绿色：勤洗手、常通风、戴口罩，出现发热咳嗽等症状请及时就医","phone":'12345678900',"idcardNo":"3201********0000"}}（2）失败响应{"resMessage":"没有访问权限","resCode":116,"res":""}11DB32/T3761.46—2021B.2响应状态码响应状态码见表B.2表B.2响应状态码响应状态码中文描述0正常1请求失败，其他异常健康码二维码已失效健康码不匹配，不是苏康码没有访问权限111112116118扫码核验参数缺失，提示会具体到参数名B.3res参数res参数说明见表B.3表B.3res参数表字段数据类型字符串长度<=255<=25510是否必填字段说明namelevel否否否否否姓名字符串状态,red：红码，yellow：黄码；green：绿码createTimetip长整数型字符串注册时间，10位时间戳健康提示<=255<=255phone字符串手机号idcardNo字符串<=255否脱敏证件号12DB32/T3761.46—2021CC附录C（规范性附录）苏康码证件号码核验接口参数说明C.1参数要求苏康码证件号码核验接口参数要求见表C.1表C.1苏康码证件号码核验接口参数要求类别参数类型是否必填说明鉴权，请求时需要在header中增加鉴权参数auth，鉴权的参数由接口提供方提供（鉴权参数需要通过提供的鉴权加解密密钥进行加密），详见附录D。请求体，业务参数，JSON格式。数据固定格式如下:auth字符串是{"userid":,"name":"张三",输入参数"organizeLocation":"南京市,鼓楼区,江苏路172号","applyType":"身份证闸机"}body字符串是注意：body参数需要加密后以text的形式请求体，加解密的密钥由接口提供方提供，详见附录D。响应体，结束数据，JSON格式。数据固定格式如下:{"code":200,"message":"请求成功",输出参数body字符串是"data":{}}注意：响应体需要进行解密才能获得json结果，加解密的密钥由接口提供方提供，详见附录D返回数据解密后格式统一采用JSON格式。示例：（1）成功响应{"code":200,"message":"请求成功","data":{"userid":"3706**********9219","name":"张三","levelData":"2","exceptionCo