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
+ **履行類型** - 合作夥伴預期如何獲得利益 `DISCOUNT`(`CREDITS`、`CASH`、`RECOGNITION`、`ACCESS`、 或 `RESOURCE`)
+ **利益應用程式詳細資訊** - 包含利益請求結構描述所定義之利益特定資訊的 JSON 文件
+ **用戶端字符** - 防止重複提交的唯一冪等字符

合作夥伴可以選擇性地提供：
+ **名稱和描述** - 應用程式的人類可讀取識別符
+ **合作夥伴聯絡人** - 管理此利益請求的人員的聯絡資訊 （最多 1 位聯絡人）
+ **檔案附件** - 支援文件，例如專案計劃、SOWs、成本證明或客戶滿意度調查 （最多 10 個檔案）
+ **相關資源** - 相關機會或現有利益分配的連結 （最多 10 個資源）
+ **標籤** - 資源組織和追蹤的鍵值對 （最多 200 個標籤）

`CreateBenefitApplication` API 會執行軟驗證，只檢查基本欄位類型和模式。完整商業邏輯驗證會在提交期間進行，允許合作夥伴儲存不完整的應用程式，並在稍後傳回以完成它們。

**最佳實務：**合作夥伴應使用來自 的利益請求結構描述`GetBenefit`，確切了解在建立應用程式之前需要哪些資訊。這可降低因資料遺失或無效而提交失敗的可能性。

## 更新利益應用程式
<a name="updating-benefit-applications"></a>

合作夥伴可以使用 `UpdateBenefitApplication` API 動作修改利益應用程式草稿。這可讓合作夥伴在提交之前精簡資訊、新增文件或更正錯誤。

更新利益應用程式時，合作夥伴必須提供：
+ **識別符** - 要更新之利益應用程式的 ID 或 ARN
+ **修訂** - 樂觀鎖定的目前修訂編號
+ **利益應用程式詳細資訊** - 完整、更新的 JSON 文件

合作夥伴必須提交完整的利益應用程式物件，即使只有特定欄位變更。最佳實務是先使用 擷取最新的應用程式詳細資訊`GetBenefitApplication`、修改必要欄位，然後將完整更新的承載提交至 `UpdateBenefitApplication`。

**樂觀鎖定：**修訂欄位可確保只有在應用程式自上次擷取以來未變更時，才會套用更新。如果修訂版不符合目前的資料庫值，則更新會因衝突錯誤而遭到拒絕。這可防止合作夥伴意外覆寫其他程序或系統所做的變更。

更新只能在應用程式處於 `PENDING_SUBMISSION` 狀態時執行。提交後，應用程式會進入檢閱程序，且無法再透過此 API 更新。

## 將資源與利益應用程式建立關聯
<a name="associating-resources-with-benefit-applications"></a>

合作夥伴可以使用 `AssociateBenefitApplicationResource` API 動作將受益應用程式連結至相關資源。這會在利益和使用利益的業務內容之間建立寶貴的關聯。

支援的資源類型包含：
+ **機會** - 將利益應用程式連結至 中的特定客戶機會。這對於特定機會的好處特別有用，例如與客戶業務互動相關的 MAP 資金或 POC 點數。
+ **BENEFIT\_ALLOCATION** - 連結至現有的利益分配，讓合作夥伴能夠鏈結利益或示範如何利用先前的利益

資源關聯只能在提交之前發生。提交利益應用程式後 （狀態變更為 `IN_REVIEW`)，即不允許進一步關聯。合作夥伴最多可將 10 個資源與每個利益應用程式建立關聯。

若要取消資源的關聯，合作夥伴會使用 `DisassociateBenefitApplicationResource` API 動作。與關聯類似，取消關聯只能以 `PENDING_SUBMISSION` 狀態發生。

**重要**  
合作夥伴必須擁有適當的許可，才能存取利益應用程式並讀取相關聯的特定資源。API 會在關聯操作期間驗證這些許可。

## 提交利益應用程式
<a name="submitting-benefit-applications"></a>

當利益應用程式完成並準備好 AWS 檢閱時，合作夥伴會使用 `SubmitBenefitApplication` API 動作提交該應用程式。提交會觸發從 `PENDING_SUBMISSION` 到 的狀態轉換，`IN_REVIEW`並啟動利益特定的核准工作流程。

提交時，API 會執行全面的驗證，包括：
+ **必要欄位驗證** - 確保利益應用程式詳細資訊中的所有必要欄位都存在
+ **欄位格式驗證** - 驗證欄位值是否符合預期的模式和資料類型
+ **業務規則驗證** - 套用利益特定的業務邏輯和限制條件
+ **資源驗證** - 確認所有相關資源都有效且可存取
+ **檔案驗證** - 驗證所有檔案附件是否已成功完成處理

如果驗證失敗，API 會傳回 ValidationException，其中包含詳細的錯誤代碼和訊息，指出哪些欄位需要更正。合作夥伴必須使用 解決這些問題，`UpdateBenefitApplication`然後再嘗試再次提交。

**檔案處理需求：**如果任何連接的檔案仍處於 `PENDING` 狀態，則無法提交利益應用程式。合作夥伴必須等待檔案處理完成 （狀態變更為 `SUCCEEDED`)，才能提交。如果檔案處理失敗 （狀態 `FAILED`)，合作夥伴應該上傳更正的版本。

成功提交後：
+ 應用程式狀態會變更為 `IN_REVIEW`
+ 利益擁有者的團隊會收到新提交的通知
+ 合作夥伴無法再透過標準更新 APIs修改應用程式詳細資訊
+ 應用程式會進入定義的核准工作流程，其中可能包括業務核准、技術核准和財務核准階段

合作夥伴可以透過擷取應用程式並監控階段欄位來追蹤提交進度，該欄位指出目前的核准階段 （例如「商業核准」、「技術核准」、「財務核准」)。

## 管理提交的應用程式
<a name="managing-submitted-applications"></a>

提交後，合作夥伴在管理利益應用程式的選項有限，但 API 為常見案例提供特定動作。

### 回收利益應用程式
<a name="recalling-benefit-applications"></a>

如果合作夥伴在提交後發現錯誤或需要進行變更，他們可以使用 `RecallBenefitApplication` API 動作叫用應用程式。Recall 會將應用程式轉換回 `PENDING_SUBMISSION` 狀態，允許更新和重新提交。

召回應用程式時，合作夥伴應該提供：
+ **識別符** - 要回收之利益應用程式的 ID 或 ARN
+ **原因** - 回收的選用說明 （最多 1000 個字元）

原因欄位可實現更好的可追蹤性，並有助於 AWS 了解導致召回的常見問題，以通知未來改善利益應用程式程序。

召回後，合作夥伴可以使用 `UpdateBenefitApplication`進行必要的變更，然後在準備就緒`SubmitBenefitApplication`時使用 重新提交。

**重要**  
召回通常只能在早期審查階段期間使用。已進入稍後核准階段或已核准的應用程式可能不符合召回資格。

### 修改利益應用程式
<a name="amending-benefit-applications"></a>

對於提交後的次要更正，合作夥伴可以使用 `AmendBenefitApplication` API 動作來更新特定欄位，而無需重新叫用整個應用程式。當 AWS 檢閱者在檢閱過程中請求釐清或更正時，這特別有用。

修訂使用合作夥伴指定的 JSON 修補程式樣式方法：
+ **路徑** - 識別要更新之欄位的 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) 和 Amazon Resource Name (ARN)
+ 相關聯的利益識別符
+ 應用程式名稱和描述
+ 目前狀態 (`PENDING_SUBMISSION`、`IN_REVIEW`、`ACTION_REQUIRED``APPROVED`、`REJECTED`、 或 `CANCELED`)
+ 目前處理階段

**狀態資訊：**
+ 狀態原因 - 人類可讀取的目前狀態說明
+ 狀態原因代碼 - 指出特定問題或要求的結構化代碼 （例如「檢查清單未完成」、「專案計畫遺失」、「設計成功遺失」)

**應用程式內容：**
+ 完整利益應用程式詳細資訊 JSON 文件
+ 合作夥伴聯絡資訊
+ 具有處理狀態的檔案附件
+ 關聯的資源 （機會或配置）
+ 資源標籤

**稽核資訊：**
+ 建立時間戳記
+ 上次修改時間戳記
+ 目前的修訂編號

當應用程式處於 `ACTION_REQUIRED` 狀態時，狀態原因代碼特別重要。這些代碼針對合作夥伴需要處理的應用程式以繼續，提供具體、可行的指引。

## 列出利益應用程式
<a name="listing-benefit-applications"></a>

合作夥伴可以使用 `ListBenefitApplications` API 動作檢視其所有利益應用程式。這會傳回具有強大篩選功能的應用程式摘要分頁清單。

合作夥伴可以依下列條件篩選應用程式：
+ **程式** - 檢視特定程式 (MAP、MDF、沙盒、POC 等） 的應用程式
+ **履行類型** - 依交付方法篩選 (`CREDITS`、`ACCESS`、 `CASH`等）
+ **利益識別符** - 檢視應用程式以取得特定利益
+ **狀態** - 依應用程式狀態 (`PENDING_SUBMISSION`、`IN_REVIEW`、`REJECTED`、) `APPROVED`篩選 `CANCELED`
+ **階段** - 依核准階段篩選 （業務核准、技術核准、財務核准）
+ **關聯的資源 ARNs** - 尋找連結至特定機會或配置的應用程式

清單回應包含基本摘要資訊，例如：
+ 應用程式 ID、ARN 和名稱
+ 關聯的利益 ID
+ 程式和履行類型
+ 目前狀態和階段
+ 建立和修改時間戳記
+ 相關資源
+ 目前的修訂編號
+ 從利益應用程式詳細資訊選取的欄位 （由利益擁有者定義）

合作夥伴可以使用排序參數設定結果排序，並可選擇依建立日期、狀態、程式或利益識別符以遞增或遞減順序排序。

**Dashboard Building：**`ListBenefitApplications`API 旨在支援合作夥伴儀表板建立。透過篩選和排序應用程式，合作夥伴可以建立檢視，例如：
+ 需要動作的應用程式 (`ACTION_REQUIRED` 狀態）
+ 最近提交的應用程式 （依建立日期、`IN_REVIEW`狀態排序）
+ 核准的應用程式待分配 (`APPROVED` 狀態）
+ 依程式的應用程式 （依特定程式篩選）