2023电力区块链绿电交易第4部分：接口规范

4II目 次前言 II范围 1规性用件 1术和义 1缩语 2总要求 2据输 2口用程 2口计求 4口全求 4接规约 4口类 4据装本求 4块平接数的接规约 4接请求 4接返回 5块平提数的接规约 5接请求 5接返回 6接信内容 6据互求 6块平接信息 7市主信息 7合信息 7合映关系 8结信息 9绿划信息 9块平提信息 9区链台成钥 10链市主信息 10链合信息 10链结信息 11链绿划信息 11绿电消证询链接 12IIII——1——2——3——411电力区块链绿电交易第4部分：接口要求范围本文件规定了绿色电力交易平台与区块链平台之间进行绿电交易信息交换的数据接口的总体要求、接口规约及接口信息内容。（GB/T32905—2016 SM3GB/T35276—2017 SM2DL/TXXXX.1—XXXX电力区块链绿电交易第1部分：通用要求GM/T0067—2019 DL/TXXXX.1—XXXX界定的以及下列术语和定义适用于本文件。3.1绿电交易信息greenpowertransactioninformation开展绿电交易业务涉及的市场主体信息、合同信息、结算信息。3.2绿电交易信息网关服务gatewayservice3.3SM2法 SM2algorithm一种椭圆曲线公钥密码算法，其密钥长度为256比特。[来源：GM/T0067—2019，3.8]3.4SM3法 SM3algorithm一种密码杂凑算法，其输出为256比特。[来源：GM/T0067—2019，3.9]3.5SHA256算法SHA256algorithm一种安全哈希算法，其摘要长度为256比特。22缩略语下列缩略语适用于本文件。API：应用程序接口（ApplicationProgrammingInterface）AppKey：应用程序接口公钥，API接口验证序号，是用于验证API接入的合法性（ApplicationprogramminginterfaceKey）AppKey（ApplicationprogramminginterfaceSecret）HTTPS（HyperTransferProtocoloverSecureSocketLayer）JSON：一种轻量级的数据交换格式（JavaScriptObjectNotation）Unicode（8-bitUnicodeTransformationFormat）XML（eXtensibleMarkupLanguage）1。图1绿电交易信息数据传输其中：绿电交易信息交互的接口调用如图2所示，具体调用过程为：33pdf注1：因网关服务部署在区块链平台上，非独立信息系统，故图中用虚线表示。注2：绿证划转和绿色电力消费证明的生成均为绿电交易结算后发生的。注3且有序号。注4：市场主体可通过绿色电力交易平台随时按需查询绿色电力消费认证数据，不涉及到流程顺序，故图中用虚线表示，且无序号。图2接口调用流程44绿电交易信息交互的接口设计要求如下：HTTPSpost绿电交易信息交互的接口安全要求如下：AppKeyAppSecretSM2AppKeyAppSecretSM3SM3算法要求遵循GB/T32905—2016；SM2SM2算法要求遵循GB/T35276—2017。数据封装基本要求如下：报文应采用XML格式或JSONUTF-8yyyy-MM-ddHH24:mm:ss”。（MWh），/（CNY/MWh）/（CNY/kWh）（CNY）SM2。55表1接口请求参数参数名参数类型分类参数说明AppKeyString公共参数用户名，由区块链平台线下分配给绿色电力交易平台的鉴权信息，用于赋予接口调用权限hashAlgString公共参数用于计算参数摘要值的算法，可用SM3或SHA256signString公共参数参数摘要值，根据AppKey和AppSecret，采用SM3加密计算得出InterfacenameString业务参数数据接口ID，见表5“数据接口ID”列DataObject业务参数传输的具体业务数据，见表7~表13SM22。表2接口返回参数参数名参数类型分类参数说明codeInt公共参数接口调用返回编码，200为请求成功，非200为请求失败msgString公共参数调用提示或错误信息dataObject业务参数接口返回信息，一般各接口对应返回信息如下：市场主体信息存证接口：bcHash_member合同信息存证接口：bcHash_contract合同关联映射关系存证接口：bcHash_contractlist结算信息存证接口：bcHash_settlement绿证划转信息存证接口：bcHash_green_certificateSM2。表3接口请求参数参数名参数类型分类参数说明AppKeyString公共参数用户名，由区块链平台线下分配给绿色电力交易平台的鉴权信息，用于赋予接口调用权限hashAlgString公共参数用于计算参数摘要值的算法，SM3或SHA256signString公共参数参数摘要值，根据AppKey和AppSecret，采用SM3加密计算得出TaskIDString业务参数传输任务对应的数据接口ID，见表6“数据接口ID”列dataObject业务参数接口调用信息，一般各接口对应的调用信息如下：市场主体信息溯源查询接口：市场主体ID合同信息溯源查询接口：合同ID结算信息溯源查询接口：结算ID绿证划转信息溯源查询接口：绿证编号ID绿色电力消费证明获取接口：合同ID或结算ID66SM2。表4接口返回参数参数名参数类型分类参数说明codeInt公共参数接口调用返回编码，200为请求成功，非200为请求失败hashAlgString公共参数用于计算参数摘要值的算法，SM3或SHA256signString公共参数参数摘要值，根据AppKey和AppSecret，采用SM3加密计算得出msgString公共参数调用提示或错误信息dataObject业务参数接口返回信息，传输的具体业务数据，见表14-表21区块链平台接收数据交互要求见表5。表5 区链台收据交要求对应章节交互信息数据接口名称数据接口ID传输频率备注7.2.1市场主体信息市场主体信息存证接口MarketEntityInfo_onchain按照业务周期表77.2.2合同信息合同信息存证接口ContractInfo_onchain按照业务周期表8~表107.2.3合同映射关系合同关联映射关系存证接口Contract_mapping_relationship_onchain按照业务周期表117.2.4结算信息结算信息存证接口SettlementInfo_onchain按照业务周期表127.2.5绿证划转信息绿证划转信息存证接口Green_certificate_onchain按照业务周期表13区块链平台提供数据交互要求见表6。表6 区链台供据交要求对应章节交互信息数据接口名称数据接口ID传输频率备注7.3.1区块链平台生成的SM2公钥SM2公钥查询接口Blockchain_pubKey_query—表147.3.2链上市场主体信息市场主体信息溯源查询接口MarketSubjectInfo_trace按业务需求表157.3.3链上合同信息合同信息溯源查询接口ContractInfo_trace按业务需求表16~表187.3.4链上结算信息结算信息溯源查询接口SettlementInfo_trace按业务需求表197.3.5链上绿证划转信息绿证划转信息溯源查询接口Green_certificate_trace按业务需求表207.3.6绿色电力消费证明查询链接绿色电力消费证明获取接口GreenPowerConsumptionCer_query按业务需求表2177市场主体信息上链存证接口为结构化数据接口，接口数据信息详见表7。表7 市主信息序号信息项英文名称数据类型备注说明1市场主体IDmembersIdString市场主体对应的唯一标识2市场主体名称membersNameString—3企业统一社会信用代码USCIString—4企业法人姓名businesscorporationNameString—5地理区域IDprovinceIdString地理区域对应的唯一标识6地理区域名称provinceNameString—7联系人姓名LinkmanNameString—8联系人电话LinkmanPhoneString—合同信息上链存证接口为结构化数据接口，接口数据信息详见表8~表10。表8 合信息序号信息项英文名称数据类型备注说明1合同IDcontractIdString合同信息对应的唯一标识2合同名称contractNameString—3绿电合同分类contractTypeString0（用户—发电厂）1（售电公司—代理机构）2（代理机构—发电厂）3（用户—售电公司）4（售电公司—发电厂）5（用户（非售电公司）—代理机构）4合同电量contractQtyBigDecimal—5电量类型energyTypeString—6合同开始时间contractStartDateDate—7合同结束时间contractEndDateDate—8购电方主体IDpurchaserString购电方的市场主体对应的唯一标识9购电方主体类型purchaserTypeString—10购电方主体名称purchaserNameString—11售电方主体IDsellerString售电方的市场主体对应的唯一标识12售电方主体类型sellerTypeString—13售电方主体名称sellerNameString—14交易序列IDtransactionIdString交易序列对应的唯一标识88表8(续)序号信息项英文名称数据类型备注说明15交易序列名称transactionNameString—16合同电价contractPriceBigDecimal—17售电方发电类型sellerPowerTypeString—18售电方省份IDsellerProvinceIdString售电方省份对应的唯一标识19售电方省份名称sellerProvinceNameString—20购电方省份IDpurchaserProvinceIdString购电方省份对应的唯一标识21购电方省份名称purchaserProvinceNameString—22合同分月信息energyInfosList具体见表1023输电方相关信息transferConfirmsList具体见表1124绿色权益电价greenRightsPriceDecimal—表9 合分信息序号信息项英文名称数据类型备注说明1合同IDcontractIdString合同信息对应的唯一标识2分月开始时间startDateDate—3分月结束时间endDateDate—4分月合同电量contractEnergyBigDecimal—5分月总电价PriceBigDecimal—6分月电能量电价energyPriceBigDecimal—7分月绿色权益电价greenRightsPriceDecimal—表10 电相信息序号信息项英文名称数据类型备注说明1合同IDcontractIdString合同信息对应的唯一标识2交易序列IDtradeseqIdString交易序列对应的唯一标识3输电方主体IDpowerGridIdString输电方的市场主体对应的唯一标识4输电方名称powerGridNameString—。99表11 同射系息序号信息项英文名称数据类型备注说明1售电公司和代理机构签订的合同IDbuyContractIdString售电公司和代理机构签订的合同信息对应的唯一标识2代理机构和发电厂签订的合同IDsellContractIdString代理机构和发电厂签订的合同信息对应的唯一标识3用户和售电公司签订的合同IDretailContractIdString用户和售电公司签订的合同信息对应的唯一标识4售电公司和发电厂签订的合同IDwholesaleContractIdString售电公司和发电厂签订的合同信息对应的唯一标识5用户（非售电公司）和代理机构签订的合同IDuserBuyContractIdString用户（非售电公司）和代理机构签订的合同信息对应的唯一标识结算信息上链存证接口为结构化数据接口，接口数据信息详见表12。表12结算信息序号信息项英文名称数据类型备注说明1结算IDsettlementIdString结算信息对应的唯一标识2月度mktMonthString—3结算开始时间Settle_startDateDate—4结算结束时间Settle_endDateDate—5合同IDcontractIdString合同信息对应的唯一标识6结算类型IDsettleTypeIdString—7时段periodInt0总时间段，1尖峰时段，2高峰时段，3非峰谷时段，4低谷时段8结算电量energyTotalBigDecimal—9结算电价priceTotalBigDecimal—10结算电费feeTotalBigDecimal—绿证划转信息上链存证接口为结构化数据接口，接口数据信息详见表13。表13绿证划转信息序号信息项英文名称数据类型备注说明1绿证编码IDGreen_certificate_NO.IdString水规院绿证编码对应的唯一标识2绿证数量Green_certificate_QtyBigDecimal—3可再生能源发电企业IDRenewenergy_generation_enterprisesIdString与划转绿证关联的发电企业对应的唯一标识4电力用户IDPoweruserIdString与划转绿证关联的电力用户对应的唯一标识1010区块链平台生成的SM2公钥查询接口为结构化数据接口，接口数据信息详见表14。表14 块平生的SM2钥息序号信息项英文名称数据类型备注说明1区块链平台生成的SM2公钥Blockchain_pubKeyObject—市场主体信息查询接口为结构化数据接口，接口数据信息详见表15。表15 上场体息序号信息项英文名称数据类型备注说明1市场主体IDmembersIdString市场主体对应的唯一标识2市场主体信息上链凭证编号bcHash_memberString—合同信息查询接口为结构化数据接口，接口数据信息详见表16~表18。表16 上同息序号信息项英文名称数据类型备注说明1合同IDcontractIdString合同信息对应的唯一标识2合同名称contractNameString—3合同电量contractQtyBigDecimal—4电量类型energyTypeString—5合同开始时间contractStartDateDate—6合同结束时间contractEndDateDate—7购电方主体IDpurchaseString购电方的市场主体对应的唯一标识8售电方主体IDsellerString售电方的市场主体对应的唯一标识9交易序列IDtransactionIdString交易序列对应的唯一标识10合同电价contractPriceBigDecimal—11售电方发电类型sellerPowerTypeString—12合同分月信息energyInfosList见表1613输电方相关信息transferConfirmsList见表1714合同上链凭证编号bcHash_contractString—15绿色权益电价greenRightsPriceDecimal—1111表17 同月息序号信息项英文名称数据类型备注说明1合同IDcontractIdString合同信息对应的唯一标识2分月开始时间startDateDate—3分月结束时间endDateDate—4分月合同电量contractEnergyBigDecimal—5分月总电价PriceBigDecimal—6分月电能量电价energyPriceBigDecimal—7分月绿色权益电价greenRightsPriceDecimal—表18 电相信息序号信息项英文名称数据类型备注说明1合同IDcontractIdString合同信息对应的唯一标识2交易序列IDtradeseqIdString交易序列对应的唯一标识3输电方主体IDpowerGridIdString输电方的市场主体对应的唯一标识4输电方名称powerGridNameString—结算信息查询接口为结构化数据接口，接口数据信息详见表19。表19 上算息序号信息项英文名称数据类型备注说明1结算IDsettlementIdString结算信息对应的唯一标识2月度mktMonthString—