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

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