Integrar las API de protección de compras

  • Artículo

En este artículo se explica cómo integrar las interfaces de programación de aplicaciones (API) en tiempo real de Microsoft Dynamics 365 Fraud Protection.

Para aprovechar la serie completa de las características de Fraud Protection, envíe los datos de transacciones a las API en tiempo real de Fraud Protection. En la experiencia de evaluación, enviar datos de transacciones le permite analizar los resultados de usar Fraud Protection. En la experiencia Protección, también puede cumplir decisiones basadas en las reglas que ha configurado.

Según cómo user Fraud Protection, puede hacer uso de varios conjuntos de las siguientes API de protección de compra:

  • Comprar
  • PurchaseStatus
  • BankEvent
  • Contracargo
  • Devolución
  • UpdateAccount
  • Etiqueta

Fases de integración de API

La integración de las API de protección de compras se produce en tres fases:

  1. Crear aplicaciones Microsoft Entra a través de Fraud Protection.
  2. Generar un token de acceso.
  3. Llamar a las API.

Iniciar sesión

Importante

Debe ser administrador global en el inquilino de Azure para completar el inicio de sesión inicial.

Visite los siguientes portales para cada entorno que pretenda utilizar. Inicie sesión y acepte los términos y condiciones si se le solicita que lo haga.

Crear aplicaciones Microsoft Entra

Importante

Tiene que ser administrador de aplicaciones, administrador de aplicaciones en la nube o administrador global en el inquilino de Azure para completar este paso.

Para adquirir los tokens necesarios para llamar a las API, debe configurar y usar aplicaciones Microsoft Entra como se describe en esta sección.

Configurar aplicaciones de Microsoft Entra

Para configurar aplicaciones Microsoft Entra, siga estos pasos.

  1. En el portal de Fraud Protection, en el panel de navegación izquierdo, seleccione Integración > Crear aplicación Microsoft Entra > Configurar ahora.

  2. Complete la página para crear su aplicación. Le recomendamos que cree una aplicación Microsoft Entra para cada entorno que quiera integrar con Fraud Protection.

  3. Especifique o seleccione los valores para los campos requeridos:

    • Nombre para mostrar de la aplicación - Proporcione a su aplicación un nombre descriptivo. La longitud máxima es de 93 caracteres.
    • Método de autenticación - Seleccione si quiere autenticar mediante certificado o secreto (contraseña).

  4. Si seleccionó el método de autenticación de certificado, siga estos pasos:

    1. Seleccione Elija el archivo para cargar la clave pública. (La clave privada correspondiente es necesaria para adquirir tokens).
    2. Seleccione Secreto para generar automáticamente una contraseña después de que se haya creado la aplicación.

  5. Cuando haya terminado de establecer los campos necesarios, seleccione Crear aplicación. La página de confirmación resume el nombre de la aplicación, ID, y la huella digital o el secreto del certificado, en función del método de autenticación que ha seleccionado.

Importante

Guarde la información del secreto o la huella digital dle certificado para referencias futuras. El secreto se mostrará una sola vez.

Crear otra aplicación

Para crear otra aplicación, seleccione Crear otra aplicación. Puede crear tantas aplicaciones como necesite para ejecutar llamadas API en cada uno de sus entornos.

Administrar aplicaciones Microsoft Entra existentes

Después de crear las aplicaciones de Microsoft Entra, puede administrarlas a través de [Azure portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Para más información, vea Cómo y por qué se agregan aplicaciones a Microsoft Entra ID.

Generar un símbolo de acceso

Para integrar de forma segura sus sistemas con Fraud Protection, obtenga un token de Microsoft Entra y proporciónelo en el encabezado de cada llamada a la API.

Nota

Los tokens de acceso tienen una vida útil limitada de 60 minutos. Se recomienda almacenarlo en caché y reusar un token hasta que esté cerca de expirar. Entonces puede obtener un nuevo token de acceso.

La siguiente información es necesaria para obtener un token.

Ids e información necesarios

  • URI de entorno: los URI de su entorno de espacio aislado o de producción aparecen en la pestaña Configuración de la página Administración de API en el portal de Fraud Protection.
  • Identificador del directorio (inquilino) - Este identificador es el identificador único global (GUID) para el dominio de un inquilino en Azure. Aparece en Azure Portal y en la pestaña Configuración de la página Administración de API en el portal de Fraud Protection.
  • ID de la aplicación (cliente) - Este ID identifica la aplicación de Microsoft Entra que creó para llamar a las API. Obtenga el identificador en la página de confirmación de API en tiempo real o encuéntrelo más adelante en el Azure Portal en Registros de aplicación. Habrá un identificador por cada aplicación que haya creado.
  • Huella digital o secreto del certificado - Obtenga la huella digital o el secreto de la página de confirmación de API en tiempo real.
  • ID de instancia – Este ID es el GUID de su entorno en Fraud Protection. Aparece en el icono Integración, en el panel de información de Fraud Protection.

Exjemplos: los ejemplos de código muestran cómo adquirir un token mediante su certificado o secreto

Los ejemplos de código de C# siguientes ofrecen ejemplos de cómo adquirir un token con su certificado o secreto. Reemplace los marcadores de posición con su información específica. Para estos dos ejemplos de C #, deberá importar el siguiente paquete NuGet Microsoft.Identity.Client.

Para obtener ejemplos en otros idiomas, consulte https://aka.ms/aaddev.

Obtenga un token de acceso usando una ID de aplicación y una clave de certificado privado

/// <summary>
/// Gets an access token using an app ID and private certificate key.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="certPath">File path to the certificate file (pfx) used to authenticate your application to Microsoft Entra ID</param>
/// <param name="certPassword">Password to access to the certificate file's private key</param>
public async Task<string> AcquireTokenWithCertificate(string tenantId, string clientId, string certPath, string certPassword)
{
    var certificate = new X509Certificate2(certPath, certPassword);

    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithCertificate(certificate)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

Obtenga un token de acceso usando una ID de aplicación y secreto

/// <summary>
/// Gets an access token using an app ID and secret.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="clientSecret">The secret (password) used to authenticate the client (application) ID</param>
public async Task<string> AcquireTokenWithSecret(string tenantId, string clientId, string clientSecret)

{
    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithClientSecret(clientSecret)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

El objeto AuthenticationResult en cada caso contiene el propio AccessToken y una propiedad ExpiresOn que indica cuándo el token dejará de ser válido.

  • Solicitud POST para:

    • https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token

  • Encabezados:

    • Content-type: application/x-www-form-urlencoded

  • Cuerpo (valor-clave):

    • grant_type: client_credentials
    • client_id: {Su ID de cliente del paso anterior}
    • client_secret: {Su secreto del paso anterior}
    • recurso: https://api.dfp.microsoft.com (para int, https://api.dfp.microsoft-int.com)

  • Respuesta:

    • Usa el valor de access_token de la respuesta para el siguiente paso.

Para obtener más información, consulte la siguiente documentación de Azure:

Llamar a las API

Para llamar a las API, siga estos pasos.

  1. Pase los encabezados HTTP necesarios siguientes en cada solicitud.

    Nombre de encabezado Valor de encabezado
    Autorización

    Utilice el siguiente formato para este encabezado. (Reemplace accesstoken con el valor real del token devuelto por Microsoft Entra ID).

    Portador de accesstoken
    x-ms-correlation-id Envíe un nuevo valor GUID en cada conjunto de llamadas API que se hacen juntas.
    x-ms-dfpenvid Envíe el valor GUID de su id. de instancia.

  2. Genere una carga basada en eventos. Complete los datos de evento con información relevante del sistema. Para la documentación sobre todos los eventos admitidos, consulte API de Dynamics 365 Fraud Protection.

  3. Combine el encabezado (que incluye el token de acceso) y la carga, y después envíelos a su extremo de Fraud Protection.

    • Solicitud POST para:

      • <Base URL>/v1.0/merchantservices/events/purchase

    • Encabezados:

      • x-ms-correlation-id : {Un GUID, que debe ser único por solicitud}
      • content-type: application/json
      • Autorización : {El token del paso anterior}
      • x-ms-dfpenvid: {El id. de entorno del entorno de destino}

    • Cuerpo:

      • Obtenga el cuerpo de solicitud de protección de cuenta de muestra del archivo compartido página de Swagger.

Nota

Si crea un nuevo entorno, incluya el id. del entorno en el encabezado de la API durante la integración, para que las transacciones se puedan enrutar correctamente.

Las siguientes opciones son aceptables para x-ms-dfpenvid en la llamada a la API y el comportamiento es idéntico.

  • Utilice el ID de entorno para el entorno al que está llamando. El ID aparece en la página Integración en el campo ID del entorno.
  • Use la palmadita completa del ID de la API del cliente desde la raíz hasta el entorno secundario al que está llamando usando la barra inclinada (/) como divisor. Por ejemplo, /primary/XYZ.
  • Use la ruta completa del ID del entorno o el ID de API del cliente desde la raíz hasta el entorno secundario al que está llamando usando la barra inclinada (/) como divisor. Por ejemplo, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Para especificar el ID de la API del cliente al crear un entorno, consulte el artículo Administrar entornos.

Prácticas recomendadas

  • Cada token de Microsoft Entra sigue siendo válido durante 60 minutos. Recomendamos que lo almacene en caché por un período más corto y lo reutilice.
  • Asegúrese de que HttpClient tenga conexiones permanentes.
  • Pase siempre el encabezado x-ms-dfpenvid y asegúrese de que apunte al entorno del comerciante en cuyo nombre desea enviar transacciones.
  • Guarda el secreto en una tienda secreta.
  • Pasa siempre el encabezado x-ms-correlación-id para futuras sesiones de depuración con Fraud Protection.
  • Asegúrese de que el encabezado x-ms-correlación-id es único para cada transacción que se envía a Fraud Protection. 

Ver la aplicación de ejemplo

Como referencia adicional, puede ver la aplicación mercantil de ejemplo y la documentación del desarrollador correspondiente. La aplicación de ejemplo proporciona un ejemplo de cómo llamar a las API de Fraud Protection, incluidos eventos de API como el envío de actualizaciones, de reembolsos, y de retrocargos de la cuenta del cliente en tiempo real. La documentación de la aplicación de ejemplo está vinculada al código de ejemplo real siempre que este tipo de enlaces sea posible. De lo contrario, los ejemplos de código existen directamente en la documentación.

Para obtener instrucciones sobre la configuración del sitio de ejemplo para su uso, vea configurar el sitio de ejemplo.