基于区块链的港航集装箱信息交换平台及接口技术要求

JT/TXXXXX—XXXX

基于区块链的港航集装箱信息交换平台及接口技术要求

1范围

本文件规定了基于区块链的港航集装箱信息交换平台要求和接口要求。

本文件适用于基于区块链的港航集装箱信息交换平台及接口的设计和应用。

2规范性引用文件

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

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

文件。

GB/T34990信息安全技术信息系统安全管理平台技术要求和测评评价方法

JT/T1417交通运输行业网络安全等级保护基本要求

YD/T3747区块链技术架构安全要求

RFC2616超文本传输协议HTTP1.1（HypertextTransferProtocol--HTTP/1.1）

3术语和定义

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

分布式账本distributedledger

一个可以在多个节点、不同地理位置或者多个机构组成的网络中分享的数据记录。

[来源：GM/T0111—2021，3.4]

智能合约smartcontract

一套以数字形式定义的约定。

[来源：GM/T0111—2021，3.3]

节点node

构建数据结构的基本组件。

交易transaction

数字资产的一次转账或者对智能合约的一次调用。

[来源：GM/T0111—2021，3.6]

哈希值hashvalue

将任意长度的二进制串映射为固定长度的二进制串的函数输出的比特串。

时间戳timestamp

以公共时间为参考的时间点。

4缩略语

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

gRPCs：Google发起的开源远程过程调用安全协议(googleRemoteProcedureCallsecurity

protocol）

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

1

JT/TXXXXX—XXXX

JSON：脚本语言对象符号，一种轻量级的数据交换格式（JavaScriptObjectNotation）

REST：表征状态转移（RepresentationalStateTransfer）

SCAC：标准承运人数字代码（StandardCarrierAlphaCode）

URI：通用资源标识符（UniformResourceIdentifier）

5平台要求

一般要求

5.1.1基于区块链的港航集装箱信息交换平台（以下简称“平台”）技术架构应符合YD/T3747的要

求。

5.1.2平台的安全等级应符合GB/T34990中的增强级等级。

5.1.3网络安全等级保护应符合JT/T1417中的第三级安全要求。

5.1.4承运人、货主、货代、船代、港口企业等业务参与方是数据交互方，应通过平台完成集装箱运

输信息的交换。

平台框架

平台框架见图1。

其他业务系统

集基

业务应用层信息创建信息更新信息推送信息查询信息验证

装于

箱

平台服务层身份管理运维监测交易管理节点管理区

信

块

息

分布式账本智能合约链

交

节点节点节点

平台基础层的

密码算法隐私保护共识机制换

节点平港

台航

图1平台框架

业务应用层

5.3.1信息创建

信息创建方创建需要上链的集装箱信息并发送到平台，平台应返回上链事务信息数据。

5.3.2信息更新

信息更新方应根据业务应用需要，更新之前已经创建过的集装箱信息。针对同样的信息，应以新的

版本进行上链并发送到平台，平台应返回上链事务信息数据。

5.3.3信息推送

消息上链成功之后，平台应将消息推送给该消息角色清单中的参与方。

5.3.4信息查询

信息查询方请求查询链上集装箱信息，平台应向信息查询方返回所查询信息的明细。

5.3.5信息验证

2

JT/TXXXXX—XXXX

信息验证方发送集装箱信息验证请求，平台校验数据后应返回验证结果。信息验证方应通过链上信

息与链下信息的对比来验证链下信息是否有篡改。

平台服务层

5.4.1身份管理

平台应支持业务参与方注册，注册时业务参与方应提供统一社会信用代码等信息完成身份认

证。

平台应对数据交互方定期进行身份验证。

5.4.2运维监测

平台应能对基础硬件、基础软件、性能、异常事务等进行监控。

业务参与方的任何操作，包括时间、数据变更内容、操作者等信息，都应在平台留存记录并

可进行相关统计。

5.4.3交易管理

交易管理应包括单证编码的生成与发放管理、单证编码对应的业务参与方地址列表的管理、消息的

发送与接收管理、消息异常处理管理、交易的异常处理管理、日志管理等功能。

5.4.4节点管理

平台应支持节点的增加和删除，新节点应通过签名证书相互授权准入后才能加到业务相关的

通道中。

各节点应在部署上物理隔离，宜通过gRPCs进行通信。

业务相关节点之间应搭建通道，每个通道应有专属分布式账本，且仅对通道内节点开放。

平台应对节点管理操作进行权限控制和身份验证，记录所有节点管理的操作历史，做到可审

计、可追溯。

平台基础层

5.5.1分布式账本

平台应为港航集装箱数据交互方建立分布式账本，存储信息的上链记录、授权记录、使用记

录、查询记录、状态变更等信息。

分布式账本以块链结构实现数据的分布式存储，每个节点都应有独立的、完整的数据存储区

域，并设置隐私保护措施，仅对利益相关方选择可见，并使用非代币形式的记账以及验证交易信息。

平台应具备分布式账本维护、分布式账本数据有效性检验、分布式账本数据追溯、分布式账

本同步等功能。

5.5.2智能合约

智能合约应包含相关数据交互方的数据交换规则和交换流程，这些规则和流程以代码的形式

部署在区块链节点中，当满足指定日期或者发生指定行为的条件时，计算机系统应自动执行相关合约。

平台应具备智能合约审核、发布、更新、日志审计、版本管理等功能，智能合约的发布应引

入相关方联合审核机制。

5.5.3密码算法

平台应具备对集装箱上链信息加密的能力。

密码算法可包括分组密码算法、流密码算法、非对称密码算法、密钥交换算法、密码杂凑算

法和标识密码算法等国家商用密码算法。

5.5.4隐私保护

平台应基于国家商用密码算法采取加密传输、认证和数据签名校验等安全机制。

3

JT/TXXXXX—XXXX

平台在进行信息采集、处理及发布过程中，应采取信息安全管理措施和技术手段，并应对隐

私数据进行数据加密存储。

平台应制定完备的隐私保护审计方案，方案应满足下列要求：

——审计内容包括隐私保护策略和隐私保护技术手段；

——审查形式包括但不限于日常监控、定期审计、不定期审计；

——审查对象包括但不限于操作记录等支持性文档；

——确认执行过程中遵循并实现既定的策略和技术手段。

5.5.5共识机制

平台的共识机制应由共识算法和共识协议等组成，应根据交易顺序写到分布式账本上，并满足在不

同场景中的一致性需求。

6接口要求

一般要求

6.1.1接口方式与协议规范

平台提供的接口服务应采用以系统资源为中心，基于REST的网络服务设计方式。基于REST的网络服

务应遵循RFC2616定义的协议方式，并应满足下列要求：

——显式地使用HTTP方法，应充分利用HTTP提供的请求信息、请求方法、响应信息来识别请求

的服务以及返回的错误；

——无状态的设计，不保留请求的状态，同时连接应为短连接；

——公开目录结构式的URI；

——传输JSON格式的请求体。

6.1.2接口响应常用状态码

接口响应状态码应使用RFC2616规范定义的HTTP状态码，常用的接口响应状态码及其说明应符合

表1的规定。

表1接口响应常用状态码及其说明

常用状态码说明

200服务调用成功

400请求格式错误

401未授权访问

403服务器拒绝访问

404指定的资源未找到

429请求数超出限额

500服务器内部错误

504响应超时

注：业务产生的错误或异常，其错误描述和错误号在HTTP响应体中返回。

6.1.3传输协议

平台应采用HTTP传输协议，建立以安全为目标的HTTP通道，在HTTP的基础上通过传输加密和身份认

证保证传输过程的安全性。

6.1.4数据格式

平台服务宜采用JSON作为数据交换的格式。

6.1.5交互方式

平台应支持的HTTP交互方式包括：创建信息（POST）、更新信息（PUT）和获得信息（GET）

三种方式，各接口类型的对应交互方式的应符合6.1.6的规定。

4

JT/TXXXXX—XXXX

接口应采取授权准入的规则，只有授权的IP方能进行访问。

6.1.6接口类型

平台接口类型和交互方式应符合表2的要求。

表2类型与交互方式

接口类型交互方式URI发送方接收方

港航集装箱信息交换

信息创建POST/api/[assetType]信息创建方

平台

港航集装箱信息交换

信息更新PUT/api/[assetType]信息更新方

平台

港航集装箱信息交换

信息推送POST/api/push信息接收方

平台

/api/[assetType]/港航集装箱信息交换

信息查询GET信息查询方

[assetId]/version/[assetVersion]平台

港航集装箱信息交换

信息验证POST/api/verify信息验证方

平台

6.1.7数据属性

数据属性包括：层次、中文名称、英文名称、类型、是否必填、说明，其中：

——层次：字段所属的层次关系；

——中文名称：字段的中文名称；

——英文名称：字段的英文名称；

——说明及要求：字段的内容和表达的含义；

——类型：数据元的特征和基本要素，包括字符型（string）、对象型（object）、数组型

(array)；

——是否必填：该数据元是否必填，必填为M、非必填为C；

——说明：字段的内容和表达的含义。

信息创建接口

6.2.1接口说明

创建需要上链的信息。

6.2.2请求内容

信息创建接口的请求参数数据格式和要求应符合表3的规定。

表3信息创建请求头信息数据格式要求

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

信息创建方区块链组织代码，在区块

1区块链组织代码orgIDstringM链注册后，由区块链创建的唯一的组

织代码

2角色rolestringM信息创建方

区块链业务应用场景编区块链针对业务应用场景分配的编

3applicationIDstringM

号号

6.2.3上链内容

上链内容的数据格式和要求应符合表4的规定。

5

JT/TXXXXX—XXXX

表4信息创建上链内容数据格式要求

序号层次中文名称英文名称类型是否必填说明

信息创建方指定允许查询的参与方

10角色清单roleListobjectM

清单

roleListLocator采集信息，供区块链生成唯一上链信

1.11角色清单定位键objectM

Key息识别码

1.1.12承运人代码carrierScacstringM承运人scac代码

1.1.22提单号blNumberstringC提单号

1.1.32提货单号doNumberstringC提货单号

1.1.42集装箱号cntrNumberstringC集装箱号

1.1.52角色清单类型roleListTypestringM角色清单类型

1.21角色清单类型roleListTypestringM角色清单类型

1.31角色清单内容roleListContentobjectM参与方清单内容

1.3.12承运人组织代码carrierOrgIDstringC承运人在区块链的组织代码

最终卸港码头组lastPodTerminal

1.3.22stringC最终卸港码头在区块链的组织代码

织代码OperatorOrgID

1.3.32托运人组织代码shipperOrgIDstringC托运人在区块链的组织代码

货运代理组织代

1.3.42forwardeOrgIDstringC货运代理在区块链的组织代码

码

1.3.52收货人组织代码consigneeOrgIDstringC收货人在区块链的组织代码

船公司代理组织

1.3.62shipAgentOrgIDstringC船公司代理在区块链的组织代码

代码

20信息明细assetContentobjectM所需创建的信息明细

6.2.4返回内容

返回内容的数据格式和要求应符合表5的规定。

表5信息创建返回内容数据格式要求

序号层次中文名称英文名称类型是否必填说明

10代码codestringM由区块链返回的回执代码

20错误简要描述errorstringC1000000：表示成功；

30回执明细dataobjectM其余代码：表示出错

由区块链返回。如果有错误，则会返

3.11事务识别号txnIDstringC

回错误简要描述

由区块链返回的回执明细。如果有报

3.21信息识别码assetIDstringC

错，则会返回错误明细

如果成功，由区块链返回的唯一事务

3.31错误列表detailsarrayC

识别号

如果成功，由区块链返回的唯一上链

3.3.12错误明细messagestringC

信息识别码

3.3.22错误类型typestringC如果错误，由区块链返回的错误列表

信息更新接口

6.3.1接口说明

根据业务应用需要，依据信息识别码和信息版本号，更新之前已经创建过的信息，以新版本进行上

链。如需撤回之前已经创建过的信息，可在上链信息的assestcontent中标记“撤回”。

6.3.2请求内容

信息更新接口的请求头信息数据格式和要求应符合表6的规定。

6

JT/TXXXXX—XXXX

表6信息更新请求头信息数据格式要求

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

信息更新方区块链组织代码，在区块

1区块链组织代码orgIDstringM链注册后，由区块链创建的唯一的组

织代码

2角色rolestringM信息更新方

区块链业务应用场景编区块链针对业务应用场景分配的编

3applicationIDstringM

号号

4信息识别码assetIDstringM唯一信息识别码

5信息版本assetVersionstringM当前区块链上该信息的版本

6.3.3上链内容

信息更新上链内容数据格式要求应符合表7的规定。

表7信息更新上链内容数据格式要求

序号层次中文名称英文名称类型是否必填说明

信息更新方指定允许查询的参与方

10角色清单roleListobjectM

清单

roleListLocator采集信息，供区块链生成唯一上链信

1.11角色清单定位键objectM

Key息识别码

1.1.12承运人代码carrierScacstringM承运人scac代码

1.1.22提单号blNumberstringC提单号

1.1.32提货单号doNumberstringC提货单号

1.1.42集装箱号cntrNumberstringC集装箱号

1.1.52角色清单类型roleListTypestringM角色清单类型。如：SEAWAY_BILL

1.21角色清单类型roleListTypestringM角色清单类型。如：SEAWAY_BILL

1.31角色清单内容roleListContentobjectM参与方清单内容

1.3.12承运人组织代码carrierOrgIDstringC承运人在区块链的组织代码

最终卸港码头组lastPodTerminal

1.3.22stringC最终卸港码头在区块链的组织代码

织代码OperatorOrgID

1.3.32托运人组织代码shipperOrgIDstringC托运人在区块链的组织代码

货运代理组织代

1.3.42forwardeOrgIDstringC货运代理在区块链的组织代码

码

1.3.52收货人组织代码consigneeOrgIDstringC收货人在区块链的组织代码

船公司代理组织

1.3.62shipAgentOrgIDstringC船公司代理在区块链的组织代码

代码

1.41信息明细assetContentobjectM所需更新的信息明细

6.3.4返回内容

返回内容应符合6.2.4的规定。

信息推送接口

6.4.1接口说明

消息上链成功之后，平台将消息推送给该消息角色清单中的参与方。

6.4.2请求内容

信息推送请求头信息数据格式要求应符合表8的规定。

7

JT/TXXXXX—XXXX

表8信息推送请求头信息数据格式要求

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

参与方在区块链注册时，提供给区块

1授权码authorizationstringM链，用来接收信息推送接口的授权

码，是数据交互安全的手段之一

6.4.3上链内容

信息推送上链内容数据格式要求应符合表9的规定。

表9信息推送上链内容数据格式要求

序号层次中文名称英文名称类型是否必填说明

10信息识别码assetIDstringM信息推送所对应的唯一信息识别码

20信息版本assetVersionstringM由区块链返回的当前信息版本

返回由区块链预先定义的信息类型，

每种信息均有定义的专属信息类型。

30信息类型assetTypestringM

区块链用此信息类型定义，控制信息

中具体数据项的访问权限

由区块链产生的数字指纹，用来追踪

40数字指纹locatorKeystringM

相关参与方

由区块链返回的上链事务识别号和

50上链事务onchainTxnsarrayM

时间戳

由区块链返回的区块链通道信息，一

5.11区块链通道channelstringM

个通道对应一本区块链分布式账本

5.21事务识别号txnIDstringM由区块链返回的唯一事务识别号

5.31参与方participantsarrayM由区块链返回的参与方清单

由区块链返回的上链时的时间戳，采

5.41时间戳timestampstringM

用格林威治时间

信息在平台创建的时间戳，采用格林

60创建的时间戳createAtstringM

威治时间

信息在平台更新的时间戳，采用格林

70更新的时间戳updateAtstringM

威治时间

80加密策略encryptStrategystringM由区块链返回的加密策略

信息提供方的事由区块链返回的信息提供方的数字

90payloadSignstringM

务数字签名签名

链上信息的哈希

100assetHashstringM由区块链返回的链上信息哈希值

值

110信息明细assetContentobjectM由区块链返回的信息明细

6.4.4返回内容

信息推送接口的状态应由HTTP状态码进行识别，HTTP状态码200为成功，其它状态码为失败。

信息查询接口

6.5.1接口说明

参与方可通过该接口查询链上信息。

6.5.2请求内容

信息查询请求内容数据格式要求应符合表10的规定。

8

JT/TXXXXX—XXXX

表10信息查询请求内容数据格式要求

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

信息查询方区块链组织代码，在区块

1区块链组织代码orgIDstringM链注册后，由区块链创建的唯一的组

织代码

2角色rolestringM信息查询方

区块链业务应用场景编区块链针对业务应用场景分配的编

3applicationIDstringM

号号

需要查询信息所对应的唯一信息识

4信息识别码assetIDstringM

别码

5信息版本assetVersionstringC当前区块链上该信息的版本

6.5.3返回内容

信息查询返回内容数据格式要求应符合表11的规定。

表11信息查询返回内容数据格式要求

序号层次中文名称英文名称类型是否必填说明

10代码codestringM由区块链返回的回执代码

20数据dataarrayM由区块链返回的回执明细

需要查询信息所对应的唯一信息识

2.11信息识别码assetIDstringM

别码

由区块链返回的链上信息的当前版

2.21信息版本assetVersionstringM

本

返回由区块链预先定义的信息类型，

每种信息均有定义的专属信息类型。

2.31信息类型assetTypestringM

区块链用此信息类型定义，控制信息

中具体数据项的访问权限

由区块链产生的数字指纹，用来追踪

2.41数字指纹locatorKeystringM

相关参与方

2.51数据报文散列值assetHashstringM由区块链返回的资产散列值

提供方的事务数由区块链返回的提供方的交易数字

2.61payloadSignstringM

字签名签名

2.71加密策略encryptStrategystringM由区块链返回的加密策略

信息在平台创建的时间戳，采用格林

2.81创建的时间戳createAtstringM

威治时间

信息在平台更新的时间戳，采用格林

2.91更新的时间戳updateAtstringM

威治时间

由区块链返回的上链事务识别号和

2.101上链事务onchainTxnsarrayM

时间戳

2.10.12事务识别号txnIDstringM由区块链返回的唯一事务识别号

由区块链返回的区块链通道信息，一

2.10.22区块链通道channelstringM

个通道对应一本区块链分布式账本

2.10.32参与方participantsarrayM由区块链返回的参与方清单

由区块链返回的上链时的时间戳，

2.10.42时间戳timestampstringM

采用格林威治时间

2.111信息明细assetContentobjectM由区块链返回的所查询信息的明细

信息验证接口

6.6.1接口说明

各参与方通过链上信息与链下信息的对比，来验证链下信息是否有篡改。

6.6.2请求内容

9

JT/TXXXXX—XXXX

信息验证请求内容数据格式要求应符合表12的规定。

表12信息验证请求内容数据格式要求

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

返回由区块链预先定义的信息类型，

每种信息均有定义的专属信息类型。

1信息类型assetTypestringM

区块链用此信息类型定义，控制信息

中具体数据项的访问权限

在区块链注册后，由区块链创建的唯

2验证方区块链组织代码orgIDstringM

一的组织代码

信息验证方在区块链的角色（信息创

3角色rolestringM

建方、信息更新方或信息查询方）

区块链业务应用场景编

4applicationIDstringM针对业务应用场景分配的编号

号

需要查询信息所对应的唯一信息识

5信息识别码assetIDstringM

别码

6信息版本assetVersionstringM当前区块链上该信息的版本

6.6.3校验内容

信息验证校验内容数据格式要求应符合表13的规定。

表13信息验证校验内容数据格式要求

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

在区块链注册后，由区块链创建的唯

1验证方组织代码originatorOrgIDstringM

一的组织代码

2