2023電力區(qū)塊鏈綠電交易第4部分：接口規(guī)范

4II目 次前言 II范圍 1規(guī)性用件 1術和義 1縮語 2總要求 2據輸 2口用程 2口計求 4口全求 4接規(guī)約 4口類 4據裝本求 4塊平接數(shù)的接規(guī)約 4接請求 4接返回 5塊平提數(shù)的接規(guī)約 5接請求 5接返回 6接信內容 6據互求 6塊平接信息 7市主信息 7合信息 7合映關系 8結信息 9綠劃信息 9塊平提信息 9區(qū)鏈臺成鑰 10鏈市主信息 10鏈合信息 10鏈結信息 11鏈綠劃信息 11綠電消證詢鏈接 12IIII——1——2——3——411電力區(qū)塊鏈綠電交易第4部分：接口要求范圍本文件規(guī)定了綠色電力交易平臺與區(qū)塊鏈平臺之間進行綠電交易信息交換的數(shù)據接口的總體要求、接口規(guī)約及接口信息內容。（GB/T32905—2016 SM3GB/T35276—2017 SM2DL/TXXXX.1—XXXX電力區(qū)塊鏈綠電交易第1部分：通用要求GM/T0067—2019 DL/TXXXX.1—XXXX界定的以及下列術語和定義適用于本文件。3.1綠電交易信息greenpowertransactioninformation開展綠電交易業(yè)務涉及的市場主體信息、合同信息、結算信息。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：一種輕量級的數(shù)據交換格式（JavaScriptObjectNotation）Unicode（8-bitUnicodeTransformationFormat）XML（eXtensibleMarkupLanguage）1。圖1綠電交易信息數(shù)據傳輸其中：綠電交易信息交互的接口調用如圖2所示，具體調用過程為：33pdf注1：因網關服務部署在區(qū)塊鏈平臺上，非獨立信息系統(tǒng)，故圖中用虛線表示。注2：綠證劃轉和綠色電力消費證明的生成均為綠電交易結算后發(fā)生的。注3且有序號。注4：市場主體可通過綠色電力交易平臺隨時按需查詢綠色電力消費認證數(shù)據，不涉及到流程順序，故圖中用虛線表示，且無序號。圖2接口調用流程44綠電交易信息交互的接口設計要求如下：HTTPSpost綠電交易信息交互的接口安全要求如下：AppKeyAppSecretSM2AppKeyAppSecretSM3SM3算法要求遵循GB/T32905—2016；SM2SM2算法要求遵循GB/T35276—2017。數(shù)據封裝基本要求如下：報文應采用XML格式或JSONUTF-8yyyy-MM-ddHH24:mm:ss”。（MWh），/（CNY/MWh）/（CNY/kWh）（CNY）SM2。55表1接口請求參數(shù)參數(shù)名參數(shù)類型分類參數(shù)說明AppKeyString公共參數(shù)用戶名，由區(qū)塊鏈平臺線下分配給綠色電力交易平臺的鑒權信息，用于賦予接口調用權限hashAlgString公共參數(shù)用于計算參數(shù)摘要值的算法，可用SM3或SHA256signString公共參數(shù)參數(shù)摘要值，根據AppKey和AppSecret，采用SM3加密計算得出InterfacenameString業(yè)務參數(shù)數(shù)據接口ID，見表5“數(shù)據接口ID”列DataObject業(yè)務參數(shù)傳輸?shù)木唧w業(yè)務數(shù)據，見表7~表13SM22。表2接口返回參數(shù)參數(shù)名參數(shù)類型分類參數(shù)說明codeInt公共參數(shù)接口調用返回編碼，200為請求成功，非200為請求失敗msgString公共參數(shù)調用提示或錯誤信息dataObject業(yè)務參數(shù)接口返回信息，一般各接口對應返回信息如下：市場主體信息存證接口：bcHash_member合同信息存證接口：bcHash_contract合同關聯(lián)映射關系存證接口：bcHash_contractlist結算信息存證接口：bcHash_settlement綠證劃轉信息存證接口：bcHash_green_certificateSM2。表3接口請求參數(shù)參數(shù)名參數(shù)類型分類參數(shù)說明AppKeyString公共參數(shù)用戶名，由區(qū)塊鏈平臺線下分配給綠色電力交易平臺的鑒權信息，用于賦予接口調用權限hashAlgString公共參數(shù)用于計算參數(shù)摘要值的算法，SM3或SHA256signString公共參數(shù)參數(shù)摘要值，根據AppKey和AppSecret，采用SM3加密計算得出TaskIDString業(yè)務參數(shù)傳輸任務對應的數(shù)據接口ID，見表6“數(shù)據接口ID”列dataObject業(yè)務參數(shù)接口調用信息，一般各接口對應的調用信息如下：市場主體信息溯源查詢接口：市場主體ID合同信息溯源查詢接口：合同ID結算信息溯源查詢接口：結算ID綠證劃轉信息溯源查詢接口：綠證編號ID綠色電力消費證明獲取接口：合同ID或結算ID66SM2。表4接口返回參數(shù)參數(shù)名參數(shù)類型分類參數(shù)說明codeInt公共參數(shù)接口調用返回編碼，200為請求成功，非200為請求失敗hashAlgString公共參數(shù)用于計算參數(shù)摘要值的算法，SM3或SHA256signString公共參數(shù)參數(shù)摘要值，根據AppKey和AppSecret，采用SM3加密計算得出msgString公共參數(shù)調用提示或錯誤信息dataObject業(yè)務參數(shù)接口返回信息，傳輸?shù)木唧w業(yè)務數(shù)據，見表14-表21區(qū)塊鏈平臺接收數(shù)據交互要求見表5。表5 區(qū)鏈臺收據交要求對應章節(jié)交互信息數(shù)據接口名稱數(shù)據接口ID傳輸頻率備注7.2.1市場主體信息市場主體信息存證接口MarketEntityInfo_onchain按照業(yè)務周期表77.2.2合同信息合同信息存證接口ContractInfo_onchain按照業(yè)務周期表8~表107.2.3合同映射關系合同關聯(lián)映射關系存證接口Contract_mapping_relationship_onchain按照業(yè)務周期表117.2.4結算信息結算信息存證接口SettlementInfo_onchain按照業(yè)務周期表127.2.5綠證劃轉信息綠證劃轉信息存證接口Green_certificate_onchain按照業(yè)務周期表13區(qū)塊鏈平臺提供數(shù)據交互要求見表6。表6 區(qū)鏈臺供據交要求對應章節(jié)交互信息數(shù)據接口名稱數(shù)據接口ID傳輸頻率備注7.3.1區(qū)塊鏈平臺生成的SM2公鑰SM2公鑰查詢接口Blockchain_pubKey_query—表147.3.2鏈上市場主體信息市場主體信息溯源查詢接口MarketSubjectInfo_trace按業(yè)務需求表157.3.3鏈上合同信息合同信息溯源查詢接口ContractInfo_trace按業(yè)務需求表16~表187.3.4鏈上結算信息結算信息溯源查詢接口SettlementInfo_trace按業(yè)務需求表197.3.5鏈上綠證劃轉信息綠證劃轉信息溯源查詢接口Green_certificate_trace按業(yè)務需求表207.3.6綠色電力消費證明查詢鏈接綠色電力消費證明獲取接口GreenPowerConsumptionCer_query按業(yè)務需求表2177市場主體信息上鏈存證接口為結構化數(shù)據接口，接口數(shù)據信息詳見表7。表7 市主信息序號信息項英文名稱數(shù)據類型備注說明1市場主體IDmembersIdString市場主體對應的唯一標識2市場主體名稱membersNameString—3企業(yè)統(tǒng)一社會信用代碼USCIString—4企業(yè)法人姓名businesscorporationNameString—5地理區(qū)域IDprovinceIdString地理區(qū)域對應的唯一標識6地理區(qū)域名稱provinceNameString—7聯(lián)系人姓名LinkmanNameString—8聯(lián)系人電話LinkmanPhoneString—合同信息上鏈存證接口為結構化數(shù)據接口，接口數(shù)據信息詳見表8~表10。表8 合信息序號信息項英文名稱數(shù)據類型備注說明1合同IDcontractIdString合同信息對應的唯一標識2合同名稱contractNameString—3綠電合同分類contractTypeString0（用戶—發(fā)電廠）1（售電公司—代理機構）2（代理機構—發(fā)電廠）3（用戶—售電公司）4（售電公司—發(fā)電廠）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(續(xù))序號信息項英文名稱數(shù)據類型備注說明15交易序列名稱transactionNameString—16合同電價contractPriceBigDecimal—17售電方發(fā)電類型sellerPowerTypeString—18售電方省份IDsellerProvinceIdString售電方省份對應的唯一標識19售電方省份名稱sellerProvinceNameString—20購電方省份IDpurchaserProvinceIdString購電方省份對應的唯一標識21購電方省份名稱purchaserProvinceNameString—22合同分月信息energyInfosList具體見表1023輸電方相關信息transferConfirmsList具體見表1124綠色權益電價greenRightsPriceDecimal—表9 合分信息序號信息項英文名稱數(shù)據類型備注說明1合同IDcontractIdString合同信息對應的唯一標識2分月開始時間startDateDate—3分月結束時間endDateDate—4分月合同電量contractEnergyBigDecimal—5分月總電價PriceBigDecimal—6分月電能量電價energyPriceBigDecimal—7分月綠色權益電價greenRightsPriceDecimal—表10 電相信息序號信息項英文名稱數(shù)據類型備注說明1合同IDcontractIdString合同信息對應的唯一標識2交易序列IDtradeseqIdString交易序列對應的唯一標識3輸電方主體IDpowerGridIdString輸電方的市場主體對應的唯一標識4輸電方名稱powerGridNameString—。99表11 同射系息序號信息項英文名稱數(shù)據類型備注說明1售電公司和代理機構簽訂的合同IDbuyContractIdString售電公司和代理機構簽訂的合同信息對應的唯一標識2代理機構和發(fā)電廠簽訂的合同IDsellContractIdString代理機構和發(fā)電廠簽訂的合同信息對應的唯一標識3用戶和售電公司簽訂的合同IDretailContractIdString用戶和售電公司簽訂的合同信息對應的唯一標識4售電公司和發(fā)電廠簽訂的合同IDwholesaleContractIdString售電公司和發(fā)電廠簽訂的合同信息對應的唯一標識5用戶（非售電公司）和代理機構簽訂的合同IDuserBuyContractIdString用戶（非售電公司）和代理機構簽訂的合同信息對應的唯一標識結算信息上鏈存證接口為結構化數(shù)據接口，接口數(shù)據信息詳見表12。表12結算信息序號信息項英文名稱數(shù)據類型備注說明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—綠證劃轉信息上鏈存證接口為結構化數(shù)據接口，接口數(shù)據信息詳見表13。表13綠證劃轉信息序號信息項英文名稱數(shù)據類型備注說明1綠證編碼IDGreen_certificate_NO.IdString水規(guī)院綠證編碼對應的唯一標識2綠證數(shù)量Green_certificate_QtyBigDecimal—3可再生能源發(fā)電企業(yè)IDRenewenergy_generation_enterprisesIdString與劃轉綠證關聯(lián)的發(fā)電企業(yè)對應的唯一標識4電力用戶IDPoweruserIdString與劃轉綠證關聯(lián)的電力用戶對應的唯一標識1010區(qū)塊鏈平臺生成的SM2公鑰查詢接口為結構化數(shù)據接口，接口數(shù)據信息詳見表14。表14 塊平生的SM2鑰息序號信息項英文名稱數(shù)據類型備注說明1區(qū)塊鏈平臺生成的SM2公鑰Blockchain_pubKeyObject—市場主體信息查詢接口為結構化數(shù)據接口，接口數(shù)據信息詳見表15。表15 上場體息序號信息項英文名稱數(shù)據類型備注說明1市場主體IDmembersIdString市場主體對應的唯一標識2市場主體信息上鏈憑證編號bcHash_memberString—合同信息查詢接口為結構化數(shù)據接口，接口數(shù)據信息詳見表16~表18。表16 上同息序號信息項英文名稱數(shù)據類型備注說明1合同IDcontractIdString合同信息對應的唯一標識2合同名稱contractNameString—3合同電量contractQtyBigDecimal—4電量類型energyTypeString—5合同開始時間contractStartDateDate—6合同結束時間contractEndDateDate—7購電方主體IDpurchaseString購電方的市場主體對應的唯一標識8售電方主體IDsellerString售電方的市場主體對應的唯一標識9交易序列IDtransactionIdString交易序列對應的唯一標識10合同電價contractPriceBigDecimal—11售電方發(fā)電類型sellerPowerTypeString—12合同分月信息energyInfosList見表1613輸電方相關信息transferConfirmsList見表1714合同上鏈憑證編號bcHash_contractString—15綠色權益電價greenRightsPriceDecimal—1111表17 同月息序號信息項英文名稱數(shù)據類型備注說明1合同IDcontractIdString合同信息對應的唯一標識2分月開始時間startDateDate—3分月結束時間endDateDate—4分月合同電量contractEnergyBigDecimal—5分月總電價PriceBigDecimal—6分月電能量電價energyPriceBigDecimal—7分月綠色權益電價greenRightsPriceDecimal—表18 電相信息序號信息項英文名稱數(shù)據類型備注說明1合同IDcontractIdString合同信息對應的唯一標識2交易序列IDtradeseqIdString交易序列對應的唯一標識3輸電方主體IDpowerGridIdString輸電方的市場主體對應的唯一標識4輸電方名稱powerGridNameString—結算信息查詢接口為結構化數(shù)據接口，接口數(shù)據信息詳見表19。表19 上算息序號信息項英文名稱數(shù)據類型備注說明1結算IDsettlementIdString結算信息對應的唯一標識2月度mktMonthString—