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

PAGEPAGE11PAGEPAGE10基于区块链的港航集装箱信息交换平台及接口技术要求范围本文件规定了基于区块链的港航集装箱信息交换平台要求和接口要求。本文件适用于基于区块链的港航集装箱信息交换平台及接口的设计和应用。（GB/T34990信息安全技术信息系统安全管理平台技术要求和测评评价方法JT/T1417交通运输行业网络安全等级保护基本要求YD/T3747区块链技术架构安全要求RFC2616超文本传输协议HTTP1.1（HypertextTransferProtocol--HTTP/1.1）下列术语和定义适用于本文件。分布账本 distributedledgerGM/T0111—2021，3.4]智能约 smartcontract一套以数字形式定义的约定。[来源：GM/T0111—2021，3.3]节点 node构建数据结构的基本组件。交易 transactionGM/T0111—2021，3.6]哈希值 hashvalue将任意长度的二进制串映射为固定长度的二进制串的函数输出的比特串。时间戳 timestamp以公共时间为参考的时间点。缩略语下列缩略语适用于本文件。gRPCs：Google发起的开源远程过程调用安全协议(googleRemoteProcedureCallsecurityprotocol）HTTP：超文本传输协议（HyperTextTransferProtocol）JSON：脚本语言对象符号，一种轻量级的数据交换格式（JavaScriptObjectNotation）REST：表征状态转移（RepresentationalStateTransfer）SCAC：标准承运人数字代码（StandardCarrierAlphaCode）URI：通用资源标识符（UniformResourceIdentifier））YD/T3747求。GB/T34990JT/T1417其他业务系统平台框架见图1。其他业务系统集基业务应用层信息创建 信息更新 信息推送 信息查询信息验证平台服务层平台基础层身份管理 分布式账本 智能合约密码算法 隐私保护 共识机节点交易管理 节点节点 节点装于箱信块息链交换平台航图1 平台架信息创建方创建需要上链的集装箱信息并发送到平台，平台应返回上链事务信息数据。消息上链成功之后，平台应将消息推送给该消息角色清单中的参与方。信息查询方请求查询链上集装箱信息，平台应向信息查询方返回所查询信息的明细。gRPCs平台基础层——审计内容包括隐私保护策略和隐私保护技术手段；——审查形式包括但不限于日常监控、定期审计、不定期审计；——审查对象包括但不限于操作记录等支持性文档；——确认执行过程中遵循并实现既定的策略和技术手段。RESTRESTRFC2616HTTPHTTP——无状态的设计，不保留请求的状态，同时连接应为短连接；——公开目录结构式的URI；——传输JSON格式的请求体。接口响应状态码应使用RFC2616规范定义的HTTP状态码，常用的接口响应状态码及其说明应符合表1表1 接口应用态及说明常用状态码说明200服务调用成功400请求格式错误401未授权访问403服务器拒绝访问404指定的资源未找到429请求数超出限额500服务器内部错误504响应超时注：业务产生的错误或异常，其错误描述和错误号在HTTP响应体中返回。HTTPHTTPHTTP平台服务宜采用JSON作为数据交换的格式。HTTP（POST）（PUT）（GET）6.1.6IP平台接口类型和交互方式应符合表2的要求。表2 类型交方式接口类型交互方式URI发送方接收方信息创建POST/api/[assetType]信息创建方港航集装箱信息交换平台信息更新PUT/api/[assetType]信息更新方港航集装箱信息交换平台信息推送POST/api/push港航集装箱信息交换平台信息接收方信息查询GET/api/[assetType]/[assetId]/version/[assetVersion]信息查询方港航集装箱信息交换平台信息验证POST/api/verify信息验证方港航集装箱信息交换平台数据属性包括：层次、中文名称、英文名称、类型、是否必填、说明，其中：——说明及要求：字段的内容和表达的含义；（string）（object）——是否必填：该数据元是否必填，必填为M、非必填为C；——说明：字段的内容和表达的含义。创建需要上链的信息。信息创建接口的请求参数数据格式和要求应符合表3的规定。表3 信息建求信数格式求序号中文名称英文名称类型是否必填说明1区块链组织代码orgIDstringM织代码2角色rolestringM信息创建方3区块链业务应用场景编号applicationIDstringM区块链针对业务应用场景分配的编号上链内容的数据格式和要求应符合表4的规定。表4 信息建链容据式要求序号层次中文名称英文名称类型是否必填说明10角色清单roleListobjectM信息创建方指定允许查询的参与方清单1.11角色清单定位键roleListLocatorKeyobjectM息识别码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承运人在区块链的组织代码1.3.22最终卸港码头组织代码lastPodTerminalOperatorOrgIDstringC最终卸港码头在区块链的组织代码1.3.32托运人组织代码shipperOrgIDstringC托运人在区块链的组织代码1.3.42货运代理组织代码forwardeOrgIDstringC货运代理在区块链的组织代码1.3.52收货人组织代码consigneeOrgIDstringC收货人在区块链的组织代码1.3.62船公司代理组织代码shipAgentOrgIDstringC船公司代理在区块链的组织代码20信息明细assetContentobjectM所需创建的信息明细返回内容的数据格式和要求应符合表5的规定。表5 信息建回容据式要求序号层次中文名称英文名称类型是否必填说明10代码codestringM由区块链返回的回执代码20错误简要描述errorstringC1000000：表示成功；30回执明细dataobjectM其余代码：表示出错3.11事务识别号txnIDstringC回错误简要描述3.21信息识别码assetIDstringC错，则会返回错误明细3.31错误列表detailsarrayC识别号3.3.12错误明细messagestringC信息识别码3.3.22错误类型typestringCassestcontent信息更新接口的请求头信息数据格式和要求应符合表6的规定。表6 信息新求信数格式求序号中文名称英文名称类型是否必填说明1区块链组织代码orgIDstringM织代码2角色rolestringM信息更新方3区块链业务应用场景编号applicationIDstringM区块链针对业务应用场景分配的编号4信息识别码assetIDstringM唯一信息识别码5信息版本assetVersionstringM当前区块链上该信息的版本信息更新上链内容数据格式要求应符合表7的规定。表7 信息新链容据式要求序号层次中文名称英文名称类型是否必填说明10角色清单roleListobjectM信息更新方指定允许查询的参与方清单1.11角色清单定位键roleListLocatorKeyobjectM息识别码1.1.12承运人代码carrierScacstringM承运人scac代码1.1.22提单号blNumberstringC提单号1.1.32提货单号doNumberstringC提货单号1.1.42集装箱号cntrNumberstringC集装箱号1.1.52角色清单类型roleListTypestringM角色清单类型。如：SEAWAY_BILL1.21角色清单类型roleListTypestringM角色清单类型。如：SEAWAY_BILL1.31角色清单内容roleListContentobjectM参与方清单内容1.3.12承运人组织代码carrierOrgIDstringC承运人在区块链的组织代码1.3.22最终卸港码头组织代码lastPodTerminalOperatorOrgIDstringC最终卸港码头在区块链的组织代码1.3.32托运人组织代码shipperOrgIDstringC托运人在区块链的组织代码1.3.42货运代理组织代码forwardeOrgIDstringC货运代理在区块链的组织代码1.3.52收货人组织代码consigneeOrgIDstringC收货人在区块链的组织代码1.3.62船公司代理组织代码shipAgentOrgIDstringC船公司代理在区块链的组织代码1.41信息明细assetContentobjectM所需更新的信息明细返回内容应符合6.2.4的规定。消息上链成功之后，平台将消息推送给该消息角色清单中的参与方。信息推送请求头信息数据格式要求应符合表8的规定。表8 信息送求信数格式求序号中文名称英文名称类型是否必填说明1授权码authorizationstringM链，用来接收信息推送接口的授权码，是数据交互安全的手段之一信息推送上链内容数据格式要求应符合表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由区块链返回的加密策略90信息提供方的事务数字签名payloadSignstringM由区块链返回的信息提供方的数字签名100链上信息的哈希值assetHashstringM由区块链返回的链上信息哈希值110信息明细assetContentobjectM由区块链返回的信息明细信息推送接口的状态应由HTTP状态码进行识别，HTTP状态码200为成功，其它状态码为失败。参与方可通过该接口查询链上信息。信息查询请求内容数据格式要求应符合表10的规定。表10 信息询求容据式要求序号中文名称英文名称类型是否必填说明1区块链组织代码orgIDstringM织代码2角色rolestringM信息查询方3区块链业务应用场景编号applicationIDstringM区块链针对业务应用场景分配的编号4信息识别码assetIDstringM需要查询信息所对应的唯一信息识别码5信息版本assetVersionstringC当前区块链上该信息的版本信息查询返回内容数据格式要求应符合表11的规定。表11 信息询回容据式要求序号层次中文名称英文名称类型是否必填说明10代码codestringM由区块链返回的回执代码20数据dataarrayM由区块链返回的回执明细2.11信息识别码assetIDstringM需要查询信息所对应的唯一信息识别码2.21信息版本assetVersionstringM由区块链返回的链上信息的当前版本2.31信息类型assetTypestringM返回由区块链预先定义的信息类型，每种信息均有定义的专属信息类型。区块链用此信息类型定义，控制信息中具体数据项的访问权限2.41数字指纹locatorKeystringM相关参与方2.51数据报文散列值assetHashstringM由区块链返回的资产散列值2.61提供方的事务数字签名payloadSignstringM由区块链返回的提供方的交易数字签名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由区块链返回的所查询信息的明细各参与方通过链上信息与链下信息的对比，来验证链下信息是否有篡改。信息验证请求内容数据格式要求应符合表12的规定。表12 信息证求容据式要求序号中文名称英文名称类型是否必填说明1信息类型assetTypestringM中具体数据项的访问权限2验证方区块链组织代码orgIDstringM一的组织代码3角色rolestringM（建方、信息更新方或信息查询方）4区块链业务应用场景编号applicationIDstringM针对业务应用场景分配的编号5信息识别码assetIDstringM需要查询信息所对应的唯一信息识别码6信息版本assetVersionstringM当前区块链上该信息的版本信息验证校验内容数据格式要求应符合表13的规定。表13 信息证验容据式要求序号中文名称英文名称类型是否必填说明1验证方组织代码originatorOrgIDstringM一的组织代码2需验证的内容assetContentobjectM信息验证方需验证的信息内容3需验证的文件filestringC信息验证方需验证的文件信息校验返回内容数据格式要求应符合表14的规定。表14 信息证回容据式要求序号层次中文名称英文名称类型是否必填说明10代码codestringM由区块链返回的回执代码20数据dataobjectM由区块链返回的回执明细2.11验证结果verificationResultstringM失败2.21原因reasonstringC由区块链返回的失败原因［请求参数以HTTPHeader的方式提供：POST/api/seawayBill

附录A（资料性）信息交互示例orgID:6aba7011-a947-4d61-ae59-700791870c99role:CarrierapplicationID:b6422a60-caeb-41f7-81be-847af760c635［［请求示例］请求参数以HTTPURL参数和HTTPHeader的方式提供，assetID及assetVersion以URL参数的方式提供，其它参数以HTTPHeader的方式提供：PUT/api/seawayBill/1888512039056320807/version/1orgID:6aba7011-a947-4d61-ae59-700791870c99role:Carr