環境信用服務 API 參考概觀
重要
這其中部分或所有的功能會做為預覽版本的一部分來提供。 內容和功能隨時可能變更。 您可以存取環境信用服務 (預覽版) 沙箱環境來進行 30 天試用。 若要在生產環境中使用環境信用服務 (預覽版),請完成環境信用服務 (預覽版) 註冊表單。
本文協助您使用環境信用服務 REST API 來執行工作。 若要查看完整的 API 參考,請移至環境信用服務 API 參考。 您可以在環境信用服務 REST API 上找到 Swagger 檔案。
註冊專案
本節向您展示如何透過 API 建立、提交和審查生態專案。 如需有關使用此使用者介面的指示,請移至在環境信用服務中註冊專案。
建立專案
若要在建立專案時上傳並附加檔案:
使用 POST/files 上傳檔案。 在 API 中指定下列詳細資料:
- 檔案或檔案 URL
- 檔案的描述性標籤
建立生態專案及對應的模組化效益專案,並指定 POST/files API 呼叫回應中傳回的 fileID 做為專案建立 API 要求本文中的屬性:POST/ecoprojects。
儲存並提交專案
擷取專案的詳細資訊:
GET/ecoProjects/{ecoProjectId}
檢視附加至模組化效益專案的檔案清單 (以及其相關聯的中繼資料):
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
使用做為檔案中繼資料一部分提供的 fileID 來下載檔案:
GET/files/{fileId}
將檔案新增至模組化效益專案:
POST/files
在要求本文中指定模組化效益專案的資源 URI。
提交 MBPRegister 提案,以送出模組化效益專案供註冊:
POST/proposals
檢視專案
擷取所有的提案:
GET/proposals
擷取特定提案的詳細資料:
GET/proposals/{proposalId}
擷取特定生態專案的詳細資料:
GET/ecoProjects/{ecoProjectId}
擷取要審查的特定 MBP 詳細資料:
GET/ecoProjects/{ecoProjectId}/mbps/{mbpId}
取得附加至模組化效益專案的檔案清單 (及相關中繼資料):
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
使用做為先前 API 回應一部分提供的欄位來下載檔案:
GET/files/{fileId}
將檔案附加至模組化效益專案:
POST/files
核准或拒絕提案
上傳檔案 (如果有):
POST/files,並指定 File (或 FileUrl) 和標籤詳細資料
拒絕註冊要求:
POST/proposals/{proposalId}/action,並在要求本文中指定下列詳細資料
動作:拒絕
訊息:指定要為拒絕註冊而提供的註解 (如果有)。
FileIDs:指定所上傳檔案的檔案識別碼。
刪除檔案
檢視附加至模組化效益專案的檔案清單:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
識別您已上傳的檔案,因為使用者只能刪除他們所上傳的檔案。
刪除檔案:
DELETE/files/{fileId}
退回提案供編輯
如果想要讓供應商更正或新增的專案屬性或檔案中存在一些差距或不正確的詳細資料,您可以要求對專案進行編輯。
上傳必須與供應商共用的檔案 (如果有):
POST/files
使用 POST/proposals/{proposalId}/action API 執行 returnForEdits 動作以將 MBPRegister 提案移至 submitterActionNeeded 狀態,並在要求本文中指定下列詳細資料:
動作:returnForEdits
訊息:退回要求供編輯時,指定給供應商作參考的註解 (如果需要)。
檔案識別碼:指定此處所上傳檔案的檔案識別碼,以將檔案附加至相關的模組化效益專案。
完成此動作後,模組化效益專案會移至 returnedForEdits 狀態。
供應商現在可以檢視送回供編輯的提案。 他們現在可以編輯模組化效益專案屬性,並將更多檔案上傳至模組化效益專案。
檢視提案:GET/proposals/{proposalId}
將檔案上傳並附加至模組化效益專案:POST/files,並在要求本文中指定下列詳細資料:
- 檔案或檔案 URL
- 標籤:描述性檔案標籤
- ResourceURI:指定相應模組化效益專案的資源 URI。
更新模組化效益專案的屬性
- 使用 GET/ecoprojects/{ecoproject_id}/mbps/{mbp_id} 取得更新的模組化效益專案詳細資料,並複製回應標頭中的 Etag 值。
- 使用 PATCH/ecoprojects/{ecoproject_id}/mbps/{mbp_id} API 更新模組化效益專案屬性,並在標頭的 If-Match 金鑰中指定 Etag 值。
變更完成後,供應商現在可以使用 POST/proposals/{proposalId}/action API 將提案送回登記處,並在要求中指定下列詳細資料:
動作:提交
訊息:指定供登記處參考的註解 (如果有)。
註冊其他模組化效益專案
建立並送出 MBPRegister 提案,以將生態效益提交至發行登記機構進行註冊:
POST/proposal
審查模組化效益專案
檢視提案詳細資料:
GET/proposals/{proposalId}
檢視整個專案詳細資料:
GET/ecoProjects/{ecoProjectId}
檢視專案個別模組化效益專案的詳細資料:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
核准或拒絕註冊提案,或將其退回供編輯:
POST/proposals/{proposalId}/action
處理宣告
本節向您展示如何透過 API 處理宣告。 如需有關使用此使用者介面的指示,請移至在環境信用服務中處理宣告。
建立宣告
建立宣告:
POST/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims
上傳檔案並將其附加至宣告檢查點:
POST/files
在要求中指定下列詳細資料:
- 檔案或檔案 URL
- 標籤
- 宣告的資源 URI
提交宣告
建立並提交模組化效益 projectClaimVerify 提案:
POST/proposals
檢視已提交提案的詳細資料:
GET/proposal/{proposalId}
檢視宣告的詳細資料:
POST/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}
驗證宣告
檢視提案:
GET/proposals
擷取特定提案的詳細資料:
GET/proposals/{proposalId}
擷取驗證提案已提交之特定宣告的詳細資料:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}
接受驗證宣告的工作:
POST/proposals/{proposalId}/action
列出與模組化效益專案相關聯的檔案:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
列出與宣告檢查點相關聯的檔案:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpclaims/{claimId}/checkpoints
檢視附加至特定資產的檔案:
GET/files/{fileId}
接受宣告之後,就會建立對應的「已處理的宣告」。 記錄您對已處理宣告的驗證結果。 這包括更新數量、宣告的共同效益。 提交信用額度發行要求之前,您也必須更新對已處理宣告的信用額度建議:
- 使用 GET/processedClaims/{processed_claim_id} 取得已處理的宣告詳細資料,並從回應標頭複製 Etag 值。
- 使用 PATCH/processedClaims/{processed_claim_id} API 更新已處理的宣告屬性,並在標頭的 If-Match 金鑰中指定 Etag 值。
對於您驗證的每個檢查點,都可以在已處理宣告的對應檢查點結果上更新驗證結果:
- 使用 POST/files API 上傳驗證結果報表,並將其附加至已處理宣告的檢查點結果,然後在要求本文中指定檔案或檔案 URL、標籤和 ResourceUri (這會是檢查點結果的資源 URI)。
- 更新檢查點結果屬性之前和之後的環境效果 (如果需要):
- 使用 GET/processedClaims/{processed_claim_Id}/checkpointResults/{checkpoint_result_Id} 取得檢查點結果詳細資料,並從回應標頭複製 Etag 值。
- 使用 PATCH/processedClaims/{processed_claim_Id}/checkpointResults/{checkpoint_result_Id} API 更新檢查點結果的屬性,並在標頭的 If-Match 金鑰中指定 Etag 值。
- 您還可以對已處理的宣告使用修補 API 來更新檢查點結果。
驗證完成後,即核准或拒絕 MBPClaimVerify 提案:
POST/proposals/{proposalId}/action
指定下列詳細資料:
動作:核准或拒絕
訊息:指定給供應商作參考的註解 (如果有)。
核准 MBPClaimVerify 提案後,即建立並提交 CreditMint 提案,以提交信用額度發行要求:
POST/proposals/
退回宣告要求供編輯
如果驗證與查核機構想要讓供應商更正或新增的宣告要求中存在一些差距或不正確的詳細資料,您可以要求對宣告要求進行編輯,而不核准或拒絕要求。 此功能只能透過 API 來使用。
將檔案 (要與供應商共用) 上傳並附加至已處理宣告,或至已處理宣告的檢查點結果:POST/files,然後在要求本文中指定下列詳細資訊
- 檔案或檔案 URL
- 標籤
- 已處理宣告的資源 URI,或是必須在其中新增檔案之已處理宣告的檢查點結果
使用 POST/proposals/{proposalId}/action API 執行 returnForEdits 動作以將 MBPClaimVerify 提案移至 submitterActionNeeded 狀態,並在要求本文中指定下列詳細資料:
- 動作:returnForEdits
- 訊息:退回要求供編輯時,指定給供應商作參考的註解 (如果需要)。
編輯退回的提案
供應商接著可以檢視送回供編輯的提案。 他們現在可以編輯宣告和檢查點屬性,並且可以將更多檔案上傳至宣告檢查點:
檢視提案:GET/proposals/{proposalId}
- 如有需要,供應商也可以使用 GET/processedClaims/{processed_claim_Id} API 來檢視對應的已處理宣告詳細資料。
將檔案 (如果有) 上傳並附加至宣告檢查點:POST/files,並在要求本文中指定下列詳細資料
- 檔案或檔案 URL
- 標籤
- 必須將檔案新增到的檢查點資源 URI
使用 PATCH 作業更新宣告屬性:
- 取得最新的宣告詳細資料,並記下回應標頭中的 ETag 值:GET/ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}
- 更新宣告屬性,並在要求標頭的 ‘If-Match’ 金鑰中指定 Etag 值:PATCH /ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}
使用 PATCH 作業更新宣告檢查點:
取得最新的檢查點詳細資料,並記下回應標頭中的 ETag 值:GET /ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}/checkpoints/{mbpcheckpoint_id}
更新宣告屬性,並在要求標頭的 If-Match 金鑰中指定 Etag 值:PATCH /ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}/checkpoints/{mbpcheckpoint_id}
注意
指定更新屬性時,請確定 JSON 要求本文遵循與相應 get API 呼叫中結構相同的結構。
完成修改後,供應商可以接著使用 POST/proposals/{proposalId}/action API 將提案送回驗證與查核機構,並在要求本文中指定下列詳細資料:
- 動作:重新提交
- 訊息:指定任何供驗證與查核機構參考的註解 (如果需要)。
重新提交提案後,驗證與查核機構可以審查提案,然後核准、拒絕或再次要求編輯。
撤回信用額度發行要求
用於撤回已提交的信用額度發行要求 (CreditMint) 提案的選項:
將信用額度發行提案提交至登記處後,如因任何問題而要撤回已提交的提案,只要登記處尚未就此提案進行處理,就可以撤回已提交的提案。 此功能目前只能透過 API 使用。
使用 POST/proposals/{proposalId}/action API,將處於已提交狀態的 CreditMint 提案轉為已撤回狀態,並在要求本文中指定下列詳細資料:
- 動作:撤回
- 訊息:指定供登記處參考的提案撤回原因 (如果有)。
提案的狀態現在jn 已撤回。
撤回信用額度發行要求後,驗證與查核機構可以修改「已處理的宣告」和相關聯檢查點結果,然後重新提交信用額度發行要求。
將檔案上傳並附加至已處理宣告的檢查點結果:POST/files,並指定下列詳細資料:
- 檔案或檔案 URL
- 標籤
- 相關聯檢查點結果的 ResourceURI。
更新已處理宣告的屬性:PATCH/processedClaims/{processedClaim_Id}
將發行要求重新提交給登記機構,並在 API 要求本文中指定下列詳細資料:POST/提案/{proposal_id}/動作
- 動作:指定為重新提交
- 訊息:指定供登記處參考的訊息/註解 (如果有)
發行信用額度
本節向您展示如何透過 API 來檢視和發行信用額度。 如需有關使用此使用者介面的指示,請移至在環境信用服務中發行信用額度。
審查信用額度發行提案
檢視已提交的「代幣鑄造」提案,並取得已提交供審查的「已處理的宣告」資源 URI:
GET/proposal/{proposalId}
檢視已處理宣告和相關聯檢查點結果 (以及相關聯的檔案),以審查驗證與查核機構的驗證調查結果。
GET/processedClaims/{processedClaims_Id}
檢視宣告以及對應的檢查點詳細資料 (連同檢查點供應商所附加檔案的清單):
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}
檢視模組化效益專案詳細資料,以及附加檔案的清單:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
使用檔案識別碼下載檔案:
GET/files/{fileId}
核准信用額度
上傳您要附加至信用額度供發行的檔案:POST/files,並在要求本文中指定下列詳細資料:
- 檔案或檔案 URL
- 標籤
核准提案:
POST/proposals/{proposalId}/action
在要求本文中指定下列詳細資料:
- 動作:指定為鑄幣
- 訊息:指定供驗證與查核機構參考的訊息 (如果有)
- 檔案識別碼:指定所上傳檔案的檔案識別碼,讓檔案附加至已發行的信用額度
- 數量
- 年份
- 資產識別碼
- 確定值
注意
提案已核准時,將會建立相對應的信用額度。
拒絕提案
將檔案 (如果有) 上傳至已處理的宣告:POST/files,並指定下列詳細資料:
- 檔案或檔案 URL
- 標籤
拒絕提案:
POST/proposals/{proposalId}/action
在要求本文中指定下列詳細資料:
- 動作:拒絕
- 訊息:指定供驗證與查核機構參考的訊息 (如果有)
- 檔案識別碼:指定所上傳檔案的檔案識別碼,讓這些檔案附加至相關聯的已處理宣告。
退回信用額度發行要求供編輯
如果想要讓驗證與查核機構更正的發行要求中存在差距或不正確的詳細資料,您可以要求對發行要求進行編輯。 此功能只能透過 API 來使用。
在送回發行要求供編輯的過程中,上傳您要與驗證與查核機構共用的檔案 (如果有)。
使用 POST/proposals/{proposalId}/action API,將發行要求 (CreditMint 提案) 轉為 submitterActionNeeded 狀態:
- 動作:ReturnForEdits
- 訊息:指定供驗證與查核機構參考的訊息 (如果有),讓供他們可以了解要編輯要求的原因。
- 檔案識別碼:指定所上傳檔案 (如果有) 的檔案識別碼,讓這些檔案附加至相關聯的已處理宣告。
驗證與查核機構現在可以檢視已送回供編輯的提案。 現在還可以編輯對應的已處理宣告和檢查點結果。 他們可以更新屬性,以及將更新的檔案上傳至檢查點結果。
如有需要,驗證與查核機構此時可將需要編輯的宣告退回給供應商,以要求對驗證的宣告進行澄清。 供應商重新提交宣告之後,驗證與查核機構就可以審查並驗證該宣告,更新對應的已處理宣告,然後將發行要求重新提交至登記機構。
將檔案上傳並附加至檢查點結果:POST/files,並指定下列詳細資料:
- 檔案或檔案 URL
- 標籤
- 相關聯檢查點結果的 ResourceURI
更新已處理宣告的屬性,包括信用額度建議:PATCH/processedClaim/{已處理宣告識別碼}
重新提交發行要求,並在 API 要求本文中指定下列詳細資料:POST/提案/{proposal_id}/動作
- 動作:重新提交
- 訊息:指定供登記處參考的訊息 (如果有)
重新送出要求之後,發行登記機構可以審查要求,然後核准、拒絕或再次要求編輯。
檢視發行的信用額度
GET/credits
搜尋並檢視信用額度
擷取所有信用額度:
GET/credits
注意
此 API 將會傳回所有信用額度的清單。 買方接著可以自行根據信用額度狀態篩選清單,僅檢視已上架的信用額度。
檢視清單中所顯示特定信用額度的信用額度詳細資料 (包括譜系):
GET/credits/{creditId}/lineage
上架信用額度
本節向您展示如何透過 API 將信用額度上架到市場平台以進行交易。 如需有關使用此使用者介面的指示,請移至在環境信用服務中上架信用額度。
註冊為買方或市場平台
以信用額度擁有者或買方的身分提交 MarketplaceTraderRegister 提案:
POST/proposals
以市場平台的身分擷取並審查所有的 MarketplaceTraderRegister 提案:
GET/proposals
以市場平台的身分核准或拒絕提案:
POST/proposals/{proposalId}/action
以市場平台的身分擷取並檢視所有已在其平台上註冊的交易者:
GET/marketplaces/{marketplaceId}/traders
提交要將信用額度上架的提案
建立和提交 MarketplaceListingRegister 提案:
POST/proposals
審查要將信用額度上架的提案
GET/proposals
POST /proposals/{proposalId}/action
管理信用額度
本節向您展示如何透過 API 管理信用額度。 如需有關使用此使用者介面的指示,請移至在環境信用服務中管理信用額度。
下架信用額度
分割信用額度是環境信用服務中的獨立作業。 如需有關透過 API 分割信用額度的詳細資訊,請移至分割信用額度。 信用額度分割之後,您可以繼續下一個步驟。
建立和提交 MarketplaceListingDeregister 提案:
POST/proposals
檢視所有已提交供審查的 MarketplaceListingDeregister 提案:
GET/proposals
若要核准或拒絕提案:
POST/proposals/{proposalId}/action
移轉擁有權
POST/credits/{creditId}/transfer/
檢視信用額度譜系
具備供應商及登記處角色的組織,可以檢視他們所擁有或已發行信用額度的信用額度譜系。
GET/credits/{creditId}/lineage
分割信用額度
您可以將信用額度分割成子信用額度。 此功能目前只能透過 API 使用。
分割信用額度,方法是指定至少兩項子信用額度,做為信用額度擁有者 (代表他們擁有信用額度) 或做為市場平台 (代表已上架至其平台的信用額度) 的數量 (以公噸二氧化碳當量計):
POST/credits/{creditId}/split
信用額度移轉上架
市場平台可以將信用額度從其平台移轉到另一個市場平台上架。 此移轉也稱為權利負擔移轉。 在傳統流程中,供應商會將信用額度上架到可協助處理需求、清算和結算的市場平台。 市場平台有時可能無法自行執行付款清除和結算,而且可能要依靠不同的平台來執行這些作業。 在這種情況下,必須將資產移轉至新的市場平台,才能完成交易。 此功能目前只能透過 API 使用。
以市場平台的身分,為您平台中上架的信用額度建立並提交 MarketplaceListingTransfer 提案:
POST/proposals
以核准者市場平台的身分,檢視所有已提交給他們進行審查的 MarketplaceListingTransfer 提案:
GET/proposals
做為核准者市場平台,核准或拒絕提案。 如果核准提案,則信用額度權利負擔會從初始市場平台移轉至核准者市場平台:
POST/proposals/{proposalId}/action
權利負擔部分移轉:市場可以先將信用額度分割為獨立動作,來移轉部分信用額度的權利負擔。 如需有關如何分割信用額度的詳細資訊,請移至分割信用額度。 分割信用額度之後,繼續上述步驟進行子信用額度的權利負擔移轉。
設定排放目標
本節向您展示如何透過 API 設定排放減量目標和對象。
建立排放目標
POST/esgs
檢視排放目標
GET/esgs
追蹤排放
本節向您展示如何對照透過 API 所設定的排放計分卡來追蹤您的排放。 如需有關使用此使用者介面的指示,請移至在環境信用服務中追蹤排放目標。
建立特定報告週期的里程碑
POST/esgs/{esgScorecardId}/milestones
擷取所有的里程碑:
GET/esgs/{esgScorecardId}/milestones
擷取特定里程碑:
GET/esgs/{esgScorecardId}/milestones/{esgMilestoneId}
根據里程碑追蹤實際排放
POST/esgs/{esgScorecardId}/milestones/{esgMilestoneId}/reportingPeriods/{esgReportingPeriodId}/emissions
GET/esgs/{esgScorecardId}/milestones/{esgMilestoneId}/reportingPeriods/{esgReportingPeriodId}
註銷信用額度
本節向您展示如何透過 API 註銷擁有的碳信用額度來抵換過量的排放。 如需有關使用此使用者介面的指示,請移至在環境信用服務中註銷信用額度。
提交信用額度註銷提案
建立並提交 ESGEmissionOffset 提案:
POST/proposals
買方也可以不指定要抵換的排放量就直接註銷碳信用額度。 此功能只能透過 API 使用。
建立並提交 CreditRetire 提案:
POST/proposals
審查信用額度註銷提案
GET/proposals
GET/proposals/{proposalId}
將檔案附加至要進行註銷審查的信用額度:
POST/files
POST/proposals/{proposalId}/action
部分信用額度註銷
如需有關透過 API 分割信用額度的詳細資訊,請移至分割信用額度。
分割信用額度之後,使用先前步驟中的 API 進行抵換和註銷。
管理檔案
本節向您展示如何透過 API 來附加、檢視和刪除專案、宣告和信用額度等資產的檔案。 如需有關使用此使用者介面的指示,請移至在環境信用服務中管理檔案。
附加檔案
使用 POST/files API,將檔案附加至資產。 您需要指定下列詳細資料:
- 檔案或檔案 URI
- 資產的資源 URI
- 檔案的描述性標籤
檢視檔案
使用資產詳細資料 API,檢視檔案清單以及資產的檔案屬性:
模組化效益專案:
GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}
宣告:
GET/ecoprojects/{ecoProjectId}/mbps/{modular benefit projectId}/mbpClaims/{mbpClaimId}
宣告檢查點:
GET/ecoprojects/{ecoProjectId}/modular benefit projects/{mbpId}/mbpClaims/{mbpClaimId}/checkpoints
信用額度:
GET/credits/{creditId}
使用檔案的檔案屬性中提供的檔案識別碼來下載檔案:
GET/files/{fileId}
刪除檔案
使用檔案的檔案識別碼來呼叫刪除 API:
DELETE/files/{fileId}