山西省《政务数据共享交换平台 服务接口管理规范》

DB14/TXXXX—XXXX

政务数据共享交换平台服务接口管理规范

1范围

本文件规定了政务数据共享交换平台用于共享服务接口的基本要求、接口设计、接口开发、接口文

档、注册与发布、变更与撤销、申请与使用、接口安全等方面的要求。

本文件适用于省级政务数据共享交换平台的共享服务接口管理，市县级政务数据共享交换平台的共

享服务接口管理可参考使用。

2规范性引用文件

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

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

文件。

GB/T38664.1—2020信息技术大数据政务数据开放共享第1部分：总则

GB/T39477—2020信息安全技术政务信息共享数据安全技术要求

GB/T42877—2023气象数据服务接口规范

3术语和定义

GB/T38664.1—2020、GB/T39477—2020、GB/T42877—2023界定的以及下列术语和定义适用于本

文件。

3.1

政务数据共享交换平台

共享交换平台

由各级人民政府确定的面向各级政务部门，维护政务数据资源目录，汇聚基础数据资源、管理共享

交换需求，提供数据安全与运行监控保障，支撑跨部门、跨地区开展政务数据共享交换的关键信息基础

设施。

[来源：GB/T38664.1—2020，3.5，有修改]

3.2

服务接口

接口

在政务数据共享过程中，为提供特定业务服务功能而发布的可供其他系统调用的应用编程函数。

[来源：GB/T42877—2023，3.2，有修改]

3.3

服务提供方

通过政务数据共享交换平台，为其他部门提供政务数据共享服务接口并且是责任主体的政务部门或

组织机构。

[来源：GB/T39477—2020，3.3，有修改]

3

DB14/TXXXX—XXXX

3.4

服务使用方

根据履行职责需要，通过政务数据共享交换平台，使用其他部门提供的政务数据共享服务接口的政

务部门或组织机构。

[来源：GB/T39477—2020，3.5，有修改]

3.5

接口授权码

服务使用方的使用申请通过审核后，共享交换平台为服务使用方生成调用该接口的唯一验证和授权

接口访问的编码。

4缩略语

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

HTTP：超文本传输协议（HyperTextTransferProtocol）

HTTPS：超文本传输安全协议（HyperTextTransferProtocolSecure）

SOAP：简单对象访问协议（SimpleObjectAccessProtocol）

JSON：JavaScript对象表示法（JavaScriptObjectNotation）

XML：可扩展标记语言（ExtensibleMarkupLanguage）

OAuth：开放的授权协议（OpenAuthorization）

JWT：基于JSON格式的轻量级、自包含的身份验证和授权机制（JSONWebToken）

API：应用程序接口（ApplicationProgrammingInterface）

5基本要求

a)接口的设计与开发应名称清晰、明确，路径规整，请求方式规范，有版本控制，高效、安全、

稳定且易于维护；

b)接口文档应内容明确、结构清晰、易于阅读和理解，且文档中不能暴露原始接口地址、认证

信息等，文档模板参考附录B；

c)接口的注册与发布、撤销与变更、申请与使用应符合本级共享交换平台要求；

d)共享交换平台、服务提供方、服务使用方均应对接口开展相应安全管理。

6接口设计

6.1安全性

接口应采用安全的技术和协议，如HTTPS、加密传输等，确保数据在传输和存储过程中的安全性。

同时，应建立接口的身份验证和权限管理机制，确保只有授权用户才能访问数据。

6.2时效性

接口应确保提供的数据是最新的，能够反映当前最新的政务数据状态，以满足用户对最新信息的需

求。

6.3准确性

4

DB14/TXXXX—XXXX

数据应准确，不存在错误、遗漏或误导性信息。应建立接口数据源校验机制，确保数据在传输和处

理过程中不被篡改或损坏。

6.4完整性

接口应提供完整的数据集，包括所有必要的信息和关联数据。对于需要跨多个系统或部门获取的数

据，接口应能够整合和提供完整的数据视图。

6.5稳定性

接口应具有高度的稳定性，能够持续稳定地提供服务，稳定性应达到99.99%以上。接口应具备良好

的容错和恢复能力，能够自动检测和修复错误，并在必要时进行故障转移和负载均衡。

6.6开放性

应采用通用、主流的接口设计方法及协议，保证与其他系统的互联互通。

6.7松耦合

接口应能与提供方的部门业务系统解耦，发生故障不应影响到部门业务系统使用。

6.8高内聚

接口设计时需满足以下要求：

——功能明确，接口应只负责一个明确的功能或一组紧密相关的功能，避免将多个不相关的功能

混合在一个接口中；

——粒度适中，接口应既不过于庞大导致功能复杂，也不过于细碎导致调用繁琐；

——减少内部依赖，接口内部应减少对其他模块的依赖，降低模块间的耦合度，提高接口的独立

性和可重用性。

6.9可扩展性

接口应具备良好的可扩展性，能够满足服务使用方对接口响应时间、并发数等的技术要求。如利用

负载实现接口的横向可扩展等。

6.10易用性

接口应提供清晰、简洁的文档和示例代码，方便用户理解和使用。同时，接口应提供友好的错误提

示和日志记录功能，帮助用户快速定位和解决问题。

7接口开发

7.1版本控制

接口开发时应做好版本控制，版本升级时应不影响已发布版本的使用。

7.2接口地址

接口应有且只能有一个服务路径作为接口地址，不应多个接口共用一个服务路径。

7.2.1接口协议类型

5

DB14/TXXXX—XXXX

共享交换平台应只支持基于HTTP或SOAP协议的接口，协议不同时，应由服务提供方进行协议转换。

7.2.2接口分类

接口分类见表1。

表1接口分类

序号分类名称

1查询类

2验证类

3数据传输类

4下载类

5其他类

7.2.3接口参数

开发接口时，授权信息宜放在消息体的请求头，设计参数不应与各级平台的保留字冲突，保留字清

单应符合附录A中的相关规定。

7.2.4返回数据

服务提供方应规范数据的返回格式，并采用固定的数据格式封装。返回数据应清晰易懂，并包括结

果状态码及相应的提示信息。

7.2.5状态码

服务提供方应当做好服务响应状态码的规划管理，并在接口文档中进行详细说明。

8接口文档

8.1.1接口名称

清晰、简洁地命名接口，应与接口功能和用途相关。

8.1.2接口版本

接口版本信息包括但不限于：

a)版本信息：明确标记接口的版本信息；

b)更新历史：记录接口的更新历史，包括更新日期、更新内容等信息，便于开发人员了解接口

变化情况。

8.1.3接口描述

清晰简洁的描述接口功能及用途。

8.1.4接口认证

对于访问时需要认证的接口，应列明支持的认证方法，如OAuth2.0、JWT、API密钥、基本认证等。

并提供示例展示如何在请求中包含必要的认证信息，以及如何处理响应中的认证结果。

8.1.5请求方法

6

DB14/TXXXX—XXXX

标明接口支持的HTTP请求方法，如GET、POST等,SOAP协议不需要填写。

8.1.6请求参数

请求参数信息包括但不限于：

a)参数列表：详细列出所有请求参数，包括字段名、类型（如String、Number、Object、Array

等）、是否必填、长度、描述等信息；

b)参数示例：对于复杂结构的请求参数（如JSON或XML），提供示例数据便于开发人员理解。

8.1.7返回参数

返回参数信息包括但不限于：

a)数据类型与格式：列出返回值的数据类型、格式和示例数据，以便开发人员正确处理返回数

据；

b)状态码与错误信息：列出接口可能返回的错误码及其含义，确保开发人员能够正确处理接口

返回的错误信息。

8.1.8使用示例

使用示例信息包括但不限于：

a)请求示例：提供使用接口的示例请求，如CURL命令、Java脚本等，帮助开发人员更好地理解

接口的使用方法；

b)响应示例：给出接口的响应示例，包括正确的响应和可能的错误响应。

8.1.9申请材料

应明确接口申请时需要额外提交到共享交换平台的材料，有格式要求的应提供模版。

8.1.10数据字典

请求参数或者返回参数中数据类型为布尔、枚举等类型的需要额外解释、说明或规范的数据元素，

应在数据字典中进行详细描述和定义，以确保接口的正确理解和实现。

9注册与发布

9.1注册

服务提供方应按照各级共享交换平台的要求注册接口，注册时应满足以下要求：

a)资源名称应采用中文名称，且应准确描述接口能够提供的业务、能力及分类等信息，方便使

用方进行查询与检索；

b)应准确描述接口其他信息，如请求方法、请求参数、返回参数、接口描述、每天最大调用次

数、超时设置、技术支持信息等；

c)注册完成后，应生成本级共享交换平台唯一的资源编码。

9.2发布

接口注册完成后，应由服务提供方、共享交换平台管理方进行审核，通过后发布到共享交换平台。

审核内容包括但不限于接口描述、接口名称、接口方式、接口地址、授权方式、入参出参、调用示例等。

7

DB14/TXXXX—XXXX

10变更与撤消

10.1变更

10.1.1接口有部门使用时的变更

变更应符合以下要求：

a)服务提供方应先行评估变更影响，优先保障已对接接口业务的正常使用；

b)变更时，应向共享交换平台管理方发起变更申请，说明变更事由、变更影响、变更内容、变

更计划等信息，变更计划制定时需征询服务使用方的意见，服务使用方需要进行同步变更的，

需预留一定的变更时间；

c)共享交换平台管理方应对变更事由、变更影响、变更内容、变更计划等信息进行审核，通过

后完成资源发布；

d)变更执行应选择非工作时间进行，服务提供方应做好版本控制，参与联调测试，测试失败时

应及时回滚。

10.1.2接口无部门使用时的变更

变更应符合以下要求：

a)变更时，应向共享交换平台管理方发起变更申请，说明变更事由、变更内容、变更计划等信

息；

b)共享交换平台管理方进行变更审核,通过后完成资源发布。

10.2撤销

10.2.1接口有部门使用时的撤销

撤销应符合以下要求：

a)服务提供方应先行评估撤销的影响，优先保障已对接接口业务的正常使用，有影响时需延迟

撤销操作或者提供替代方案；

b)撤销时，应向共享交换平台管理方发起撤销申请，说明撤销事由、撤销影响、撤销计划等信

息。撤销计划制定时需征询相关使用方的意见，给服务使用方预留一定的业务变更时间；

c)共享交换平台管理方应对撤销事由、撤销影响、撤销计划等信息进行审核，通过后共享交换

平台应向相关业务部门发出撤销通知；

d)撤销执行宜按撤销计划选择非工作时间进行。

10.2.2接口无部门使用时的撤销

撤销应符合以下要求：

a)服务提供方向共享交换平台发起申请，说明撤销的原因，计划撤销时间等；

b)共享交换平台管理方应对撤销申请进行审核，通过后按计划撤销接口。

11申请与使用

11.1申请

服务使用方申请接口时，应符合如下要求：

8

DB14/TXXXX—XXXX

a)服务使用方应按共享交换平台及所申请接口服务提供方的要求，提交接口申请表（参考附录C）

和服务提供方要求的资料。

b)申请提交后由各级共享交换平台及服务提供方进行多级审核。

c)审核通过后，由共享交换平台为服务使用方提供接口授权码、接口地址及接口文档等相关信

息。

11.2使用

服务使用方获取使用授权后开展接口的对接及业务实现工作，应符合如下要求：

a)接口用于互联网或跨网应用时，要确保联接方式及安全策略符合有关要求；

b)服务使用方应仔细参阅平台提供的接口文档，按照文档要求数据格式、传输协议、接口地址、

请求方式等，开展接口的对接及业务实现工作；

12接口安全

12.1对共享交换平台的要求

主要包括：

a)应做好接口发布、申请审核的管理及审核工作；

b)应建设相关接口的安全保护能力，包括授权、认证、访问限流、并发限制等，确保接口安全

与稳定；

c)应对接口调用情况进行详细的日志记录，以便在发生安全事件时进行追溯和审计。

12.2对服务提供方的要求

主要包括：

a)接口发布前应对接口数据进行数据安全检查与评估，识别数据安全风险，存在风险的应采取

额外的保护措施确保数据不被非法获取或滥用，如数据加密、数据脱敏等；

b)接口发布前应确保接口不存在安全漏洞；

c)接口发布后应定期对接口等进行安全性检查和漏洞扫描，及时修复存在的安全漏洞；

d)应对接口调用情况进行详细的日志记录，以便在发生安全事件时进行追溯和审计。

12.3对服务使用方的要求

主要包括：

a)应妥善保管接口访问认证授权信息，不得向第三方泄露，且不得将接口用于非授权用途；

b)应定期对使用接口开发的应用系统等进行安全性检查和漏洞扫描，及时修复存在的安全漏洞；

c)应遵守共享交换平台设定的接口调用频率、数据格式和传输协议进行接口调用，不应对共享

交换平台进行恶意请求或滥用接口；

d)服务使用方使用接口开展业务的过程中应符合有关安全要求。

e)应根据数据的敏感程度结合应用场景使用合适的加密、脱敏算法等技术手段对接口返回的敏

感数据进行保护；

f)应对使用接口的用户进行身份验证和授权管理，并记录用户的操作日志以便跟踪和审计。

9

DB14/TXXXX—XXXX

附录A

（规范性）

保留字清单

保留字应符合表A.1的要求。

表A.1保留字清单

序号保留字说明备注

1sxspt_rid请求者标识

2要调用的服务编码

sxspt_sid省政务数据共享交换平台

3sxspt_rtime请求的时间戳

4sxspt_sign发送方签名

5client_id请求者标识

6client_secret请求者秘钥太原市政务数据共享交换平台

7access_token请求授权码

8请求者标识

appCode大同市政务数据共享交换平台

9apiToken请求者授权码

10appkey请求者标识朔州、忻州、阳泉、晋中、吕梁、长治、运

城市政务数据共享交换平台

11X-Client-Id请求者标识

12时间戳

X-Timestamp省级数据直达系统

13X-Nonce随机字符串

14X-Signature数字签名

A

B

10

DB14/TXXXX—XXXX

附录B

（资料性）

接口文档模版

B.1接口名称

清晰、简洁地命名接口，使其与接口功能和用途相关。如“企业基本信息批量获取接口”。

B.2接口版本

明确标记接口的版本信息。

B.3接口描述

清晰、简洁描述接口功能及用途。

B.4接口认证

对于访问时需要认证的接口，需要列明认证方法，如OAuth2.0、JWT、API密钥、基本认证等。并

提供示例展示如何在请求中包含必要的认证信息，以及如何处理响应中的认证结果。

B.5请求方法

标明接口支持的HTTP请求方法，如GET、POST等,SOAP协议不需要填写。

B.6请求参数

请求参数填入表B.1。

表B.1请求参数

序号必填字段名称字段描述数据类型长度备注

1.Y字典见表B.2数据字典

2.N

3.

B.7返回参数

返回参数填入表B.2。

表B.2返回参数

序号字段名称字段描述数据类型长度备注

1

2

3

4

5

6

11

DB14/TXXXX—XXXX

B.8使用示例

B.8.1请求示例

提供详细的接口请求示例。

B.8.2响应示例

提供详细的接口响应示例，相关状态见表B.3状态码。

表B.3状态码

序号状态码状态描述

1

2

3

B.9申请材料

明确接口申请时需要额外提交到共享交换平台的材料，有格式要求的应提供模版。

B.10数据字典

数据字典填入表B.4。

表B.4数据字典

序号字典码字典名称备注

1

2

3

12

DB14/TXXXX—XXXX

附录C

（资料性）

接口申请模版

接口申请模板见表C.1。

表C.1接口申请模版

信息项目内容填写说明

申请服务接口名称填写数据资源名称，且只允许填一个

服务接口提供单位

填写数据提供单位全称

名称

服务接口使用单位

填写数据使用单位全称

名称

基本

信息使用单位社会统一填写数据使用单位社会统一信用代

信用代码码

填写数据使用单位数据使用部门负

负责人姓名、电话

责人联系方式

经办人姓名、电话及

填写经办人联系方式

邮箱

填写服务接口使用到哪一个政务服

政务服务事项和业务事项的哪一个业务环节。如“办理

（有该需求时如实填写）

务环节婚姻登记事项，在受理环节进行双方

身份信息核验”。

填写通过数据接口服务进行批量数

数据批量比对数据的方据比对时实施方案概述，如比对目

（有该需求时如实填写）

应用案概述的、比对库描述、比对方式、数据安

场景全措施等内容

信息

填写通过数据接口服务进行业务系

（须明业务系统协同的方

（有该需求时如实填写）统协同的实施方案概述，如数据调用

确具体案概述

方式、数据安全措施等内容

场景）

预期应用成效数据应用预期成效

填写数据申请依据的文件题目和文

申请依据号，具体文件单独附上，并标注依据

条款（章节）

13

DB14/TXXXX—XXXX

表C.1接口申请模版（续）

业务系统名称（代填写数据接口服务拟应用的业务系

码）统名称

业务系统的政务外填写业务系统服务器使用的国家电

网IP子政务外网公共区IP地址

业务系统部署地点填写业务系统部署的地点

填写服务接口每天使用次数，必须同

技术服务接口每天使用

时标明平均值和峰值，如平均200

信息频次

次/天、峰值10000次/天

服务接口使用时间填写接口调用时间段，如工作日

范围9:00到17:00

填写使用期限，使用期限不得多于3

服务接口使用期限

年

接口使用其他技术基于特定服务接口的具体技术要求，

请求可另附表格详细说明

安全责任人及联系填写数据安全负责人联系方式（不允

方式许填写技术支持公司人员）

安全1.在申请范围内使用数据。

信息2.严格保护国家秘密、个人敏感信息和商

安全承诺业秘密。安全责任人签字承诺

3.确保数据存储、使用安全可控。

安全责任人（签字）：

承诺如下：本表提供的资料、信息全部属实。

经办人（签字）：

数据使用单位全称（盖章）：

数据使用

单位盖章

申请日期：

14

ICS35.240.01

CCSL67

14

山西省地方标准

DB14/TXXXX—XXXX

政务数据共享交换平台服务接口管理规范

（征求意见稿）

在提交反馈意见时，请将您知道的相关专利连同支持性文件一并附上。

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

山西省市场监督管理局  发布

DB14/TXXXX—XXXX

政务数据共享交换平台服务接口管理规范

1范围

本文件规定了政务数据共享交换平台用于共享服务接口的基本要求、接口设计、接口开发、接口文

档、注册与发布、变更与撤销、申请与使用、接口安全等方面的要求。

本文件适用于省级政务数据共享交换平台的共享服务接口管理，市县级政务数据共享交换平台的共

享服务接口管理可参考使用。

2规范性引用文件

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

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

文件。

GB/T38664.1—2020信息技术大数据政务数据开放共享第1部分：总则

GB/T39477—2020信息安全技术政务信息共享数据安全技术要求

GB/T42877—2023气象数据服务接口规范

3术语和定义

GB/T38664.1—2020、GB/T39477—2020、GB/T42877—2023界定的以及下列术语和定义适用于本

文件。

3.1

政务数据共享交换平台

共享交换平台

由各级人民政府确定的面向各级政务部门，维护政务数据资源目录，汇聚基础数据资源、管理共享

交换需求，提供数据安全与运行监控保障，支撑跨部门、跨地区开展政务数据共享交换的关键信息基础

设施。

[来源：GB/T38664.1—2020，3.5，有修改]

3.2

服务接口

接口

在政务数据共享过程中，为提供特定业务服务功能而发布的可供其他系统调用的应用编程函数。

[来源：GB/T42877—2023，3.2，有修改]

3.3

服务提供方

通过政务数据共享交换平台，为其他部门提供政务数据共享服务接口并且是责任主体的政务部门或

组织机构。

[来源：GB/T39477—2020，3.3，有修改]

3

DB14/TXXXX—XXXX

3.4

服务使用方

根据履行职责需要，通过政务数据共享交换平台，使用其他部门提供的政务数据共享服务接口的政

务部门或组织机构。

[来源：GB/T39477—2020，3.5，有修改]

3.5

接口授权码

服务使用方的使用申请通过审核后，共享交