Gerenciar ganhos usando a API do Serviço de Ganhos

Este artigo explica como você pode acessar dados de ganhos por meio das APIs de Ganhos em vez da interface do usuário do Partner Center. Essas APIs fornecem uma maneira programática de fornecer a capacidade do recurso Exportar dados no Partner Center.

APIs disponíveis

Consulte todas as APIs disponíveis em Pagamentos de Parceiros.

Pré-requisitos

• Tenha uma assinatura funcional no portal do Azure.
• Tenha acesso a um navegador da Web.
• Seja capaz de fazer chamadas à API REST, programaticamente ou por meio de software dedicado.

Registrar um aplicativo com a Microsoft Identity Platform

1. Siga as instruções para criar um Registro de Aplicativo com a Plataforma de Identidade da Microsoft.

2. Conceda ao aplicativo as permissões delegadas apropriadas.

   1. No registro de aplicativo recém-criado, vá para Gerenciar → Permissões de API. Selecione "Adicionar uma permissão".
   2. Selecione a guia "APIs que minha organização usa" e procure o AppId "4990cffe-04e8-4e8b-808a-1175604b879f" ou pelo nome "Centro de Desenvolvimento da Microsoft". Para obter permissões, selecione "user_impersonation". Selecione "Adicionar permissões".
      • Solução de problemas: se a pesquisa da API do Centro de Desenvolvimento não retornar resultados, talvez seja necessário criar as entidades de serviço necessárias para acessar essas APIs manualmente. Eles podem ser criados com a AzCLI:

        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        

        Posteriormente, as permissões de API devem estar disponíveis para serem selecionadas na caixa de diálogo de pesquisa.
   3. Além disso, verifique se seu aplicativo tem uma permissão "User.Read" no Microsoft Graph. Caso contrário, adicione-o selecionando o Microsoft Graph na guia APIs da Microsoft.
   4. Selecione "Conceder consentimento do administrador" para todas as três permissões obtidas.
   5. As permissões do aplicativo devem ter a seguinte aparência (observe o tique verde ao lado de cada permissão):

3. Configure um URI de redirecionamento para a plataforma Web.

   1. Vá para Gerenciar → Autenticação. Selecione "Adicionar uma plataforma".
   2. Selecione "Web".
   3. Em URIs de Redirecionamento, insira o URI que você deseja usar para seu aplicativo, por exemplo https://localhost:3000. Anote este URI para mais tarde. Pressione "Configurar".

4. Gere um segredo do cliente a ser usado ao obter tokens de acesso.

   1. Vá para Gerenciar → Certificados &segredos. Vá para a guia "Segredos do cliente", selecione "Novo segredo do cliente".
   2. Insira o nome e a duração desejados.
   3. Selecione Adicionar segredo.
   4. Anote o Valor em outro lugar. Certifique-se de mantê-lo em um local seguro, por exemplo, um cofre de chaves. Use esse segredo ao solicitar o AccessToken e o RefreshToken.

Obter token de acesso – contas habilitadas para MFA

As APIs de Ganhos exigem que um AccessToken seja fornecido como o token de autenticação tipo 'bearer' na solicitação, com o prefixo Bearer <access-token> no cabeçalho de autorização. Você pode obter esse token fazendo logon com sua conta; no entanto, os tokens de acesso são de curta duração. Fazer logon em uma conta habilitada para MFA para gerar um token sempre que você precisar chamar a API não é prático para fluxos de trabalho que envolvem automação. Estas etapas orientam você pelo processo para gerar um RefreshToken. Ele tem um tempo de vida mais longo (cerca de 3 meses) e pode ser usado para obter o AccessToken. Armazenando um RefreshToken em um local seguro, você pode usá-lo para obter programaticamente um AccessToken para chamar a API de Ganhos. Observação: RefreshToken só pode ser usado uma vez, após a qual ele se torna obsoleto. Na resposta, um novo RefreshToken é retornado junto com o AccessToken. Certifique-se de substituir o valor antigo do RefreshToken em seu armazenamento seguro, sempre que você usar um RefreshToken.

1. Obtenha o AuthCode por meio do navegador. Atualmente, esse processo precisa ser feito usando a interface do usuário de um navegador da Web e não pode ser feito programaticamente.

   1. Siga o modelo aqui para criar uma URL usada para recuperar o AuthCode.
      1. Use a ID do locatário e a ID do cliente para o aplicativo criado.
      2. Definir o escopo como https://api.partner.microsoft.com/.default.
      3. Defina a URL de redirecionamento para a URL de redirecionamento configurada anteriormente. O modelo de URL é: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
   2. Vá para a URL criada e entre usando as credenciais de um usuário autorizado.
   3. Após a entrada bem-sucedida, o navegador tenta abrir uma URL do formato <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. Para o exemplo de URI de redirecionamento em uma etapa anterior, a URL para a qual você é enviado deve ser https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Salve o AuthCode retornado em algum lugar seguro.
      • Como geralmente não há nenhum aplicativo escutando localhost:3000, o navegador fornece uma mensagem de erro "não é possível se conectar". Esse erro é esperado, pois só precisamos copiar manualmente o valor do AuthCode do code parâmetro de consulta de URL mostrado anteriormente.
      • Em uma solução prod, pode-se criar um aplicativo que lida automaticamente com essa parte do processo de autenticação. Por exemplo, pode ser um fluxo de trabalho em que o usuário vai para um SPA (aplicativo de página única). O usuário seleciona um botão "entrar" que os leva para a URL construída anteriormente. Após o login, o SPA extrai o valor do AuthCode e o salva em um cofre. Em seguida, o SPA usa o AuthCode para obter RefreshToken e AccessToken, conforme descrito nas próximas etapas.

2. Use AuthCode para obter RefreshToken e o AccessToken inicial. Observação: RefreshToken expira a cada 3 meses e precisa ser novamente obtido e armazenado em algum cofre de segurança.

   1. Crie uma solicitação de API POST seguindo o modelo fornecido aqui.
      1. Use os mesmos valores para ID de locatário/cliente e URL de redirecionamento.
      2. Definir o escopo como https://api.partner.microsoft.com/.default offline_access.
      3. Defina o código para o AuthCode obtido na etapa anterior.
      4. Defina client_secret para o segredo gerado para o aplicativo criado. Em seguida, a URL deve ser estruturada da seguinte maneira: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. Posteriormente, você pode usar RefreshToken para obter o novo AccessToken.

   1. Crie uma solicitação de API POST seguindo o modelo fornecido aqui.
      1. Use os mesmos valores para ID de locatário/cliente e URL de redirecionamento.
      2. Definir o escopo como https://api.partner.microsoft.com/.default
      3. Definir refresh_token para o RefreshToken obtido na etapa anterior
      4. Defina client_secret para o segredo gerado para o aplicativo criado.

Obter token de acesso – contas não MFA

1. Obtenha o AccessToken usando as informações para o novo registro de aplicativo.
   1. Crie uma solicitação de API POST seguindo o modelo fornecido aqui.
      1. Usar os mesmos valores para iD de locatário/cliente
      2. Definir o escopo como https://api.partner.microsoft.com/.default
      3. Use o nome de usuário/senha para um usuário autorizado A URL deve ser estruturada da seguinte maneira: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. A solicitação retorna o AccessToken e um novo RefreshToken. Atualize o valor armazenado para o RefreshToken, pois você não pode mais usar o valor antigo.

Ganhos de Transação (anteriormente histórico de transações)/Pagamentos

• Use o AccessToken obtido anteriormente no cabeçalho de autorização com o prefixo Bearer <access-token> para criar novos relatórios de Rendimentos (anteriormente histórico de transações) ou Pagamentos.

Conteúdo relacionado

• Use o portal para criar um aplicativo Microsoft Entra e um principal de serviço que possa acessar recursos
• Registrar um aplicativo na plataforma de identidade da Microsoft
• Configurar um aplicativo cliente para acessar uma API Web