对 AWS 合作伙伴中心 API 参考进行了重组。有关支持的 API 操作的更多信息，请参阅 [AWS 合作伙伴中心 API 参考](https://docs.aws.amazon.com/partner-central/latest/APIReference/Welcome.html)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用福利申请
<a name="working-with-benefit-applications"></a>

福利申请可以模拟合作伙伴对特定福利的请求。它收集了根据特定福利条件评估和处理申请所需的所有信息。从草稿创建到最终批准或拒绝，福利申请生命周期经历多个状态。

## 创建福利申请
<a name="creating-benefit-applications"></a>

合作伙伴通过使用 `CreateBenefitApplication` API 操作创建福利申请来启动福利申请流程。应用程序在创建时进入`PENDING_SUBMISSION`状态，允许合作伙伴在提交审核之前准备完整的信息。

在创建福利申请时，合作伙伴必须提供：
+ **福利标识符**-所申请福利的 ID 或 ARN
+ **配送类型**-合作伙伴期望如何获得收益（`CREDITS``CASH`、`DISCOUNT`、`ACCESS`、`RECOGNITION`、或`RESOURCE`）
+ **福利申请详情**-包含福利申请架构定义的福利特定信息的 JSON 文档
+ **客户令牌**-一种独特的等性令牌，可防止重复提交

合作伙伴可以选择提供：
+ **名称和描述**-应用程序的 Human-readable 标识符
+ **合作伙伴联系人**-管理此福利申请的人员的联系信息（最多 1 位联系人）
+ **文件附件**-支持文档，例如项目计划、SOW、成本证明或客户满意度调查（最多 10 个文件）
+ **相关资源**-指向相关机会或现有福利分配的链接（最多 10 个资源）
+ **标签**-用于资源组织和跟踪的 Key-value 配对（最多 200 个标签）

`CreateBenefitApplication`API 执行软验证，仅检查基本字段类型和模式。在提交过程中会进行全面的业务逻辑验证，允许合作伙伴保存未完成的申请并稍后返回以完成申请。

**最佳实践：**在创建应用程序之前，合作伙伴应使用中的福利申请架构`GetBenefit`来准确了解需要哪些信息。这降低了由于数据丢失或无效而导致提交失败的可能性。

## 更新福利申请
<a name="updating-benefit-applications"></a>

合作伙伴可以使用 `UpdateBenefitApplication` API 操作修改福利申请草案。这允许合作伙伴在提交之前完善信息、添加文档或更正错误。

更新福利申请时，合作伙伴必须提供：
+ **标识符**-要更新的福利申请的 ID 或 ARN
+ **修订版**-乐观锁定的当前版本号
+ **福利申请详情**-完整的、更新的 JSON 文档

即使只有特定字段发生变化，合作伙伴也必须提交完整的福利申请对象。最佳做法是先使用检索最新的应用程序详细信息`GetBenefitApplication`，修改必要的字段，然后将完整更新的有效载荷提交给`UpdateBenefitApplication`。

O@@ **ptimistic Locking：**修订版字段可确保仅在应用程序自上次检索以来未发生更改时才应用更新。如果修订版与当前数据库值不匹配，则更新会因冲突错误而被拒绝。这样可以防止合作伙伴意外覆盖其他流程或系统所做的更改。

只有在应用程序处于`PENDING_SUBMISSION`状态时才能执行更新。提交后，申请将进入审核流程，无法再通过此 API 进行更新。

## 将资源与福利申请关联
<a name="associating-resources-with-benefit-applications"></a>

合作伙伴可以使用 `AssociateBenefitApplicationResource` API 操作将福利申请关联到相关资源。这在收益与使用收益的业务环境之间建立了宝贵的联系。

支持的资源类型包括：
+ **机会**-将福利申请与中的特定客户机会相关联。这对于特定于机会的福利特别有用，例如与客户互动相关的MAP资金或POC积分。
+ B@@ **ENEFIT\_AL** LOCATION-链接到现有的福利分配，使合作伙伴能够连锁收益或演示如何利用以前的福利

资源关联只能在提交之前发生。一旦提交福利申请（状态更改为`IN_REVIEW`），就不允许再进行关联。合作伙伴可以将最多 10 个资源与每个福利申请相关联。

要取消资源关联，合作伙伴可以使用 `DisassociateBenefitApplicationResource` API 操作。与关联一样，解除关联只能在`PENDING_SUBMISSION`状态下发生。

**重要**  
合作伙伴必须拥有相应的权限才能访问福利申请和读取关联的特定资源。API 会在关联操作期间验证这些权限。

## 提交福利申请
<a name="submitting-benefit-applications"></a>

当福利申请完成并可供AWS审核时，合作伙伴使用 `SubmitBenefitApplication` API 操作提交该申请。提交会触发状态从`PENDING_SUBMISSION`到的转换，`IN_REVIEW`并启动特定福利的批准工作流程。

提交后，API 将执行全面验证，包括：
+ **必填字段验证**-确保福利申请详细信息中的所有必填字段都存在
+ **字段格式验证-验证**字段值是否与预期的模式和数据类型相匹配
+ **业务规则验证**-应用特定于福利的业务逻辑和约束
+ **资源验证**-确认所有关联资源均有效且可访问
+ **文件验证-验证**所有文件附件是否已成功完成处理

如果验证失败，API 会返回 a，其中 ValidationException 包含详细的错误代码和消息，指示哪些字段需要更正。合作伙伴必须`UpdateBenefitApplication`先使用解决这些问题，然后才能再次尝试提交。

**文件处理要求：**如果任何附件仍处于`PENDING`状态，则无法提交福利申请。合作伙伴必须等待文件处理完成（状态更改为`SUCCEEDED`）后才能提交。如果文件处理失败（状态`FAILED`），合作伙伴应上传更正后的版本。

成功提交后：
+ 应用程序状态更改为 `IN_REVIEW`
+ 福利所有人的团队会收到有关新提交的通知
+ 合作伙伴无法再通过标准更新 API 修改应用程序详细信息
+ 申请进入定义的批准工作流程，其中可能包括业务审批、技术批准和财务审批阶段

合作伙伴可以通过检索申请并监视 “阶段” 字段来跟踪提交进度，该字段表示当前的批准阶段（例如，“业务批准”、“技术批准”、“财务批准”）。

## 管理已提交的申请
<a name="managing-submitted-applications"></a>

提交后，合作伙伴管理福利申请的选项有限，但是 API 提供了针对常见场景的特定操作。

### 召回福利申请
<a name="recalling-benefit-applications"></a>

如果合作伙伴在提交后发现错误或需要进行更改，他们可以使用 `RecallBenefitApplication` API 操作撤回应用程序。Recall 会将应用程序恢复到`PENDING_SUBMISSION`状态，允许更新和重新提交。

在召回申请时，合作伙伴应提供：
+ **标识符**-要召回的福利申请的 ID 或 ARN
+ **原因**-召回的可选解释（最多 1000 个字符）

reason 字段可以提高可追溯性，有助于AWS了解导致召回的常见问题，为福利申请流程的未来改进提供信息。

召回后，合作伙伴可以使用`UpdateBenefitApplication`进行必要的更改，然后在准备就绪`SubmitBenefitApplication`后使用重新提交。

**重要**  
召回通常仅在早期审查阶段可用。已进入后期批准阶段或已获得批准的申请可能不符合召回资格。

### 修改福利申请
<a name="amending-benefit-applications"></a>

对于提交后的细微更正，合作伙伴可以使用 `AmendBenefitApplication` API 操作更新特定字段，而无需撤回整个应用程序。当AWS审阅者在审阅过程中要求作出澄清或更正时，这特别有用。

修改使用 JSON Patch-style 方法，其中合作伙伴指定：
+ **路径**-标识要更新的字段的 JSONPath 表达式（例如）`$.CreditDisbursementDetails.AwsAccountIdForCredits`
+ **值**-字段的新值
+ **操作**-要执行的操作（目前`REPLACE`仅支持）

合作伙伴在单次 API 调用中最多可以提交 10 项修改。每项修订都必须包括更新的版本号，以实现乐观锁定。

对于较小的更正，应使用修正案。对于重大更改，合作伙伴应使用`RecallBenefitApplication`将申请恢复为草稿状态以进行全面更新。

### 取消福利申请
<a name="canceling-benefit-applications"></a>

如果合作伙伴不再需要福利或希望撤回申请，他们可以使用 `CancelBenefitApplication` API 操作取消申请。取消会将申请转换为`CANCELED`状态，从而永久结束申请流程。

取消申请时，合作伙伴应提供：
+ **标识符**-要取消的福利申请的 ID 或 ARN
+ **原因**-取消的可选解释（最多 1000 个字符）

一旦取消，就无法重新激活应用程序。如果合作伙伴后来决定需要该福利，则他们必须创建新的福利申请。

取消预订的常见原因包括：
+ 客户机会丢失或延迟
+ 合作伙伴容量限制已改变
+ 业务优先事项发生了变化
+ 不再需要福利来实现预期目的

## 查看福利申请详情
<a name="viewing-benefit-application-details"></a>

合作伙伴可以使用 `GetBenefitApplication` API 操作检索有关福利申请的完整信息。这提供了应用程序的全面视图，包括：

**应用程序元数据：**
+ 唯一标识符 (ID) 和亚马逊资源名称 (ARN)
+ 关联的福利标识符
+ 应用程序名称和描述
+ 当前状态（`PENDING_SUBMISSION`、`IN_REVIEW`、`ACTION_REQUIRED`、`APPROVED`、`REJECTED`、或`CANCELED`）
+ 当前处理阶段

**状态信息：**
+ 状态原因- Human-readable 对当前状态的解释
+ 状态原因代码-表示特定问题或要求的结构化代码（例如，“清单不完整”、“缺少项目计划”、“缺少设计胜利”）

**应用程序内容：**
+ 完整的福利申请详情 JSON 文档
+ 合作伙伴联系信息
+ 带有处理状态的文件附件
+ 关联资源（机会或分配）
+ 资源标签

**审计信息：**
+ 创建时间戳
+ 上次修改时间戳
+ 当前修订号

当应用程序处于状态时，`ACTION_REQUIRED`状态原因代码特别有用。这些守则提供了具体、可操作的指导，说明合作伙伴需要解决哪些问题才能继续申请。

## 列出福利申请
<a name="listing-benefit-applications"></a>

合作伙伴可以使用 `ListBenefitApplications` API 操作查看其所有福利申请。这将返回具有强大筛选功能的分页应用程序摘要列表。

合作伙伴可以按以下方式筛选应用程序：
+ **程序**-查看特定程序（MAP、MDF、沙盒、POC 等）的应用程序
+ **配送类型**-按配送方式（`CREDITS`、`CASH``ACCESS`、等）筛选
+ **福利标识符**-查看特定福利的申请
+ **状态**-按应用程序状态 (`PENDING_SUBMISSION`、、、`IN_REVIEW``APPROVED``REJECTED`、`CANCELED`) 筛选
+ **阶段**-按批准阶段筛选（业务审批、技术审批、财务审批）
+ **关联资源 ARN**-查找与特定机会或分配相关的应用程序

列表回复包括基本的摘要信息，例如：
+ 应用程序 ID、ARN 和名称
+ 关联的福利 ID
+ 计划和配送类型
+ 当前状态和阶段
+ 创建和修改时间戳
+ 关联的资源
+ 当前修订号
+ 福利申请详细信息中的选定字段（由福利所有人定义）

合作伙伴可以使用 “排序” 参数配置结果排序，并提供按创建日期、状态、计划或福利标识符升序或降序排序的选项。

**控制面板构建：**`ListBenefitApplications`API 旨在支持合作伙伴控制面板的创建。通过对应用程序进行筛选和排序，合作伙伴可以生成如下视图：
+ 需要操作的应用程序（`ACTION_REQUIRED`状态）
+ 最近提交的申请（按创建日期、`IN_REVIEW`状态排序）
+ 待分配的已批准申请（`APPROVED`状态）
+ 按程序划分的应用程序（按特定程序筛选）