Gerir lucros usando a API do Serviço de Lucros

Este artigo explica como pode aceder aos dados de lucros através das APIs de Lucros em vez da interface do Centro de Parceiros. Estas APIs fornecem uma forma programática de disponibilizar a funcionalidade Exportar dados no Centro de Parceiros.

APIs disponíveis

Veja todas as APIs disponíveis em Pagamentos aos Parceiros.

Pré-requisitos

• Tenho uma subscrição funcional no portal Azure.
• Ter acesso a um navegador web.
• Ser capaz de fazer chamadas REST API, seja programáticamente ou através de software dedicado.

Registar uma aplicação na plataforma de identidade da Microsoft

1. Siga as instruções para criar um Registo de Aplicações com a Microsoft Identity Platform.

2. Dá à aplicação permissões delegadas adequadas.

   1. No registo de aplicação recém-criada, vá a Gerenciar → Permissões da API. Selecione "Adicionar uma permissão."
   2. Selecione o separador "APIs que a minha organização usa", depois procure o AppId "4990cffe-04e8-4e8b-808a-1175604b879f" ou pelo nome "Microsoft Dev Center." Para permissões, selecione "user_impersonation." Selecione "Adicionar permissões."
      • Resolução de Problemas: Se a pesquisa pela API do Dev Center não trouxer resultados, pode ser necessário criar manualmente os principais de serviço necessários para aceder a estas APIs. Podem ser criados com AzCLI:

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

        Depois, as permissões da API devem estar disponíveis para seleção no diálogo de pesquisa.
   3. Além disso, certifica-te de que a tua aplicação tem uma permissão "User.Read" no Microsoft Graph. Se não estiver, adicione-o selecionando Microsoft Graph no separador das APIs da Microsoft.
   4. Selecione "Conceder consentimento de administrador" para as três permissões que obteve.
   5. As permissões da sua aplicação devem ser as seguintes (note o visto verde ao lado de cada permissão):

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

   1. Vá a Gerenciar → Autenticação. Selecione "Adicionar uma plataforma."
   2. Selecione "Web."
   3. Em URIs de Redirecionamento, introduza o URI que quer usar para a sua aplicação, por exemplo https://localhost:3000. Anota este URI para mais tarde. Carrega em "Configurar."

4. Gerar um segredo do cliente para usar ao obter tokens de acesso.

   1. Vá a Gerenciar → Certificados & Segredos. Vai ao separador "Segredos do cliente", seleciona "Novo segredo do cliente."
   2. Introduza o nome e a duração desejados.
   3. Selecionar Adicionar segredo.
   4. Anota o Valor noutro sítio. Certifique-se de o manter num local seguro, por exemplo, um cofre de chaves. Usa este 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 token portador de Autorização no pedido, com o prefixo Bearer <access-token> no cabeçalho de Autorização. Pode obter este token ao iniciar sessão com a sua conta; no entanto, os tokens de acesso são de curta duração. Iniciar sessão numa conta com MFA para gerar um token cada vez que precisas de ligar à API não é prático para fluxos de trabalho que envolvem automação. Estes passos guiam-no no processo para gerar um RefreshToken. Tem uma vida útil mais longa (cerca de 3 meses) e pode ser usado para obter o AccessToken. Ao armazenar um RefreshToken num local seguro, pode usá-lo para obter programaticamente um AccessToken para chamar a Earnings API. Nota: O RefreshToken só pode ser usado uma vez, após o que se torna obsoleto. Na resposta, é devolvido um novo RefreshToken juntamente com o AccessToken. Certifique-se de substituir o valor antigo do RefreshToken no seu armazenamento seguro sempre que usar um RefreshToken.

1. Obtenha o AuthCode através do navegador. Atualmente, este processo tem de ser feito usando a interface de um navegador web e não pode ser feito de forma programática.

   1. Siga o modelo aqui para construir uma URL que seja usada para recuperar o AuthCode.
      1. Use o ID do tenant e o ID do cliente para a aplicação criada.
      2. Defina o âmbito para https://api.partner.microsoft.com/.default.
      3. Defina o URL de redirecionamento para o URL de redirecionamento configurado 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. Vai ao URL integrado e inicia sessão usando as credenciais de um utilizador autorizado.
   3. Após iniciar sessão com sucesso, o seu navegador tenta abrir uma URL do formato <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. Para o exemplo do URI de redirecionamento numa etapa anterior, o URL para onde é enviado deve ser https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Guarda o AuthCode devolvido num local seguro.
      • Como normalmente não há nenhuma aplicação a escutar no localhost:3000, o navegador apresenta uma mensagem de erro "impossível conectar". Este erro é esperado, pois só precisamos copiar manualmente o valor do AuthCode do parâmetro de consulta do URL code mostrado anteriormente.
      • Numa solução de produção, pode-se criar uma aplicação que gere automaticamente esta parte do processo de autenticação. Por exemplo, pode ser um fluxo de trabalho onde o utilizador acede a uma aplicação de página única (SPA). O utilizador seleciona um botão de "iniciar sessão" que o leva ao URL construído anteriormente. Ao iniciar sessão, o SPA extrai o valor do AuthCode e guarda-o num repositório seguro. O SPA utiliza então o AuthCode para obter RefreshToken e AccessToken conforme descrito nos passos seguintes.

2. Utilize AuthCode para obter RefreshToken e o AccessToken inicial. Nota: O RefreshToken expira a cada 3 meses e precisa de ser recuperado e guardado num cofre de chaves.

   1. Construa um pedido de API POST seguindo o modelo fornecido aqui.
      1. Use os mesmos valores para o ID do inquilino/cliente e o URL de redirecionamento.
      2. Defina o âmbito para https://api.partner.microsoft.com/.default offline_access.
      3. Defina o código para o AuthCode obtido no passo anterior.
      4. Defina client_secret para o segredo gerado para a aplicação criada. A URL deve então ser estruturada da seguinte forma: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. Mais tarde, pode usar o RefreshToken para obter um novo AccessToken.

   1. Construa um pedido de API POST seguindo o modelo fornecido aqui.
      1. Use os mesmos valores para o ID do inquilino/cliente e o URL de redirecionamento.
      2. Definir o âmbito para https://api.partner.microsoft.com/.default
      3. Defina refresh_token para o RefreshToken obtido no passo anterior
      4. Defina client_secret para o segredo gerado para a aplicação criada.

Obter Token de Acesso - Contas Não-MFA

1. Obtenha o AccessToken usando a informação para o registo da nova aplicação.
   1. Construa um pedido de API POST seguindo o modelo fornecido aqui.
      1. Use os mesmos valores para o ID do inquilino/cliente
      2. Definir o âmbito para https://api.partner.microsoft.com/.default
      3. Use o nome de utilizador/palavra-passe de um utilizador autorizado O URL deve então ser estruturado da seguinte forma: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. O pedido devolve AccessToken e um novo RefreshToken. Certifica-te de atualizar o valor armazenado do RefreshToken, pois já não podes usar o valor antigo.

Rendimentos de Chamadas (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 de Pagamentos .

Conteúdo relacionado

• Use o portal para criar um aplicativo Microsoft Entra e uma entidade de serviço que possa acessar recursos
• Registar uma aplicação na plataforma de identidade da Microsoft
• Configure uma aplicação cliente para aceder a uma API web