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

ICS13.100

C50

DB32

江苏省地方标准

DB32/T3761.46—2021

新型冠状病毒肺炎疫情防控技术规范

第46部分：“苏康码”服务接口

TechnicalspecificationsforCOVID-2019preventionandcontrol

Part46:SKMserviceinterface

2021-12-09发布2022-01-09实施

江苏省市场监督管理局发布

DB32/T3761.46—2021

I

DB32/T3761.46—2021

新型冠状病毒肺炎疫情防控技术规范

第46部分："苏康码"服务接口

1范围

本文件规定了“苏康码”接口的接口规则、接口说明和接口应用。

本文件适用于“苏康码”相关应用系统的设计、开发和系统集成。

2规范性引用文件

下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，

仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本

文件。

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]

1

DB32/T3761.46—2021

3.3

授权同意consent

个人信息主体对其个人信息进行特定处理作出明确授权的行为。

［GB/T35273-2020,定义3.7]

3.4

苏康码personalhealthinformationcodeofJiangsu;SKM

以江苏省内申报对象的健康数据为基础，结合相关数据比对后动态生成的个人电子健康凭证。通常

使用二维条码作为其展示形式。

3.5

苏康码服务SKMservice

对通过身份认证的用户提供生产、验证苏康码或其对应二维条码的服务。

3.6

单点登录singlesignon;SSO

接入JIS的多个应用系统中，用户只需要登录一次就可以访问所有相互信任的应用系统。。

3.7

票据ticket

票据用于统一身份认证平台单点登录到第三方应用时，统一发放给第三方应用的授权凭证信息，用

于系统间的授权互信，第三方应用可以通过校验该凭证获得授权令牌（token），票据只能使用一次且

具有时效性。

3.8

令牌token

票据用于统一身份认证平台单点登录到第三方应用时，统一发放给第三方应用的授权凭证信息，用

于系统间的授权互信，第三方应用可以通过校验该凭证获得授权令牌（token），票据只能使用一次且

具有时效性。

3.9

应用标识appmark

应用的身份唯一标识。应用标识为统一身份认证平台分配给第三方的应用的唯一标识，第三方应用

系统在调用统一身份认证接口时，应用标识作为参数传入。

3.10

应用密钥appword

2

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接口类型及说明

序号接口类型说明

1江苏政务服务生成用户令牌接口向苏康码应用系统后台发起亮码请求前需通过该接口申请生成用户令牌

2苏康码亮码接口向苏康码应用系统后台发起亮码验请求

3苏康码扫码核验接口向苏康码应用系统后台发起扫码核验请求

4苏康码证件号码核验接口向苏康码应用系统后台发起证件号码核验请求

6接口详情

6.1江苏政务服务生成用户令牌接口

6.1.1接口描述

该接口实现接入系统能够直接将实名过的自然人个人信息同步至江苏省统一用户身份认证平台中，

同时实现生成用户令牌（token）和UUID，将令牌和UUID传递到苏康码H5页面实现苏康码应用单点登

录。

注：第三方同步至江苏省统一身份认证平台的用户信息，需要本地进行实名认证过，保证登录的用户为用户本人，

已存在的用户(通过身份证号码进行判定)会直接生成令牌。

3

DB32/T3761.46—2021

6.1.2业务流程

本级流程包括：

a)经用户明示同意或授权同意后将本端用户个人信息资料调用省平台：生成用户令牌接口。

b)省平台确认用户是否已经存在，如未存在进行快捷资料创建。

c)省平台返回该用户的令牌（token）信息、用户UUID信息等。

6.1.3接入要求

本级要求包括：

a)用户在出示苏康码时必须是实名用户。

b)用户的实名信息必须与省政务服务平台统一用户一致。

c)在使用苏康码时，禁止传递明文，如必须传递明文，必须使用HTTPS，加密、使用后台服务进

行请求。

d)应用侧必须支持流量控制，如：按并发要求为100，如果超出并发需设定流量控制，并提醒用

户。

6.1.4调用方式

江苏政务服务生成用户令牌接口应通过互联网或电子政务外网调用。

6.1.5参数说明

江苏政务服务生成用户令牌接口参数说明见附录A

6.2苏康码亮码接口

6.2.1接口描述

该接口实现接收江苏政务服务生成用户令牌接口生成的令牌和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

类别参数类型是否必填说明

token字符串是令牌

输入参数

uuid字符串否通用唯一识别码

返回数据格式统一采用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苏康码证件号码核验接口

6.4.1接口描述

该接口实现接收用户个人信息后返回用户健康状态功能。

6.4.2业务流程

本级流程包括：

a)经用户明示同意、授权同意后获取用户个人信息。

b)将用户个人信息和其他参数传入苏康码扫码核验接口。

c)苏康码证件号码核验接口返回用户最新健康信息。

6.4.3接入要求

本级流程包括：

a)经用户明示同意、授权同意。

5

DB32/T3761.46—2021

b)用户健康状态仅做核验，不得留存。

c)禁止用于商业用途。

d)使用固定IP地址的前置接口服务器进行调用。

6.4.4调用方式

苏康码证件号码核验接口应通过互联网。

6.4.5参数说明

苏康码证件号码核验接口参数说明见附录C

7接口应用

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—2021

AA

附录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是时间戳

输入servicename字符串是业务名称（固定值:"createToken"）

参数

业务参数，JSON格式。数据固定格式如下

{"name":"张三",

"paperstype":"证件类型",

"papersnumber":"321334198703452345",

params字符串是

"mobile":,

"email":"zhangsan@163.com"}

注意：params需要用AES/CBC-256加密方式进行加密后传输。加密秘钥为

appword（即应用密钥）

retcode字符串是返回状态码(000000为成功，其他为失败，详情可见返回状态码说明)

输出

msg字符串是返回说明

参数

data字符串否返回结果

返回数据格式统一采用JSON格式。

示例：（1）成功响应

{

"retcode":"000000",

7

DB32/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台湾

居民来往大陆通行证

papersnumber字符串<=20是证件号码

mobile字符串<=255是移动电话

email字符串<=255否email

phone字符串<=255否固定电话

age字符串<=3否年龄

sex字符串1否性别1：男0：女

address字符串<=255否联系地址

post字符串<=255否邮编

A.3返回状态码

返回状态码见表A.3

表A.3返回状态码

返回码值中文描述

000000返回成功

8

DB32/T3761.46—2021

000001认证失败，必填参数为空（精确到具体哪个参数为空）

000002认证失败，sign中的appmark或appword值与参数不同

000003认证失败，应用标识不正确

000004认证失败，应用密钥不正确

000005认证失败，接入应用不存在

000010SM2解密错误

000011AES加密错误

000012AES解密错误

000020工商认证接口返回异常

000401请求数据为空

000402请求格式错误

000403报文格式错误

000404系统标识错误或系统标识已被禁用

000409返回数据异常

000410工商系统异常

000437根据法人企业为查询到企业

000438根据法人企业为查询到对应企业

100001认证失败，票据已失效

100002认证失败，票据已过期

100003认证失败，该票据不存在或已过期

200001认证失败，令牌已过期

200002认证失败，令牌已失效

200003认证失败，无效UUID

200004认证失败，票据生成失败

200005认证失败，登录名未被激活

200006认证失败，登录名或密码不正确

200007认证失败，无效令牌

200008认证失败，接口未申请

500000同步失败

500001同步失败，参数为空

500002同步失败，应用标识不正确

9

DB32/T3761.46—2021

500003同步失败，应用密钥不正确

600001登录名（或其他必填项）不能为空

600002登录名格式不正确

600003已经存在相同登录名

600004证件号码格式不正确

600005证件号码已存在

600007手机号码格式不正确

600008手机号码重复

600013姓名格式不正确

600014证件类型格式不正确

600015固定电话格式不正确

600016年龄格式不正确

600017性别格式不正确

999999认证失败，其他错误

A.4data参数

data参数说明见表A.4

表A.4data参数说明

字段数据类型长度是否必填字段说明

token字符串<=255否返回的用户令牌

uuid字符串<=255否返回的用户通用唯一识别码

10

DB32/T3761.46—2021

BB

附录B

（规范性附录）

苏康码扫码核验接口参数说明

B.1参数要求

苏康码扫码核验接口参数要求见表B.1

表B.1苏康码扫码核验接口参数要求

类别参数类型是否必填说明

url字符串是码内容，扫出来的苏康码二维条码内容

source字符串是来源，用于标识申请单位（例如：nanjing,wuxi,suzhou）

position字符串是位置信息（例如：江苏省,南京市,鼓楼区,XXX街道XXX号）

输入

字符串是核验人部门（例如：江苏省疾控中心）

参数verifierDept

verifierName字符串是核验人名称（例如：王XX）

verifierPhone字符串是核验人手机号（例如：1509999xxxx）

token字符串是进行特殊加密处理生成的64位字符串唯一保持不变。

resCode整数型是响应状态码

输出

resMessage字符串是响应状态，如：健康码二维码参数不匹配

参数

res字符串是返回结果

返回数据格式统一采用JSON格式。

示例：（1）成功响应

{

"resMessage":"OK",

"resCode":0,

"res":{

"createTime":1584610731,

"level":"red",

"name":"王大锤",

"tip":"绿色：勤洗手、常通风、戴口罩，出现发热咳嗽等症状请及时就医",

"phone":'12345678900',

"idcardNo":"3201********0000"

}

}

（2）失败响应

{

"resMessage":"没有访问权限",

"resCode":116,

"res":""

}

11

DB32/T3761.46—2021

B.2响应状态码

响应状态码见表B.2

表B.2响应状态码

响应状态码中文描述

0正常

1请求失败，其他异常

111健康码二维码已失效

112健康码不匹配，不是苏康码

116没有访问权限

118扫码核验参数缺失，提示会具体到参数名

B.3res参数

res参数说明见表B.3

表B.3res参数表

字段数据类型长度是否必填字段说明

name字符串<=255否姓名

level字符串<=255否状态,red：红码，yellow：黄码；green：绿码

createTime长整数型10否注册时间，10位时间戳

tip字符串<=255否健康提示

phone字符串<=255否手机号

idcardNo字符串<=255否脱敏证件号

12

DB32/T3761.46—2021

CC

附录C

（规范性附录）

苏康码证件号码核验接口参数说明

C.1参数要求

苏康码证件号码核验接口参数要求见表C.1

表C.1苏康码证件号码核验接口参数要求

类别参数类型是否必填说明

鉴权，请求时需要在header中增加鉴权参数auth，鉴权的参数由接口提供方提供（鉴

auth字符串是

权参数需要通过提供的鉴权加解密密钥进行加密），详见附录D。

请求体，业务参数，JSON格式。数据固定格式如下:

{"userid":,

输入"name":"张三",

参数"organizeLocation":"南京市,鼓楼区,江苏路172号",

body字符串是

"applyType":"身份证闸机"

}

注意：body参数需要加密后以text的形式请求体，加解密的密钥由接口提供方提供，

详见附录D。

响应体，结束数据，JSON格式。数据固定格式如下:

{"code":200,

"message":"请求成功",

输出

body字符串是"data":{}

参数

}

注意：响应体需要进行解密才能获得json结果，加解密的密钥由接口提供方提供，详

见附录D

返回数据解密后格式统一采用JSON格式。

示例：（1）成功响应

{

"code":200,

"message":"请求成功",

"data":

{

"userid":"3706**********9219",

"name":"张三",

"levelData":"2",

"exceptionCodeReason":"黄名单接口判定"

}

13

DB32/T3761.46—2021

}

（2）失败响应

{

"code":407,

"message":"已过期，请更新",

"data":null

}

C.2请求体body参数

请求体body参数要求见表C.2

表C.2请求体body参数要求

字段数据类型长度是否必填字段说明

userid字符串<=255是证件号码

name字符串<=255是姓名

organizeLocati

字符串<=255否核验位置

on

applyType字符串<=255否应用类型

C.3响应体body参数

响应体body参数说明见表C.3

表C.3响应体body参数说明

字段数据类型长度是否必填