DB44-T 2167.3-2019 广东省电子证照技术规范 第3部分：接口规范

35.240.01L

67DB44 44/T

2167.3—2019广东省电子证照技术规范第

3

部分：接口规范Electronic

Part

3:Interface

2019

-

07

-

发布 2019

-

10

-

实施广东省市场监督管理局 发

布DB44/T

2167.3—2019 前言

II1

12

系统接口概述

12.1 接口组成

12.2 接口技术要求

12.3 接口使用

13

接口模型及参数

23.1 请求模型

23.2 返回模型

33.3 接口参数

4附录

A（规范性附录） 接口及其参数说明

5附录

B（规范性附录） 公共参数及数据类型

22附录

C（规范性附录） 错误分类代码

27参

考 文 献

30DB44/T

2167.3—2019 DB44/T

2167《广东省电子证照技术规范》分为4个部分：——第

1

部分：总体构架；——第

2

部分：数据规范；——第

3

部分：接口规范；——第

4

部分：应用与技术管理要求。本部分为DB44/T

21673部分。本部分按照GB/T

给出的规则起草。本部分的附录A、附录B、附录C为规范性附录。本部分由广东省工业和信息化厅提出。本部分由广东省信息技术标准化技术委员会归口。本部分主要起草人：周春华、王贵虎、王韬、丁曙初、马晓镌、梁宏、何铤、肖晓赟、黎东初。IIDB44/T

2167.3—2019

1 范围DB44/T

2167的本部分规定了其他电子政务系统与电子证照系统进行对接的接口规范。本部分适用于与政务电子证照系统的对接。2 系统接口概述2.1接口组成接口。a)电子证照目录查询接口应提供电子证照全省目录、地区和部门应开通目录查询功能。b) 证照信息管理接口应提供电子证照制证、签发、更新、废止等功能。c) 安全会话接口应提供对接入应用和用户身份进行合法性验证等功能。d) 用证服务接口应提供对电子证照进行查询、调用和有效性、归档等功能。2.2 接口技术要求a)

采用基于

技术服务接口；b)

接口的请求和返回结果采用

JSON

格式；c)

应支持跨系统、跨平台调用；d)

传输的数据应采用加密和防篡改技术保证数据的完整有效性。2.3 接口使用可采用app_key和方式或CA和认证方式接口使用可参考流程：DB44/T

2167.3—2019

图1接口使用流程图1)

其他电子政务系统向电子证照系统进行应用注册和申请授权；2)

审核通过后返回应用唯一标识（app_key）和密钥（app_secret）；3)

其他电子政务系统调用登录接口，在参数中加入

和

app_secret，创建会话；4)

电子证照系统返回接入令牌（access_token5)

在会话有效期内通过加入

access_token

参数进行接口调用；6)

电子证照系统返回相应数据；7)

会话超时或通过注销接口结束调用。3 接口模型及参数3.1请求模型DB44/T

2167.3—2019图2 接口请求模型数据结构InterfaceName）、请求参数集（RequestParameterSet）、附件集（AttachmentSet）组成，实线连接内容为必选项，虚线连接内容为可选项。——接口名称。接口名称指定将要调用的接口。——参数集。结构化请求参数集，登录接口必须包含

和

app_secret，其它接口必须至少包含请求公共参数。每个参数由参数名（Name）和参数值（Value）、参数类型（Type）组成。——附件集Name）、附件链接地址（）、附件类型（Type）、附件内容（Content）和附件描述（）组成，附件链接地址和附件内容至少包含一项。3.2 返回模型DB44/T

2167.3—2019图3 接口返回模型数据结构接口返回模型（ResponseModel）由返回结果参数集（ResponseParameterSet）、附件集（AttachmentSet）组成。——返回结果参数集结构化的返回结果参数集，应至少包括返回公共参数。每个参数由参数名（Name）和参数值（Value）组成。——附件集附件集为可选内容，不含或含一个以上附件，定义与接口请求模型相同。3.3 接口参数接口的具体请求和返回参数应符合附录A要求。请求公共参数和返回公共参数应符合附录B.1要求。app_keyString

app_keyapp_secretString

app_secretaccountStringpasswordStringorg_codeStringack_codeStringSUCCESS

errorsStringaccess_tokenStringDB44/T

2167.3—2019附

录 A（规范性附录）接口及其参数说明A.1 安全会话接口A.1.1登录登录是接口系统调用的第一个方法。通过调用登录接口进行身份验证，验证成功后创建一个会话，请求参数：表

登录请求参数返回结果：表

A.2登录返回结果参数返回结果：A.1.2注销注销当前会话。请求参数：返回结果：A.1.3获取当前已登录用户信息获取当前已登录用户的信息。请求参数：page_indexInteger

page_sizeInteger

10

keywordString查询关键字（证照名称，目录编制部门）statusLicenseItemStatusis_openBooleanpage_indexInteger

page_sizeInteger

10

keywordStringis_serviceBooleandataUserInfodataList<LicenseItem>DB44/T

2167.3—2019返回结果：表

A.3注销返回结果参数A.2电子证照目录接口A.2.1 查询全省目录列举出全省目录清单。请求参数：表

A.4 查询全省目录请求参数licensecertificate表

A.5查询全省目录返回结果A.2.2查询地区应开通目录列举出一个地区的应用开通目录清单。请求参数：表

A.6查询地区应开通目录请求参数返回结果：返回结果：data_fieldsStringoperatorUserInfoservice_item_codeStringservice_item_nameStringbiz_numStringlicense_groupStringseal_codeStringpage_indexInteger

page_sizeInteger

10

keywordStringis_serviceBooleandataList<LicenseItem>dataList<LicenseItem>DB44/T

2167.3—2019表

A.7 查询地区应开通目录返回结果A.2.3查询部门应开通目录列举出一个部门的应用开通目录清单。请求参数：表

A.8 查询部门应开通目录请求参数返回结果：表

A.9 查询部门应开通目录返回结果返回结果：A.3 电子证照制证接口A.3.1 创建制证数据接口按照数据标准，提交证照信息，制作一个电子证照。如果证照带有附件，需要另外调用附件相关接口操作。请求参数：表

A.10 创建制证数据请求参数返回结果：返回结果：license_codeStringdata_fieldsStringoperatorUserInfoservice_item_codeStringservice_item_nameStringbiz_numStringlicense_groupStringseal_codeStringlicense_codeStringid_codeStringoperatorUserInfoservice_item_codeStringservice_item_nameStringbiz_numStringlicense_codeStringauth_codeStringDB44/T

2167.3—2019表

A.11 创建制证数据返回结果A.3.2 修改制证数据修改电子证照制证数据。请求参数：表

A.12 修改制证数据请求参数返回结果：返回结果：A.3.3删除制证数据删除电子证照制证数据。请求参数：表

A.13删除制证数据请求参数license_codelicense_codelicense_codeStringnameStringfile_typeStringfile_dataStringbase64

attachment_codeStringlicense_codeStringdatadataAttachmentDB44/T

2167.3—2019A.3.4下载单个附件根据附件唯一标识获取单个附件数据。请求参数：表

A.14 下载单个附件请求参数返回结果：表

A.15下载单个附件返回结果返回结果：A.3.5下载多个附件根据电子证照标识码获取证照附件数据。请求参数：表

A.16下载多个附件请求参数返回结果：表

A.17下载多个附件返回结果返回结果：A.3.6 添加附件数据添加电子证照附件数据。请求参数：表

A.18 添加附件数据请求参数attachment_codeStringlicense_codeStringnameStringfile_typeStringfile_dataStringbase64

BooleandescriptionStringlicense_codeStringattachment_codeStringBooleandescriptionStringattachment_codeStringDB44/T

2167.3—2019表

A.18 添加附件数据请求参数（续）返回结果：表

A.19 添加附件数据返回结果返回结果：A.3.7 修改附件数据修改电子证照附件数据。请求参数：表

A.20 修改附件数据请求参数attachment_codeattachment_codeA.3.8 删除附件数据删除电子证照附件数据。请求参数：表

A.21 删除附件数据请求参数返回结果：10返回结果：license_codeStringid_codeStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringid_codeStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfoDB44/T

2167.3—2019A.4 电子证照信息管理接口A.4.1 签发一张证照签发一张电子证照。请求参数：表

A.22 签发一张证照请求参数license_codelicense_codelicense_code返回结果：无。（仅包含返回公共参数）A.4.2废止一张证照废止一张电子证照。请求参数：表

A.23 废止一张证照请求参数license_codelicense_codelicense_code返回结果：11license_codeStringid_codeStringdata_fieldsStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringid_codeStringdata_fieldsStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringauth_codeStringDB44/T

2167.3—2019无。（仅包含返回公共参数）A.4.3变更一张证照变更一张证照。请求参数：表

A.24变更一张证照请求参数license_codelicense_codelicense_code返回结果：表

A.25 变更一张证照返回结果A.4.4加注一张证照加注一张证照。请求参数：表

A.26 加注一张证照请求参数12license_codeStringid_codeStringdata_fieldsStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringauth_codeStringlicense_codeStringauth_codeStringDB44/T

2167.3—2019license_codelicense_code返回结果：表

A.27加注一张证照返回结果A.4.5年检一张证照年检一张证照。请求参数：表

A.28 年检一张证照请求参数license_codelicense_codelicense_code返回结果：表

A.29年检一张证照返回结果A.4.6 换证一张证照换证一张证照。请求参数：13license_codeStringid_codeStringdata_fieldsStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringid_codeStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringauth_codeStringDB44/T

2167.3—2019表

A.30换证一张证照请求参数license_codelicense_codelicense_code返回结果：表

A.31换证一张证照返回结果A.4.7挂失一张证照挂失一张证照。请求参数：表

A.32 挂失一张证照请求参数license_codelicense_codelicense_code返回结果：A.4.8补发一张证照14license_codeStringid_codeStringdata_fieldsStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringid_codeStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfolicense_codeStringauth_codeStringDB44/T

2167.3—2019补发一张证照。请求参数：表

A.33 补发一张证照请求参数license_codelicense_codelicense_code返回结果：表

A.34 补发一张证照返回结果A.4.9吊销一张证照吊销一张证照。请求参数：表

A.35 吊销一张证照请求参数license_codelicense_codelicense_code15license_codeStringid_codeStringservice_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfopage_indexInteger

page_sizeInteger

10

license_statusStringcredentialString

token_idString

randomStringDB44/T

2167.3—2019返回结果：无。（仅包含返回公共参数）A.4.10 注销一张证照注销一张证照。请求参数：表

A.35 注销一张证照请求参数license_codelicense_codelicense_code返回结果：无。（仅包含返回公共参数）A.5 电子证照用证服务接口A.5.1 两页系统用证民个人网页、企业专属网页）系统使用。使用这个接口必须先登录实名认证系统获取实名登录凭据。请求参数：表

A.36 两页用证请求参数16service_item_codeStringservice_item_nameStringbiz_numStringcredentialString

token_idString

randomString实名登录随机数total_countIntegerdataList<License>auth_codesList<String>total_countIntegerdataList<License>auth_codesList<String>DB44/T

2167.3—2019返回结果：表

A.37两页用证返回结果A.5.2持证者用证凭据。请求参数：表

A.38 持证者用证请求参数返回结果：表

A.39 持证者用证返回结果返回结果：A.5.3 依职能查验用证照，同时对结果清单每一项生成用证码。请求参数：17service_item_codeStringservice_item_nameStringbiz_numStringoperatorUserInfoidentity_numberStringtotal_countIntegerdataList<License>auth_codesList<String>expires_inString

yyyy-MM-ddHH:mm:ss.fffStringpage_indexInteger

page_sizeInteger

10

auth_codeStringDB44/T

2167.3—2019表

A.40 依职能用证请求参数表

A.40依职能用证请求参数（续）返回结果：表

A.41 依职能用证返回结果返回结果：A.5.4 获取证照访问令牌根据电子证照用证码获取电子证照访问令牌。请求参数：表

A.42 换取访问令牌请求参数返回结果：表

A.43 换取访问令牌返回结果返回结果：18file_nameString

file_dataString

auth_codeStringauth_codeStringdataLicenseDB44/T

2167.3—2019A.5.5提取证照数据根据用证码提取一个电子证照的数据。请求参数：表

A.44 提取证照数据请求参数返回结果：表

A.45 提取证照数据返回结果返回结果：A.5.6 获取归档文件根据用证码获取一张电子证照归档文件。请求参数：表

A.46 获取归档文件请求参数返回结果：表

A.47 获取归档文件返回结果返回结果：A.6 事项与电子证照关系接口查询事项所需的电子证照和所签的电子证照。A.6.1 查询部门事项根据主管部门组织机构代码查询服务事项列表。忽略status参数，只返回已发布状态的事项。请求参数：19service_item_codeStringtypeString

org_codeStringstatusStringlicense_access_tokenStringdataList<ServiceItem>dataStringDB44/T

2167.3—2019表

A.48查询部门事项请求参数返回结果：表

A.49查询部门事项返回结果返回结果：A.6.2查询事项与证照关系根据事项编号查询所需的电子证照和所签的电子证照。请求参数：表

A.50 查询部门事项请求参数返回结果：表

A.51 查询部门事项返回结果返回结果：A.7 电子证照网页接口电子证照网页接口部署在互联网（以下约定部署在互联网的接口URL地址前缀为{WEB_ROOT}），均采用HTTPS

GET方法调用，返回html页面，一般搭配IFrame或弹出页面使用。A.7.1查看电子证照页面查看单个电子证照详情页面。请求参数：表

A.52 查看单个证照页面请求参数20license_access_tokenStringlicense_access_tokenStringDB44/T

2167.3—2019返回结果：电子证照详情网页。A.7.2 按对象查看电子证照页面按对象查看电子证照详情页面。请求参数：表

A.53按对象查看电子证照页面请求参数返回结果：持证者电子证照详情网页。返回结果：A.7.3审核签发电子证照页面签发操作人审核并签发电子证照页面。请求参数：表

A.54审核签发电子证照页面请求参数返回结果：审核签发电子证照页面。返回结果：21ack_codeStringSUCCESSFAILUREerrorsList<Error>signStringsign_methodStringtimestampDatecorrelation_idString

request_id

request_id

response_idStringaccess_tokenString

signStringsign_certStringsign_methodStringtimestampDate

10

request_idString

request_id

DB44/T

2167.3—2019D

A附

录 B（规范性附录）公共参数及数据类型B.1 公共参数B.1.1 请求公共参数表

B.1 接口请求公共参数B.1.2返回公共参数表

B.2 接口返回结果公共参数B.2 参数类型22license_codeStringnameStringlicense_typeString

DB44xx

id_codeStringdoc_nameStringdoc_summaryStringdoc_keywordStringholder_nameStringStringholder_identity_numString持证者身份证件号码。如有多个，中间以逗号（StringStringdivisionStringdivision_codeStringissue_dateDate

YYYYMMDDbegin_dateDate

YYYYMMDDexpiry_dateDate证照有效期结束日期

YYYYMMDDdata_fieldsString

json

attachment_fieldsString证照附件数据，采用

json

StringDateIntegerFloatBytesBooleanList<Type>Type

codeStringmessageStringinner_codeString

DB44/T

2167.3—2019表

B.3 基本数据类型表

B.4 错误信息

Error

类表

B.5证照信息

类23trust_levelString

DB44xx

remarkStringbiz_numStringlicense_item_codeStringlicense_statusString

DB44xx

creatorStringcreation_timeDateissuerStringissue_timeDateabolisherStringabolish_timeDateStringcorrelative_licenseStringpublic_keyStrings_sign_certStringalgorithmStrings_sign_dataStringlast_modificatorStringDateattachment_codeStringnameStringlicense_codeStringfile_nameStringfile_typeString

xlsxlsx

file_dataString

file_url

file_urlStringdescriptionStringhash_codeStringextend_propsStringcreatorStringcreation_timeDateStringDateDB44/T

2167.3—2019表

B.5 证照信息

类（续）表

B.6证照附件

类24license_item_codeStringnameStringshort_nameStringversionStringstatusString

DB44xx

typeString

DB44xx

use_constraint_typeString

DB44xx

descriptionStringremarkStringissue_rankString

DB44xx

admin_orgStringStringdivisionStringdivision_codeString