环境信用服务 API 参考概述

Microsoft Cloud for Sustainability 技术峰会 2024 年 11 月。

重要提示

此功能的部分或全部属于预览版内容。 相关内容和功能可能会发生更改。 您可以访问环境信用服务(预览)沙盒环境进行 30 天的试用。 要在生产环境中使用环境信用服务(预览),请完成环境信用服务(预览)注册窗体

本文帮助您使用环境信用服务 REST API 执行任务。 要查看完整的 API 参考,请转到环境信用服务 API 参考。 您可以在环境信用服务 REST API 中查找 Swagger 文件。

注册项目

本节介绍如何通过 API 创建、提交和审查生态项目。 有关使用用户界面的说明,请转到在环境信用服务中注册项目

创建项目

若要在创建项目时上传和附加文件,请执行以下操作:

  1. 使用 POST/files 上传文件。 在 API 中指定以下详细信息:

    • 文件或文件 URL
    • 文件的描述性标记
  2. 创建生态项目和对应的模块化收益项目,并将 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 响应中提供的 fileId 下载文件:

   GET/files/{fileId}

将文件附加到模块化收益项目:

   POST/files

批准或拒绝提案

上传文件(如果有):

POST/files 并指定文件(或 FileUrl)和标记详细信息

拒绝注册请求:

POST/proposals/{proposalId}action,并在请求正文中指定以下详细信息

  • 操作:拒绝

  • 消息:指定要为拒绝注册提供的注释(如果有)。

  • FileIDs:指定上传的文件的文件 ID。

删除文件

查看附加到模块化收益项目的文件列表:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

标识您已经上传的文件,因为用户只能删除他们已经上传的那些文件。

删除文件。

   DELETE/files/{fileId}

返回提案以进行编辑

如果项目属性或文件中存在一些您希望供应商更正或添加的空白或不正确的详细信息,则可以请求对项目进行编辑。

  1. 上传必须与供应商共享的文件(如果有):

    POST/files

  2. 使用 POST/proposals/{proposalId}/action API 执行 returnForEdits 操作,将 MBPRegister 提案改为 submitterActionNeeded 状态,并在请求正文中指定以下详细信息:

    • 操作:returnForEdits

    • 消息:指定注释(如果需要)以便供应商在返回编辑请求时参考。

    • 文件 ID:在此处指定已上传文件的文件 ID,以将文件附加到相关的模块化收益项目。

    完成此操作后,模块化收益项目将变为 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 使用。

  1. 上载文件(您希望与供应商共享的文件)并将其附加到已处理声明或已处理声明的检查点结果:POST/files,并在请求正文中指定以下详细信息

    • 文件或文件 URL
    • 标记
    • 必须向其添加文件的已处理声明或已处理声明的检查点结果的资源 URI
  2. 使用 POST/proposals/{proposalId}/action API 执行 returnForEdits 操作,将 MBPClaimVerify 提案改为 submitterActionNeeded 状态,并在请求正文中指定以下详细信息:

    • 操作:returnForEdits
    • 消息:指定注释(如果需要)以便供应商在返回编辑请求时参考。

编辑返回的提案

供应商以后可以查看发回去进行编辑的提案。 他们现在可以编辑索赔和检查点属性,并且可以将更多文件上传到索赔检查点:

  1. 查看提案:GET/proposals/{proposalId}

    • 如果需要,供应商还可以使用 GET/processedClaims/{processed_claim_Id} API 查看相应的已处理声明详细信息。
  2. 向索赔检查点上传并附加文件(如果有):POST/files 并在请求正文中指定以下详细信息

    • 文件或文件 URL
    • 标记
    • 必须将文件添加到的检查点的资源 URI
  3. 使用 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}
  4. 使用 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 调用中的相同结构。

  5. 修改完成后,供应商可以使用 POST/proposals/{proposalId}/action API 将提案提交回审定和验证机构,并在请求正文中指定以下详细信息:

    • 操作:重新提交
    • 消息:指定任何注释(如果需要)以供审定和验证机构参考。

重新提交提案后,审定和验证机构可以查看提案并批准、拒绝或再次请求编辑。

撤回信用额度发放请求

撤回已提交的信用额度发放请求 (CreditMint) 提案的选项:

将信用额度发放提案提交给注册机构后,如因任何问题需要撤回提交的提案,并且注册机构未对该提案采取行动,则可以撤回提交的提案。 此功能目前仅由 API 提供。

  • 使用 POST/proposals/{proposalId}/action API 将处于已提交状态的 CreditMint 提案改为已撤回状态,并在请求正文中指定以下详细信息:

    • 操作:撤回
    • 消息:指定撤回提案的原因(如果有)以供注册机构参考。

该提案的状态现在为已撤回

撤回信用额度发放请求后,审定和验证机构可以修改“已处理声明”和相关的检查点结果,然后重新提交信用额度发放请求。

  • 上载文件并将其附加到已处理声明的检查点结果:POST/files,并指定以下详细信息:

    • 文件或文件 URL
    • 标记
    • 相关检查点结果的 ResourceURI。
  • 更新已处理声明的属性:PATCH/processedClaims/{processedClaim_Id}

  • 重新向注册机构提交颁发请求,并在 API 请求正文中指定以下详细信息:POST/proposals/{ proposal_id}/action

    • 操作:指定为重新提交
    • 消息:指定消息/注释(如果有)以供注册机构参考

发放信用额度

本节介绍如何通过 API 查看和发放信用额度。 有关使用用户界面的说明,请转到在环境信用服务中发放信用额度

查看信用额度发放提案

查看提交的“Token mint”提案,获取已提交审查的“已处理声明”资源 URI:

GET/proposal/{proposalId}

通过查看已处理声明和相关检查点结果(以及相关文件),审查审定和验证机构的验证结果:

GET/processedClaims/{processedClaims_Id} 

查看索赔和相应的检查点详细信息(以及供应商为检查点附加的文件列表):

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}

查看模块化收益项目详细信息以及所附文件列表:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

使用文件 ID 下载文件:

   GET/files/{fileId}

审批信用额度

上传要附加到待发放信用额度的文件:POST/files 并在请求正文中指定以下详细信息:

  • 文件或文件 URL
  • 标记

批准提案:

   POST/proposals/{proposalId}/action

在请求正文中指定以下详细信息:

  • 操作:指定为铸造
  • 消息:指定消息(如果有)以供审定和验证机构参考
  • 文件 ID:指定所上传文件的文件 ID,以便将文件附加到发放的信用额度
  • 数量
  • 旧式
  • 资产 ID
  • 确定的值

备注

提案获得批准后,将创建相应的信用额度。

拒绝提案

将文件(如果有)上传到已处理索赔:POST/files,并指定以下详细信息:

  • 文件或文件 URL
  • 标记

拒绝提案:

   POST/proposals/{proposalId}/action

在请求正文中指定以下详细信息:

  • 操作:拒绝
  • 消息:指定消息(如果有)以供审定和验证机构参考
  • 文件 ID:指定已上传文件的文件 ID,以便将它们附加到相关的已处理声明。

返回信用额度发放请求以进行编辑

如果发放请求中存在一些您希望审定和验证机构更正或添加的空白或错误的详细信息,则可以请求对发放请求进行编辑。 此功能只能通过 API 使用。

  1. 上传您希望在将发放请求发回来编辑过程中与审定和验证机构共享的文件(如果有)。

  2. 使用 POST/proposals/{proposalId}/action API 将发放请求(CreditMint 提案)改为 submitterActionNeeded 状态,并指定以下详细信息:

    • 操作:ReturnForEdits
    • 消息:指定消息(如果有)供审定和验证机构参考,以便他们可以了解编辑请求的原因。
    • 文件 ID:指定已上传文件(如果有)的文件 ID,以便将这些文件附加到相关的已处理声明。

审定和验证机构现在可以查看已发回进行编辑的提案。 他们现在还可以编辑相应的已处理声明和检查点结果。 他们可以更新属性,也可以将更新后的文件上载到检查点结果。

如果需要,此时审定和验证机构可以通过将声明返回给供应商进行编辑,要求对已验证的声明进行澄清。 供应商重新提交声明后,审定和验证机构即可以审查和验证声明,更新相应的已处理声明,然后向注册机构重新提交发放请求。

  1. 上载文件并将其附加到检查点结果:POST/files,并指定以下详细信息:

    • 文件或文件 URL
    • 标记
    • 相关检查点结果的 ResourceURI
  2. 更新已处理声明的属性,包括信用额度建议:PATCH/processedClaim/{processed claim id}

  3. 重新提交颁发请求,并在 API 请求正文中指定以下详细信息:POST/proposals/{ proposal_id}/action

    • 操作:重新提交
    • 消息:指定消息(如果有)以供注册机构参考

重新提交请求后,发放注册机构可以查看请求并批准、拒绝或再次请求编辑。

查看发放的信用额度

   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 使用此功能。

作为信用额度所有者(适用于他们拥有的信用额度)或市场(适用于他们平台上列出的信用额度),指定至少两个子信用额度的数量(以 mtCO2e 为单位)来拆分信用额度:

   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}

使用文件的文件属性中存在的文件 ID 下载文件:

   GET/files/{fileId}

删除文件

使用文件的文件 ID 调用删除 API:

   DELETE/files/{fileId}

环境信用服务概述
配置环境信用服务
环境信用服务术语表