A referência Central de Parceiros da AWS da API foi reestruturada. Para obter mais informações sobre as operações de API suportadas, consulte a [Referência Central de Parceiros da AWS da API](https://docs.aws.amazon.com/partner-central/latest/APIReference/Welcome.html).
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Trabalhando com aplicativos de benefícios
Um aplicativo de benefícios modela a solicitação de um parceiro por um benefício específico. Ele captura todas as informações necessárias para avaliar e processar a solicitação de acordo com as condições específicas do benefício. O ciclo de vida do pedido de benefícios avança em vários estados, desde a criação do rascunho até a aprovação ou rejeição final.
## Criação de aplicativos de benefícios
Os parceiros iniciam o processo de solicitação de benefícios criando um aplicativo de benefícios usando a ação da `CreateBenefitApplication` API. Na criação, o aplicativo entra em `PENDING_SUBMISSION` status, permitindo que os parceiros preparem as informações completas antes de enviá-las para análise.
Ao criar um pedido de benefícios, os parceiros devem fornecer:
+ **Identificador do benefício** - O ID ou ARN do benefício que está sendo solicitado
+ **Tipos de atendimento** — Como o parceiro espera receber o benefício (`CREDITS`,,`CASH`,`DISCOUNT`, `ACCESS``RECOGNITION`, ou`RESOURCE`)
+ **Detalhes do aplicativo de benefícios** - Um documento JSON contendo informações específicas do benefício, conforme definido pelo esquema de solicitação do benefício
+ **Token de cliente** - Um token de idempotência exclusivo para evitar envios duplicados
Opcionalmente, os parceiros podem fornecer:
+ **Nome e descrição** - Human-readable identificadores para o aplicativo
+ **Contatos do parceiro** - Informações de contato da pessoa que gerencia essa solicitação de benefício (máximo de 1 contato)
+ **Anexos de arquivo** - Documentação de apoio, como planos de projeto, SOWs, comprovante de custo ou pesquisas de satisfação do cliente (máximo de 10 arquivos)
+ **Recursos associados** - Links para oportunidades relacionadas ou alocações de benefícios existentes (máximo de 10 recursos)
+ **Tags** - Key-value pares para organização e rastreamento de recursos (máximo de 200 tags)
A `CreateBenefitApplication` API realiza uma validação flexível, verificando somente tipos e padrões de campo básicos. A validação completa da lógica de negócios ocorre durante o envio, permitindo que os parceiros salvem as inscrições incompletas e retornem posteriormente para concluí-las.
**Prática recomendada:** os parceiros devem usar o esquema de solicitação de benefícios `GetBenefit` para entender exatamente quais informações são necessárias antes de criar um aplicativo. Isso reduz a probabilidade de falhas no envio devido a dados ausentes ou inválidos.
## Atualizando aplicativos de benefícios
Os parceiros podem modificar os rascunhos dos pedidos de benefícios usando a ação `UpdateBenefitApplication` da API. Isso permite que os parceiros refinem as informações, adicionem documentação ou corrijam erros antes do envio.
Ao atualizar um pedido de benefícios, os parceiros devem fornecer:
+ **Identificador** - O ID ou ARN do pedido de benefício a ser atualizado
+ **Revisão** - O número da revisão atual para um bloqueio otimista
+ **Detalhes do aplicativo de benefícios** - O documento JSON completo e atualizado
Os parceiros devem enviar o objeto completo da solicitação de benefícios, mesmo que somente campos específicos estejam mudando. A melhor prática é primeiro recuperar os detalhes mais recentes do aplicativo usando`GetBenefitApplication`, modificar os campos necessários e, em seguida, enviar a carga útil atualizada completa para. `UpdateBenefitApplication`
**Bloqueio otimista:** o campo de revisão garante que as atualizações sejam aplicadas somente se o aplicativo não tiver sido alterado desde a última vez que foi recuperado. Se a revisão não corresponder ao valor atual do banco de dados, a atualização será rejeitada com um erro de conflito. Isso evita que os parceiros substituam acidentalmente as alterações feitas por outros processos ou sistemas.
As atualizações só podem ser realizadas enquanto o aplicativo estiver em `PENDING_SUBMISSION` status. Depois de enviadas, as inscrições entram no processo de análise e não podem mais ser atualizadas por meio dessa API.
## Associando recursos a aplicativos de benefícios
Os parceiros podem vincular aplicativos de benefícios a recursos relacionados usando a ação `AssociateBenefitApplicationResource` da API. Isso cria conexões valiosas entre os benefícios e o contexto comercial no qual eles estão sendo usados.
Os tipos de recurso aceitos incluem:
+ **OPORTUNIDADE** - Vincule o aplicativo de benefícios a uma oportunidade específica do cliente em. Isso é particularmente útil para benefícios específicos de oportunidades, como financiamento de MAP ou créditos de POC vinculados ao engajamento do cliente.
+ **BENEFIT\_ALLOCATION - Vincule às alocações** de benefícios existentes, permitindo que os parceiros cadeiem benefícios ou demonstrem como os benefícios anteriores estão sendo aproveitados
A associação de recursos só pode ocorrer antes do envio. Depois que uma solicitação de benefício é enviada (o status muda para`IN_REVIEW`), nenhuma outra associação é permitida. Os parceiros podem associar até 10 recursos a cada solicitação de benefícios.
Para desassociar um recurso, os parceiros usam a ação da `DisassociateBenefitApplicationResource` API. Assim como a associação, a dissociação só pode ocorrer no `PENDING_SUBMISSION` status.
**Importante**
Os parceiros devem ter as permissões apropriadas para acessar o aplicativo de benefícios e ler o recurso específico que está sendo associado. A API valida essas permissões durante a operação de associação.
## Envio de solicitações de benefícios
Quando uma solicitação de benefícios está completa e pronta para AWS análise, os parceiros a enviam usando a ação da `SubmitBenefitApplication` API. O envio aciona uma transição de estado de `PENDING_SUBMISSION` para `IN_REVIEW` e inicia o fluxo de trabalho de aprovação específico do benefício.
Após o envio, a API realiza uma validação abrangente, incluindo:
+ **Validação de campos obrigatórios** - Garante que todos os campos obrigatórios nos detalhes do pedido de benefícios estejam presentes
+ **Validação do formato do campo** - Verifica se os valores do campo correspondem aos padrões e tipos de dados esperados
+ **Validação de regras de negócios** - aplica lógica e restrições de negócios específicas de benefícios
+ **Validação de recursos** - confirma que todos os recursos associados são válidos e acessíveis
+ **Validação de arquivo** - Verifica se o processamento de todos os anexos de arquivos foi concluído com êxito
Se a validação falhar, a API retornará um ValidationException com códigos de erro e mensagens detalhados indicando quais campos precisam ser corrigidos. Os parceiros devem resolver esses problemas usando `UpdateBenefitApplication` antes de tentar o envio novamente.
**Requisito de processamento de arquivos:** Os pedidos de benefícios não podem ser enviados se algum arquivo anexado ainda estiver em `PENDING` status. Os parceiros devem aguardar a conclusão do processamento do arquivo (o status muda para`SUCCEEDED`) antes de enviá-lo. Se os arquivos falharem no processamento (status`FAILED`), os parceiros devem fazer o upload das versões corrigidas.
Após o envio bem-sucedido:
+ O status do aplicativo muda para `IN_REVIEW`
+ A equipe do proprietário do benefício é notificada sobre o novo envio
+ Os parceiros não podem mais modificar os detalhes do aplicativo por meio de APIs de atualização padrão
+ O aplicativo entra em um fluxo de trabalho de aprovação definido que pode incluir estágios de aprovação comercial, aprovação técnica e aprovação financeira
Os parceiros podem acompanhar o progresso do envio recuperando a inscrição e monitorando o campo Estágio, que indica o estágio de aprovação atual (por exemplo, “Aprovação comercial”, “Aprovação técnica”, “Aprovação financeira”).
## Gerenciando inscrições enviadas
Depois de enviados, os parceiros têm opções limitadas para gerenciar os pedidos de benefícios, mas a API fornece ações específicas para cenários comuns.
### Relembrando aplicativos de benefícios
Se um parceiro descobrir um erro ou precisar fazer alterações após o envio, ele poderá cancelar o aplicativo usando a ação da `RecallBenefitApplication` API. O Recall faz a transição do aplicativo de volta ao `PENDING_SUBMISSION` status, permitindo atualizações e reenvio.
Ao cancelar uma inscrição, os parceiros devem fornecer:
+ **Identificador** - O ID ou ARN do pedido de benefício a ser retirado
+ **Motivo** - Uma explicação opcional para o recall (máximo de 1000 caracteres)
O campo do motivo permite uma melhor rastreabilidade e ajuda a AWS entender problemas comuns que levam a recalls, informando futuras melhorias no processo de solicitação de benefícios.
Após o recall, os parceiros podem usar `UpdateBenefitApplication` para fazer as alterações necessárias e reenviar usando `SubmitBenefitApplication` quando estiverem prontos.
**Importante**
Normalmente, o recall só está disponível durante os estágios iniciais de revisão. As inscrições que progrediram para estágios posteriores de aprovação ou foram aprovadas podem não ser elegíveis para recall.
### Alterando os pedidos de benefícios
Para pequenas correções após o envio, os parceiros podem usar a ação da `AmendBenefitApplication` API para atualizar campos específicos sem precisar recuperar todo o aplicativo. Isso é particularmente útil quando AWS os revisores solicitam esclarecimentos ou correções durante o processo de revisão.
As emendas usam uma Patch-style abordagem JSON em que os parceiros especificam:
+ **Path** - Uma expressão JSONPath identificando o campo a ser atualizado (por exemplo,) `$.CreditDisbursementDetails.AwsAccountIdForCredits`
+ **Valor** - O novo valor para o campo
+ **Operação** - A operação a ser executada (atualmente somente `REPLACE` é suportada)
Os parceiros podem enviar até 10 emendas em uma única chamada de API. Cada emenda deve incluir um número de revisão atualizado para um bloqueio otimista.
As emendas devem ser usadas para pequenas correções. Para mudanças substanciais, os parceiros devem usar `RecallBenefitApplication` para devolver o aplicativo ao status de rascunho para obter atualizações abrangentes.
### Cancelamento de solicitações de benefícios
Se um parceiro não precisar mais de um benefício ou quiser retirar sua inscrição, ele poderá cancelá-la usando a ação da `CancelBenefitApplication` API. O cancelamento faz a transição da solicitação para o `CANCELED` status, encerrando permanentemente o processo de inscrição.
Ao cancelar uma inscrição, os parceiros devem fornecer:
+ **Identificador** - O ID ou ARN do pedido de benefício a ser cancelado
+ **Motivo** - Uma explicação opcional para o cancelamento (máximo de 1000 caracteres)
Depois de cancelados, os aplicativos não podem ser reativados. Se o parceiro decidir posteriormente que precisa do benefício, ele deve criar um novo pedido de benefício.
Os motivos comuns para o cancelamento incluem:
+ A oportunidade do cliente foi perdida ou atrasada
+ As restrições de capacidade do parceiro foram alteradas
+ As prioridades de negócios mudaram
+ O benefício não é mais necessário para a finalidade pretendida
## Exibindo detalhes da solicitação de benefícios
Os parceiros podem recuperar informações completas sobre um aplicativo de benefícios usando a ação da `GetBenefitApplication` API. Isso fornece uma visão abrangente do aplicativo, incluindo:
**Metadados do aplicativo:**
+ Identificador exclusivo (ID) e nome de recurso da Amazon (ARN)
+ Identificador de benefício associado
+ Nome e descrição do aplicativo
+ Status atual (`PENDING_SUBMISSION``IN_REVIEW`,`ACTION_REQUIRED`,`APPROVED`,`REJECTED`, ou`CANCELED`)
+ Estágio de processamento atual
**Informações de status:**
+ Motivo do status - Human-readable explicação do status atual
+ Códigos de motivo de status - Códigos estruturados indicando problemas ou requisitos específicos (por exemplo, “Lista de verificação incompleta”, “Falta o plano do projeto”, “Falta o resultado do projeto”)
**Conteúdo do aplicativo:**
+ Documento JSON completo com detalhes do pedido de benefícios
+ Informações de contato do parceiro
+ Anexos de arquivo com status de processamento
+ Recursos associados (oportunidades ou alocações)
+ Tags de recursos
**Informações de auditoria:**
+ Carimbo de data e hora de criação
+ Carimbo de data/hora da última modificação
+ Número da revisão atual
Os códigos de motivo do status são particularmente valiosos quando um aplicativo está em `ACTION_REQUIRED` status. Esses códigos fornecem orientação específica e acionável sobre o que os parceiros precisam abordar para que a inscrição prossiga.
## Listando aplicativos de benefícios
Os parceiros podem visualizar todos os seus aplicativos de benefícios usando a ação `ListBenefitApplications` da API. Isso retorna uma lista paginada de resumos de aplicativos com poderosos recursos de filtragem.
Os parceiros podem filtrar os aplicativos por:
+ **Programa** - Visualize aplicativos para programas específicos (MAP, MDF, Sandbox, POC, etc.)
+ **Tipo de atendimento** - Filtrar por método de entrega (`CREDITS`,`CASH`,`ACCESS`, etc.)
+ **Identificador de benefícios** - Visualize os aplicativos para um benefício específico
+ **Status** - Filtrar por status do aplicativo (`PENDING_SUBMISSION``IN_REVIEW`,`APPROVED`,,`REJECTED`,`CANCELED`)
+ **Estágio** - Filtrar por estágio de aprovação (aprovação comercial, aprovação técnica, aprovação financeira)
+ **ARNs de recursos associados** - Encontre aplicativos vinculados a oportunidades ou alocações específicas
A resposta da lista inclui informações resumidas essenciais, como:
+ ID, ARN e nome do aplicativo
+ ID do benefício associado
+ Programas e tipos de atendimento
+ Status e estágio atuais
+ Carimbos de data e hora de criação e modificação
+ Recursos associados
+ Número da revisão atual
+ Campos selecionados dos detalhes do pedido de benefícios (conforme definido pelo proprietário do benefício)
Os parceiros podem configurar a classificação dos resultados usando o parâmetro Classificar, com opções para classificar por data de criação, status, programa ou identificador de benefícios em ordem crescente ou decrescente.
**Criação de painéis:** a `ListBenefitApplications` API foi projetada para oferecer suporte à criação de painéis de parceiros. Ao filtrar e classificar os aplicativos, os parceiros podem criar visualizações como:
+ Aplicativos que exigem ação (`ACTION_REQUIRED`status)
+ Inscrições enviadas recentemente (classificadas por data de criação, `IN_REVIEW` status)
+ Candidaturas aprovadas com alocação pendente (`APPROVED`status)
+ Aplicativos por programa (filtrados por programas específicos)