DB3502/T 117.3-2023 国际贸易“单一窗口”数据服务 第3部分：报关服务接口

ICS35.240

CCSL77

3502

福建省厦门市地方标准

DB3502/T117.3—2023

国际贸易"单一窗口"数据服务

第3部分：报关服务接口

DataservicesforinternationaltradeSingleWindow—

Part3:Interfaceofcustomsclearanceservices

2023-12-28发布2023-12-28实施

厦门市市场监督管理局发布

DB3502/T117.3—2023

目次

前言.................................................................................II

引言................................................................................III

1范围...............................................................................1

2规范性引用文件.....................................................................1

3术语和定义.........................................................................1

4缩略语.............................................................................1

5基本要求...........................................................................1

6数据对接方式.......................................................................2

7服务接口设计基本规定...............................................................2

8业务服务接口.......................................................................4

附录A（资料性）接口示例............................................................43

附录B（资料性）通关字典............................................................61

I

DB3502/T117.3—2023

前言

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

起草。

本文件是DB3502/T117《国际贸易“单一窗口”数据服务》的第3部分。DB3502/T117已经发布了

以下部分：

——第1部分：总体技术要求；

——第2部分：报关业务数据元；

——第3部分：报关服务接口。

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

本文件由中国(福建)自由贸易试验区厦门片区管理委员会信息化服务中心提出。

本文件由中国(福建)自由贸易试验区厦门片区管理委员会归口。

本文件起草单位：中国(福建)自由贸易试验区厦门片区管理委员会信息化服务中心、北京国研数通

软件技术有限公司、厦门市标准化研究院、厦门自贸试验区电子口岸有限公司、中国厦门外轮代理有限

公司、厦门市人民政府口岸工作办公室、厦门海事局、厦门出入境边防检查总站

本文件主要起草人：吴志强、李童、王李强、郑建欣、林华、李倩文、刘裴寰、叶少鹏、杨晨、严

伟荣、吴永馨、周印亮、李红、徐锋、赵健、谢晓芳、胡流辉、李健、郑巍伟、陈瑀、李钊茜、詹永祥、

张建财、郭晓晨、张颖慧、陈劭彧

II

DB3502/T117.3—2023

引言

国际贸易“单一窗口”数据服务开放平台的建设，可以充分发掘数据资产价值，提升厦门“单一窗

口”创新服务效率，优化厦门市营商环境，积极服务“单一窗口”相关企业。DB3502/T117旨在确立数

据服务开放平台总体架构、技术架构、开放过程等的技术标准，为数据服务开放平台的建设提供基础规

范，拟由十七个部分组成。

——第1部分：总体技术要求；

——第2部分：报关业务数据元；

——第3部分：报关服务接口；

——第4部分：快件业务数据元；

——第5部分：快件业务服务接口；

——第6部分：运输工具数据元；

——第7部分：运输工具服务接口；

——第8部分：舱单业务数据元；

——第9部分：舱单业务服务接口；

——第10部分：跨境电商数据元；

——第11部分：跨境电商服务接口；

——第12部分：保税业务数据元；

——第13部分：保税业务服务接口；

——第14部分：服务目录；

——第15部分：安全管理要求；

——第16部分：数据服务流程；

——第17部分：运维服务要求。

报关服务接口用于规范报关业务领域内接口设计、数据传递方式、参数格式、交互流程等内容，支

持不同系统之间的集成和互操作性，确保数据传递的一致性和准确性，提高工作效率，降低维护成本，

支持业务流程自动化等，为特定业务领域内的系统交互提供了标准化的框架，促进了业务流程的顺畅进

行和信息交换的高效实现。

III

DB3502/T117.3—2023

国际贸易"单一窗口"数据服务

第3部分：报关服务接口

1范围

本文件规定了“单一窗口”数据服务开放平台提供的数据开放服务中报关服务相关接口。

本文件适用于相关企业业务系统调用开放的服务接口进行进出口报关申报。

2规范性引用文件

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

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

文件。

DB3502/T117.1国际贸易“单一窗口”数据服务第1部分：总体技术要求

DB3502/T117.2国际贸易“单一窗口”数据服务第2部分：报关业务数据元

3术语和定义

本文件没有需要界定的术语和定义。

4缩略语

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

AES：高级加密标准（AdvancedEncryptionStandard)

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

CA：证书认证机构(CertificateAuthority)

HTTP：超文本传输协议（HypertextTransferProtocol)

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

JSON：JavaScript对象标记(JavaScriptObjectNotation)

JWT：一种用于身份验证和授权的开放标准（JSONWebToken）

SM系列算法：国家商用密码算法

5基本要求

数据服务开放平台的接口应满足以下基本要求：

——实用性:能与不同企业报关进行业务对接、完成数据交换；

——安全性:数据交换过程中保护国家秘密、商业秘密和个人隐私；

——时效性:能实时完成数据交换。

1

DB3502/T117.3—2023

6数据对接方式

数据对接方式包括：

——专线+HTTPS；

——HTTPS+身份认证。

7服务接口设计基本规定

服务接口命名规定

服务接口的名称应采用厦门“单一窗口”业务的中文描述进行命名，服务接口业务描述为服务接口

所属领域以及业务含义描述。

服务接口编码规定

服务接口编码结构如图1所示，其中：

——服务版本：默认版本为V1，新版本则为V2，依次类推；

——业务分类：根据服务划分的类别以英文字母进行命名，保证每个业务分类唯一；

——业务服务名称：数字和字母组成的文本，保证服务接口提供方内唯一。

Https://{域名}/api/v1/{bizName}/{service}

服务版本业务分类业务服务名称

图1服务接口编码结构

示例：https://{域名}/api/v1/dataQuery/HSCIQController

传输协议应使用HTTP1.0/1.1标准或者HTTPS标准两种方式。采用HTTPS协议时，服务方应提供接口

调用需要的数字证书文件，证书文件应为“单一窗口”数据服务开放平台统一颁发的数字证书。

上下行服务接口说明

企业需要上报到数据服务开放平台的数据，调用数据服务开放平台相关的上行服务接口，数据服务

开放平台需要提供给各企业的数据，由企业从下行服务接口中调用相应的查询接口获取。其中，上行服

务接口以数据服务开放平台作为数据接收方对应的接口，下行服务接口以数据服务开放平台作为数据

提供方对应的接口。

接口技术类型

服务接口技术类型采用REST接口，使用GET或POST方法，返回报文数据格式为JSON格式。

交换数据类型

数据类型说明见DB3502/T117.2中数据元表示方法。

服务接口安全要求

2

DB3502/T117.3—2023

服务接口安全采用基于JWT开放标准（RFC7519）的签名设计方式实现，本文中所有的服务接口在

传输过程中，均采用国密SM2、SM3等国产算法进行加密，通过使用支持国产加密算法的工具库或框架来

实现对JWT的加密操作，在持久化存储至数据库过程中，则采用国产解密算法。

请求参数数据结构

请求头参数数据结构见表1，请求参数数据结构见表2，示例见附录A.1。

表1请求头参数数据结构

代码名称类型是否必填描述示例值

ContentTypeJSON是内容类型为JSON，编码类型为UTF-8application/json;charset=utf-8

ServiceVersionA..5是调用的接口版本1.0

TokenA..256是通过token服务获取token—

表2请求参数数据结构

代码名称类型是否必填描述示例值

ClientIDA..10是数据服务调用者身份标识—

EntTypeA2是数据服务调用者类型01

EntAccessTimeDateTime是数据服务调用时间—

数据服务调用者身份标识、服务标识、

签名秘钥由“单一窗口”数据服务开放

平台向企业下发。参数签名信息的生成

SignatureA..500否—

需要使用签名秘钥计算，计算的方式为

使用签名秘钥对请求者身份标识、服务

调用时间进行MD5加密获得

对称加密算法，支持：AES256、SM4，需

EncryptNameA..10否—

要加密时填写

EncryptKeyA..512否对称秘钥—

IC卡卡号，需要业务签名的接口必须填

IcCardNoA32否—

做业务的IC卡卡号

FormatA..40否业务节点的数据类型：默认JSON—

报文唯一标识，命名规范：EntID+yyyy-

MessageIdA..44是—

MM-ddHHmmss+4位自定义流水号

AccountNameA..33是实际业务方单一窗口登录账号—

ParamDataJSON是请求参数json字符串—

响应数据结构

响应数据结构见表3，示例见附录A.2。

表3响应数据结构

代码名称类型是否必填描述示例值

ClientIDA..10是返回代码—

RetTimeDateTime是返回时间—

3

DB3502/T117.3—2023

表3响应数据结构（续）

代码名称类型是否必填描述示例值

RetDataJSON是返回数据—

RetMsgA..500是返回消息—

数据服务调用者身份标识、服务标识、

签名秘钥由“单一窗口”数据服务开放

平台向企业下发。参数签名信息的生成

SignatureA..50否—

需要使用签名秘钥计算，计算的方式为

使用签名秘钥对请求者身份标识、服务

调用时间进行MD5或sm3加密获得

对称加密算法，支持：AES256、SM4，

EncryptNameA..10否—

需要加密时填写

EncryptKeyA..512否对称秘钥—

数据结构扩展字段定义

扩展字段（“FieldExtend”）内容通过JSON文本进行定义，基础数据结构扩展字段定义见表4，示

例见附录A.3。

注：请求参数和返回结果由于自贸区业务存在持续改进，本文件仅定义基础数据结构。

表4扩展字段定义

代码名称类型是否必填描述说明

ClientIDA..255是字段编码—

FieldnameA..255是字段名称—

fieldLengthN..5否字段长度—

fieldTypeA..50是字段类型—

fieldRequiredA1否字段是否必填—

fieldValueA..500否字段值—

8业务服务接口

业务流程描述

报关行报关流程见图2。货主/货代报关流程见图3。

4

DB3502/T117.3—2023

图2报关行报关流程

图3货主/货代报关流程

通用接口

8.2.1开放平台认证服务

数据服务开放平台采用Token认证，通过Token认证通用请求。请求方式为POST，请求参数说明见表

5，返回结果说明见表6，示例见附录A.4.1.1，其中：

——Header：Content-Type:application/json;charset=UTF-8

5

DB3502/T117.3—2023

——接口地址：https://{域名}/api/v1/auth/tokens

表5请求参数说明

序号代码名称中文名称类型是否必填说明

1ClientID客户端IDA..255是—

2ClientSecret客户端密码A..256是—

表6返回结果说明

序号代码名称中文名称类型是否必填说明

1RetCode返回代码A3是—

2RetTime返回时间DateTime是—

3UserId用户IDA.255是—

用户Token，计算的方式为使用签名秘钥对请

4UserToken用户TokenA..255是求者身份标识、服务调用时间进行MD5加密获

得。

5ExpireTimeToken过期时间N..255是—

8.2.2用户授权接口

对用户访问的数据服务进行服务权限的鉴定，判断其是否有权限访问该服务。请求方式为POST，请

求参数说明见表7，返回参数说明见表8，示例见附录A.4.1.2，其中：

——Header：Content-Type:application/json;charset=UTF-8

——接口地址：https://{域名}/api/v1/access/accessList

表7请求参数说明

序号代码名称中文名称类型是否必填说明

1UserID用户IDAN..32是—

2UserName用户名称AN..50是—

3ServiceApp应用名称AN..32是—

4IPAddress访问IP地址AN..50是—

5FieldExtend扩展字段JSON否—

表8返回参数说明

序号代码名称中文名称类型是否必填说明

1UserID用户IDAN..32是—

2UserName用户名称AN..50是—

3ServiceApp应用名称AN..32是—

4ServiceList访问服务列表JSON是—

5IPAddress访问IP地址AN..50是—

6FieldExtend扩展字段JSON否—

6

DB3502/T117.3—2023

8.2.3服务申请

企业在ERP或企业第三方应用调用需要的服务接口时需要发送服务申请到开放平台。请求方式为请

求方式为POST，请求参数说明见表9，返回结果说明见表10，示例见附录A.4.1.3，其中：

——Header：Content-Type:application/json;charset=UTF-8

——接口地址：https://{域名}/api/v1/Serv/ServiceApply

表9请求参数说明

序号代码名称中文名称类型是否必填说明

1ChannelId通道IdAN..36是—

时间戳yyyyMMddhhmmss，当前时间前后10分

2TimeStamp时间戳N14是

钟内有效

MD5.encode(通道ID+密钥+timestamp+

3HashSign签名AN32是

请求参数)

表10返回结果说明

序号代码名称中文名称类型是否必填说明

1ServiceList申请服务列表AN..10是—

2ServAccess服务访问权限A..60是—

3SerTimeLimit服务时间权限AN..120是—

服务访问次数权

4SerSumLimitAN..120否—

限

5FieldExtend扩展字段JSON否—

8.2.4数据申请

数据使用企业需要其他企业的数据，首先需要向其他企业进行申请使用，说明申请使用的用途、使

用期限、次数、范围等，请求方式为POST，请求参数说明见表11，返回结果说明见表12，示例见附录

A.4.1.4，其中：

——Header：Content-Type:application/json;charset=UTF-8

——接口地址：https://{域名}/api/v1/Serv/dataApply

表11请求参数说明

序号代码名称中文名称类型是否必填说明

1ChannelId通道IdAN..36是—

时间戳yyyyMMddhhmmss，当前时间前后10分

2TimeStamp时间戳N14是

钟内有效

MD5.encode(通道ID+密钥+timestamp+

3HashSign签名AN32是

请求参数)

表12返回结果说明

序号代码名称中文名称类型是否必填说明

1ServiceData数据内容AN...120是—

7

DB3502/T117.3—2023

表12返回结果说明（续）

序号代码名称中文名称类型是否必填说明

2dataUsing数据使用用途A..60是—

3dataTimeLimit数据时间范围AN..120否—

4dataSumLimit数据使用次数AN..120否—

5DataUnit申请企业AN..120是—

6DataPUnit授权企业AN..120是—

7FieldExtend扩展字段JSON否—

8.2.5数据授权

企业对本企业数据授权给申请数据的企业进行授权服务，请求方式为POST，请求参数说明见表13，

返回结果说明见表14，示例见附录A.4.1.5，其中：

——Header：Content-Type:application/json;charset=UTF-8

——接口地址：https://{域名}/api/v1/Serv/dataAccess

表13请求参数说明

序号代码名称中文名称类型是否必填说明

1ChannelId通道IdAN..36是—

时间戳yyyyMMddhhmmss，当前时间前后10分

2TimeStamp时间戳N14是

钟内有效

MD5.encode(通道ID+密钥+timestamp+

3HashSign签名AN32是

请求参数)