ICS 35.240.01 L 67 DB44 广 东 省 地 方 标 准 DB44/T 2167.3—2019 广东省电子证照技术规范 第 3 部分：接口规范 Electronic certificate technical specification Part 3:Interface specification 2019 - 07 - 12 发布 广东省市场监督管理局 2019 - 10 - 01 实施 发 布 DB44/T 2167.3—2019 目 次 前言 ................................................................................ II 1 范围 .............................................................................. 1 2 系统接口概述 ...................................................................... 1 2.1 接口组成 ...................................................................... 1 2.2 接口技术要求 .................................................................. 1 2.3 接口使用 ...................................................................... 1 3 接口模型及参数 .................................................................... 2 3.1 请求模型 ...................................................................... 2 3.2 返回模型 ...................................................................... 3 3.3 接口参数 ...................................................................... 4 附录 A（规范性附录） 接口及其参数说明 ................................................ 5 附录 B（规范性附录） 公共参数及数据类型 ............................................. 22 附录 C（规范性附录） 错误分类代码 ................................................... 27 参 考 文 献 ...................................................................... 30 I DB44/T 2167.3—2019 前 言 DB44/T 2167《广东省电子证照技术规范》分为4个部分： ——第 1 部分：总体构架； ——第 2 部分：数据规范； ——第 3 部分：接口规范； ——第 4 部分：应用与技术管理要求。 本部分为DB44/T 2167的第3部分。 本部分按照GB/T 1.1-2009给出的规则起草。 本部分的附录A、附录B、附录C为规范性附录。 本部分由广东省工业和信息化厅提出。 本部分由广东省信息技术标准化技术委员会归口。 本部分的主要起草单位：工业和信息化部电子第五研究所、广东省信息中心、广东省标准化研究院。 本部分主要起草人：周春华、王贵虎、王韬、丁曙初、马晓镌、梁宏、何铤、肖晓赟、黎东初。 II DB44/T 2167.3—2019 广东省电子证照技术规范 第 3 部分：接口规范 1 范围 DB44/T 2167的本部分规定了其他电子政务系统与电子证照系统进行对接的接口规范。 本部分适用于与政务电子证照系统的对接。 2 系统接口概述 2.1 接口组成 电子证照系统应包括电子证照目录查询接口、电子证照信息管理接口、安全会话接口和用证服务 接口。 a) 电子证照目录查询接口 应提供电子证照全省目录、地区和部门应开通目录查询功能。 b) 证照信息管理接口 应提供电子证照制证、签发、更新、废止等功能。 c) 安全会话接口 应提供对接入应用和用户身份进行合法性验证等功能。 d) 用证服务接口 应提供对电子证照进行查询、调用和有效性、归档等功能。 2.2 接口技术要求 a) b) c) d) 采用基于 Web Service 技术服务接口； 接口的请求和返回结果采用 JSON 格式； 应支持跨系统、跨平台调用； 传输的数据应采用加密和防篡改技术保证数据的完整有效性。 2.3 接口使用 接口使用前，应对使用接口的应用系统进行身份认证，确保访问接口的应用都经过授权。认证方式 可采用app_key和app_secret方式或CA证书方式。以下给出app_key和app_secret认证方式接口使用可参 考流程： 1 DB44/T 2167.3—2019 电子证照系统 其他电子政务系统 1 注册和申请授权 2 返回app_key和app_secret 3 以app_key和app_secret 为参数调用登录接口 4 返回access_token 5 带access_token参数数据访问 6 返回相应数据 7 结束调用 图1 接口使用流程图 1) 2) 3) 4) 5) 6) 7) 其他电子政务系统向电子证照系统进行应用注册和申请授权； 审核通过后返回应用唯一标识（app_key）和密钥（app_secret）； 其他电子政务系统调用登录接口，在参数中加入 app_key 和 app_secret，创建会话； 电子证照系统返回接入令牌（access_token）； 在会话有效期内通过加入 access_token 参数进行接口调用； 电子证照系统返回相应数据； 会话超时或通过注销接口结束调用。 3 接口模型及参数 3.1 请求模型 2 DB44/T 2167.3—2019 图2 接口请求模型数据结构 接口请求模型（RequestModel）由接口名称（InterfaceName） 、请求参数集（RequestParameterSet）、 附件集（AttachmentSet）组成，实线连接内容为必选项，虚线连接内容为可选项。 ——接口名称。 接口名称指定将要调用的接口。 ——参数集。 结构化请求参数集，登录接口必须包含 app_key 和 app_secret，其它接口必须至少包含请求 公共参数。每个参数由参数名（Name）和参数值（Value）、参数类型（Type）组成。 ——附件集 不含或含一个及以上附件。每个附件由附件名（Name） 、附件链接地址（URL） 、附件类型（Type）、 附件内容（Content）和附件描述（Despription）组成，附件链接地址和附件内容至少包含一项。 3.2 返回模型 3 DB44/T 2167.3—2019 图3 接口返回模型数据结构 接 口 返 回 模 型 （ ResponseModel ） 由 返 回 结 果 参 数 集 （ ResponseParameterSet ） 、 附 件 集 （AttachmentSet）组成。 ——返回结果参数集 结构化的返回结果参数集，应至少包括返回公共参数。每个参数由参数名（Name）和参数值 （Value） 、参数类型（Type）组成。 ——附件集 附件集为可选内容，不含或含一个以上附件，定义与接口请求模型相同。 3.3 接口参数 接口的具体请求和返回参数应符合附录A要求。请求公共参数和返回公共参数应符合附录B.1要求。 4 DB44/T 2167.3—2019 附 录 A （规范性附录） 接口及其参数说明 A.1 安全会话接口 A.1.1 登录 登录是接口系统调用的第一个方法。通过调用登录接口进行身份验证，验证成功后创建一个会话， 所有对数据和附件的管理操作都必须在有效的会话内进行，会话应有失效时间。此接口不包含公用参数。 请求参数： 表 A.1 登录请求参数 参数名 是否必选 类型 说明 app_key 是 String 分配给应用程序的唯一标识 app_key app_secret 是 String 分配给应用程序的密钥 app_secret account 是 String 用户账户名称 password 是 String 用户账户密码 org_code 否 String 以指定的部门管理员身份登录 返回结果： 表 A.2 登录返回结果参数 参数名 是否必选 类型 说明 ack_code 是 String 成功：SUCCESS，失败 FAILURE errors 是 String 无错误时为空，有错误返回错误信息 access_token 是 String 登录成功则返回安全会话访问令牌（一天有效） A.1.2 注销 注销当前会话。 请求参数： 无。 （仅包含请求公共参数） 返回结果： 无。 （仅包含返回公共参数） 。 A.1.3 获取当前已登录用户信息 获取当前已登录用户的信息。 请求参数： 5 DB44/T 2167.3—2019 无。 （仅包含请求公共参数） 返回结果： 表 A.3 注销返回结果参数 参数名 data 是否必选 类型 是 UserInfo 说明 用户信息 A.2 电子证照目录接口 A.2.1 查询全省目录 列举出全省目录清单。 请求参数： 表 A.4 查询全省目录请求参数 参数名 是否必选 类型 说明 page_index 否 Integer 返回第几页数据。默认值 1 page_size 否 Integer 返回数据的每页大小。默认值 10，最大值 150 keyword 否 String 查询关键字（证照名称，目录编制部门） status 否 LicenseItemStatus 证照状态（默认查询已发布，多个时中间以逗号（,）分割） is_open 否 Boolean 开通状态（默认已开通） 注：为兼容现有系统，在接口参数中，使用licen