DB23∕T 3156-2022 政务信息共享交换平台接口接入

ICS35.240.01

CCSL67

DB23

黑龙江省地方标准

DB23/TXXXX—XXXX

政务信息共享交换平台

接口接入

XXXX-XX-XX发布XXXX-XX-XX实施

黑龙江省市场监督管理局发布

DB23/TXXXX-XXXX

前言

本文件依据GB/T1.1-2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起

草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。

本文件由黑龙江省营商环境建设监督局提出并归口。

本文件起草单位：黑龙江省营商环境建设监督局、黑龙江省标准化研究院、浪潮软件集团有限公司。

本文件主要起草人：张建峰、谭嘉宁、王艳君、侯雨含、江中阳、于运来、董鹏飞、张桐瑗、陈要

武、杨大志、吕猛、李严。

I

DB23/TXXXX-XXXX

政务信息共享交换平台接口接入

1范围

本文件规定了黑龙江省政务信息共享交换平台应用程序接口接入的总体架构，以及接口接入的要

求。

本文件适用于黑龙江省政务信息资源数据提供方接口接入的开发、建设和应用。

2规范性引用文件

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

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

文件。

本文件没有规范性引用文件

3术语和定义

下列术语和定义适用于本文件。

3.1

政务信息资源

政务部门在履行职责过程中制作或获取的，以一定形式记录、保存的文件、资料、图表和数据等各

类信息资源，包括政务部门直接或通过第三方依法采集的、依法授权管理的和因履行职责需要依托政务

信息系统形成的信息资源等。

3.2

ApplicationProgrammingInterface

应用程序接口,是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的

约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理

解内部工作机制的细节。通过程序调用接口，通常用于查询或核验信息。

4缩略语

下列缩略语适用于本文件。

API：应用程序接口，（ApplicationProgrammingInterface）

URL：每一信息资源都有统一的且在网上唯一的地址，该地址就叫URL，（UniformResourceLocator）

5接口接入总体要求

5.1接口设计原则

接口开发者在设计接口的时候，可以参考以下接口原则：

1

DB23/TXXXX-XXXX

a)安全可靠性原则：系统应提供良好的安全性和可靠性策略，支持多种安全而可靠的技术手段，

制定严格的安全可靠的管理措施；

b)开放性原则：提供统一、开放式标准接口，确保与其它系统的互联互通；

c)灵活性原则：提供灵活的接口设计，适宜接口的变动；

d)可扩展性原则：支持新业务的扩展以及接口容量与接口性能的提高；

e)可管理性原则：提供良好的管理机制，确保在运行过程中提供给管理员方便的管理方式以处理

各种情况；

f)统一性原则：当保证系统的接口方式、接口形式、使用的协议等标准、统一。

5.2API接口规范

5.2.1概述

API接口最大的特点就是既能让资源提供方开放自己的资源访问权限，又能确保数据安全性并让资

源提供方继续握有控制权。资源提供方要根据业务情况描述接口功能，并按照API规范进行开发接口，

能够让使用方更好的应用接口。

5.2.2协议

API与客户端用户的通信协议，常用HTTP超文本传输协议和HTTPS安全超文本传输协议两种。

5.2.3接口类型

查询类接口常用接口类型主要有以下两种：

a)HTTPAPI接口：请求报文通常为Key-Value形式，返回报文一般为JSON串，有GET和POST

等方法；

b)WebService接口：通常走SOAP协议通过HTTP传输，请求报文和返回报文都是XML格式。

5.2.4版本控制

应该将API的版本号放入URL。

采用多版本并存、增量发布的方式，对于一个API或服务，应在生产中最多保留3个最详

细的版本。版本号分为整型和浮点型，整型：大功能版本，如v1、v2；浮点型：补充功能版本，如v1.1、

v2.1。

5.2.5请求方式

查询类接口常用请求方式主要有以下两种方式：

a)GET：从服务器取出资源（一项或多项）；

b)POST：在服务器新建一个资源。

5.2.6请求参数

接口入参一般为XML、JSON格式，常用传入参数主要分为3种类型：

a)Params：URL后面的参数，存放请求接口的参数数据；

b)Header：消息头，根据需要存放公共参数、RequestId（请求者标识）、Token（身份验证令牌）、

加密字段等；

c)Body：消息体，存放请求接口的参数数据。

注：资源提供方根据共享要求及相关安全考虑，可在接口入参中增加调用IP、访问人身份证号、调用时间戳等字段。

2

DB23/TXXXX-XXXX

5.2.7过滤信息

若记录数量很多，服务器不可能返回全部记录给用户，API应该提供分页参数及其它筛选参数，过

滤返回结果。

5.2.8返回参数

返回参数包括：

a)code：接口响应状态代码，资源提供方可自行定义。如接口调用成功，返回200；

b)msg：对Status返回的代码进行具体解释。如接口调用失败，返回具体错误信息；

c)data：接口返回的具体数据。

示例：

{

"code":"200",

"msg":"接口调用成功",

"data":"{\"error\":\"该人员未参加失业保险\"}"

}

5.2.9其他

其他内容包括：

a)如有业务需要，接口设计时应考虑限流设计、熔断设计、降级设计等；

b)如有业务需要，接口设计时应考虑敏感数据脱敏处理，部分数据加“*”号处理；

c)日志平台设计：日志平台有利于故障定位和日志统计分析；

d)当记录数量很多时，API应该提供分页参数及其它筛选参数，过滤返回结果。

5.2.10接口文档

接口文档中应包含以下内容：

a)接口地址：不包含接口BASE地址；

b)请求方式:GET、POST等；

c)请求参数：数据格式（默认JSON）、参数含义、参数类型、长度、精度等；

d)响应参数：参数含义、参数类型、值域等；

e)错误代码表；

f)其他：如算法生成说明，例Token。

注：当接口发生变化时，应及时更新接口文档并提供给资源需求方。

6接口接入流程

6.1接口接入流程图

接口接入流程图见图1。

3

DB23/TXXXX-XXXX

图1接口接入流程图

6.2接口接入准备阶段

6.2.1接口开发

资源提供方需根据接口需要开发相应的接口，并提供一份接口使用说明文档。

6.2.2存量数据处理

接口后台的数据应保证其实时性及全面性，并且数据有更新时应保证接口的返回参数尽量不会发生

改变。

6.2.3资源确认

省数据共享交换平台需确认资源提供方提供的接口是否符合的要求。

6.2.4接口测试

4

DB23/TXXXX-XXXX

确认接口符合要求后，资源提供方需提供接口测试环境访问地址、接口入参等相关信息，由省数据

共享交换平台对接口进行联调，测试接口是否可以正常使用。

6.2.5资源注册、审核

省数据共享交换平台，将资源提供方提供的接口在平台上进行接口注册，并进行资源审核。

6.2.6接口上线

省数据共享交换平台对接口进行测试且能够正常使用后，可将接口发布上线。

7特殊情况处理

如发生如下情况，需要通知省数据共享交换平台，并重新调试接口：

a)原始接口地址发生变化；

b)原始接口返回参数发生变化；

c)原始接口遇到如服务器升级、网络异常导致接口不通。

5

DB23/TXXXX-XXXX

参 考 文 献

[1]《政务信息资源共享管理暂行办法》（国发〔2016〕51号）

[2]《政务信息系统整合共享实施方案》（国办发〔2017〕39号）

[3]国家发展改革委关于印发“十三五”国家政务信息化工程建设规划的通知》（发改高技〔2017〕

1449号）

[4]国务院关于加快推进全