Gestionar ganancias mediante la API del Servicio de Ganancias

En este artículo se explica cómo acceder a los datos de ganancias a través de las API de ganancias en lugar de la interfaz de usuario del Centro de partners. Estas API proporcionan una manera programática de proporcionar la funcionalidad de la característica Exportar datos en el Centro de partners.

API disponibles

Consulta todas las API disponibles en Pagos de partners.

Prerrequisitos

• Tener una suscripción de trabajo en Azure Portal.
• Tener acceso a un explorador web.
• Puede realizar llamadas a la API REST, ya sea mediante programación o a través de software dedicado.

Registro de una aplicación con la plataforma de identidad de Microsoft

1. Siga las instrucciones para crear un registro de aplicaciones con la Plataforma de identidad de Microsoft.

2. Asigne a la aplicación los permisos delegados adecuados.

   1. En el registro de aplicaciones recién creado, vaya a Administrar → Permisos de API. Seleccione "Agregar un permiso".
   2. Seleccione la pestaña "API que usa mi organización", busque el AppId "4990cffe-04e8-4e8b-808a-1175604b879f" o por el nombre "Centro de desarrollo de Microsoft". En permisos, seleccione "user_impersonation". Seleccione "Agregar permisos".
      • Solución de problemas: si la búsqueda de la API del Centro de desarrollo no devuelve ningún resultado, es posible que tenga que crear las entidades de servicio necesarias para acceder manualmente a estas API. Se pueden crear con AzCLI:

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

        Después, los permisos de API deben estar disponibles para seleccionar en el cuadro de diálogo de búsqueda.
   3. Además, asegúrese de que la aplicación tiene un permiso "User.Read" en Microsoft Graph. Si no es así, agréguelo seleccionando Microsoft Graph en la pestaña API de Microsoft.
   4. Seleccione "Conceder consentimiento del administrador" para los tres permisos que obtuvo.
   5. Los permisos de la aplicación deben tener el siguiente aspecto (tenga en cuenta la marca verde junto a cada permiso):

3. Configure un URI de redirección para la plataforma web.

   1. Vaya a Administrar autenticación →. Seleccione "Agregar una plataforma".
   2. Seleccione "Web".
   3. En URI de redirección, escriba el URI que desea usar para la aplicación, por ejemplo https://localhost:3000. Anote este URI para más adelante. Presione "Configurar".

4. Genere un secreto de cliente para usarlo al obtener tokens de acceso.

   1. Vaya a Administrar → certificados y secretos. Vaya a la pestaña "Secretos de cliente", seleccione "Nuevo secreto de cliente".
   2. Escriba el nombre y la duración deseados.
   3. Seleccione Agregar secreto.
   4. Anote el valor en otro lugar. Asegúrese de mantenerlo en una ubicación segura, por ejemplo, un almacén de claves. Este secreto se usa al solicitar AccessToken y RefreshToken.

Obtención del token de acceso: cuentas habilitadas para MFA

Las APIs de beneficios requieren que se proporcione AccessToken como token portador para la autorización en la solicitud, con el prefijo Bearer <access-token> en el encabezado de Autorización. Para obtener este token, inicie sesión con su cuenta; sin embargo, los tokens de acceso son de corta duración. El inicio de sesión en una cuenta habilitada para MFA para generar un token cada vez que necesite llamar a la API no es práctico para los flujos de trabajo que implican automatización. Estos pasos le guiarán por el proceso para generar un RefreshToken. Tiene una duración más larga (aproximadamente 3 meses) y se puede usar para obtener AccessToken. Al almacenar un RefreshToken en una ubicación segura, puede usarlo para obtener mediante programación un AccessToken para llamar a la API de ganancias. Nota: RefreshToken solo se puede usar una vez, después de lo cual se vuelve obsoleto. En la respuesta, se devuelve un nuevo RefreshToken junto con AccessToken. Asegúrese de reemplazar el valor anterior de RefreshToken en el almacenamiento seguro cada vez que use RefreshToken.

1. Obtenga AuthCode a través del explorador. Actualmente, este proceso debe realizarse mediante la interfaz de usuario de un explorador web y no se puede realizar mediante programación.

   1. Siga la plantilla aquí para compilar una dirección URL que se usa para recuperar AuthCode.
      1. Use el identificador de inquilino y el identificador de cliente para la aplicación creada.
      2. Establezca el ámbito en https://api.partner.microsoft.com/.default.
      3. Establezca la dirección URL de redireccionamiento en la dirección URL de redireccionamiento configurada anteriormente. La plantilla de dirección URL es: 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. Vaya a la dirección URL compilada e inicie sesión con las credenciales de un usuario autorizado.
   3. Tras iniciar sesión correctamente, el explorador intenta abrir una dirección URL con el formato <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. Para el ejemplo de URI de redirección en un paso anterior, la dirección URL a la que se envía debe ser https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Guarde el código de autenticación devuelto en algún lugar seguro.
      • Dado que normalmente no hay ninguna aplicación escuchando en localhost:3000, el navegador proporciona un mensaje de error "no se puede conectar". Este error se espera, ya que solo es necesario copiar manualmente el valor de AuthCode del parámetro de consulta URL mostrado anteriormente.
      • En una solución prod, puede crear una aplicación que controle automáticamente esta parte del proceso de autenticación. Por ejemplo, podría ser un flujo de trabajo en el que el usuario va a una aplicación de una sola página (SPA). El usuario selecciona un botón de "inicio de sesión" que los lleva a la dirección URL construida anteriormente. Al iniciar sesión, la SPA extrae el valor de AuthCode y lo guarda en una bóveda. Después, la SPA usa AuthCode para obtener RefreshToken y AccessToken como se describe en los pasos siguientes.

2. Utilizar AuthCode para obtener RefreshToken y AccessToken inicial. Nota: RefreshToken expira cada 3 meses y necesita ser obtenido nuevamente y almacenado en algún almacén de claves.

   1. Compile una solicitud POST API siguiendo la plantilla proporcionada aquí.
      1. Use los mismos valores para el identificador de inquilino o cliente y la dirección URL de redirección.
      2. Establezca el ámbito en https://api.partner.microsoft.com/.default offline_access.
      3. Establezca el código a AuthCode obtenido en el paso anterior.
      4. Establezca client_secret en el secreto generado para la aplicación creada. A continuación, la dirección URL debe estructurarse de la siguiente manera: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. Más adelante, puede usar RefreshToken para obtener el nuevo AccessToken.

   1. Compile una solicitud POST API siguiendo la plantilla proporcionada aquí.
      1. Use los mismos valores para el identificador de inquilino o cliente y la dirección URL de redirección.
      2. Establecer el ámbito en https://api.partner.microsoft.com/.default
      3. Establezca refresh_token al RefreshToken obtenido en el paso anterior.
      4. Establezca client_secret en el secreto generado para la aplicación creada.

Obtener token de acceso: cuentas que no son de MFA

1. Obtenga AccessToken con la información del nuevo registro de la aplicación.
   1. Compile una solicitud POST API siguiendo la plantilla proporcionada aquí.
      1. Uso de los mismos valores para el identificador de inquilino o cliente
      2. Establecer el ámbito en https://api.partner.microsoft.com/.default
      3. Use el nombre de usuario y la contraseña de un usuario autorizado. La dirección URL debe estructurarse de la siguiente manera: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. La solicitud devuelve AccessToken y un nuevo RefreshToken. Asegúrese de actualizar el valor almacenado de RefreshToken, ya que ya no puede usar el valor anterior.

Ganancias de llamadas (antes historial de transacciones)/Pagos

• Use el AccessToken obtenido anteriormente en el encabezado Authorization con el prefijo Bearer <access-token> para crear nuevos informes de Ganancias (anteriormente TransactionHistory) o Pagos.

Contenido relacionado

• Uso del portal para crear una aplicación de Microsoft Entra y una entidad de servicio que puedan acceder a los recursos
• Registro de una aplicación en la plataforma de identidad de Microsoft
• Configuración de una aplicación cliente para acceder a una API web