Integrare le API di protezione di acquisti

Articolo
05/20/2024

In questo articolo viene illustrato come integrare le API (Application Programming Interface) in tempo reale in Microsoft Dynamics 365 Fraud Protection.

Per utilizzare la gamma completa delle funzionalità di Fraud Protection, devi inviare i dati sulle transazioni alle API Fraud Protection in tempo reale. Nell'esperienza di valutazione, l'invio dei dati sulla transazione consente di analizzare i risultati dell'uso di Fraud Protection. Nell'esperienza di protezione, è possibile inoltre rispettare le decisioni basate sulle regole configurate.

A seconda di come utilizzi Fraud Protection, è consigliabile utilizzare set diversi delle seguenti API di protezione degli acquisti:

Acquisto
PurchaseStatus
BankEvent
Rifiuto di addebito
Rimborso
UpdateAccount
Etichetta

Fasi di integrazione delle API

L'integrazione delle API di protezione degli acquisti avviene in tre fasi:

Creare applicazioni Microsoft Entra tramite Fraud Protection.
Genera un token di accesso.
Chiama le API.

Importante

È necessario essere un amministratore globale nel tenant Azure per completare l'accesso iniziale.

Visita i seguenti portali per ogni ambiente che intendi utilizzare. Accedi e accetta le condizioni se richiesto.

Ambiente sandbox
Ambiente di produzione (è possibile che tu abbia già completato tale passaggio in produzione durante l'accesso.)

Creare applicazioni Microsoft Entra

Importante

Devi essere un amministratore di applicazioni, amministratore di applicazioni cloud o amministratore globale nel tenant di Azure per completare questo passaggio.

Per acquisire i token necessari per chiamare le API, è necessario configurare e usare le applicazioni Microsoft Entra come descritto in questa sezione.

Configurare le applicazioni Microsoft Entra

Per configurare le applicazioni Microsoft Entra, seguire questa procedura.

Nel riquadro di spostamento sinistro del portale di Protezione dalle frodi selezionare Integrazione > Crea applicazione Microsoft Entra Application > Setup now.
Completa la pagina per creare l'app. È consigliabile creare un'applicazione Microsoft Entra per ogni ambiente che si vuole integrare con Fraud Protection.
Immetti o seleziona i valori nei seguenti campi obbligatori:
- Nome visualizzato dell'applicazione: fornisci all'applicazione un nome descrittivo. La lunghezza massima consentita è di 93 caratteri.
- Metodo di autenticazione: scegli se eseguire l'autenticazione tramite un certificato o un segreto (password).
Se hai selezionato il metodo di autenticazione del certificato, procedi nel seguente modo:
1. Seleziona Scegli file per caricare la chiave pubblica. La chiave privata corrispondente è necessaria quando acquisisci token.
2. Seleziona Segreto per generare automaticamente una password dopo la creazione dell'applicazione.
Al termine dell'impostazione dei campi necessari, seleziona Crea applicazione. Nella pagina di conferma verrà riepilogato il nome dell'app, l'ID e l'identificazione personale del certificato o il segreto, a seconda del metodo di autenticazione selezionato.

Importante

Salva le informazioni relative al segreto o identificazione personale del certificato per riferimento futuro. Il segreto verrà visualizzato una sola volta.

Crea un'altra applicazione

Per creare un'altra applicazione, seleziona Crea un'altra applicazione. È possibile creare il numero di app necessario per eseguire le chiamate API in ognuno dei tuoi ambienti.

Gestire le applicazioni Microsoft Entra esistenti

Dopo aver creato le app Microsoft Entra, è possibile gestirle tramite [portale di Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Per altre informazioni, vedere Come e perché le applicazioni vengono aggiunte a Microsoft Entra ID.

Generare un token di accesso

Per integrare in modo sicuro i sistemi con Fraud Protection, ottenere un token Microsoft Entra e specificarlo nell'intestazione di ogni chiamata API.

Nota

I token di accesso hanno una durata limitata di 60 minuti. È consigliabile memorizzare nella cache e riutilizzare un token fino a che non viene chiuso perché scaduto. È quindi possibile ottenere un nuovo token di accesso.

Le seguenti informazioni sono necessarie per ottenere un token.

ID e informazioni necessarie

URI ambiente: gli URI dell'ambiente sandbox o di produzione appaiono nella scheda Configurazione della pagina Gestione API nel portale Fraud Protection.
ID directory (tenant): questo ID è l'identificatore univoco globale (GUID) del dominio di un tenant in Azure. Viene visualizzato nel portale di Azure e nella scheda Configurazione della pagina Gestione API nel portale Fraud Protection.
ID applicazione (client): questo ID identifica l'app Microsoft Entra creata per chiamare le API. Ottieni l'ID dalla pagina di conferma API in tempo reale o puoi trovarlo in seguito nel portale di Azure in Registrazioni app. Ci sarà un ID per ogni app creata.
Identificazione personale certificato o segreto: ottieni l'identificazione personale certificato o il segreto dalla pagina di conferma API in tempo reale.
ID istanza: questo ID è il GUID del tuo ambiente in Fraud Protection. Appare nel riquadro Integrazione nel dashboard di Fraud Protection.

Esempi: codici di esempio che mostrano come acquisire un token utilizzando un certificato o un segreto

Negli esempi di codice C# seguenti sono esempi di acquisizione di un token con certificato o segreto. Sostituire i segnaposto con le informazioni specifiche. Per entrambi questi esempi in C#, sarà necessario importare il pacchetto NuGet Microsoft.Identity.Client.

Per esempi in altri linguaggi, vedi https://aka.ms/aaddev.

Ottenere un token di accesso tramite un ID app e una chiave di certificato privata

/// <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;
    }
}

Ottenere un token di accesso tramite un ID app e un segreto

/// <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;
    }
}

L'oggetto AuthenticationResult in ogni caso contiene lo stesso valore AccessToken e una proprietà ExpiresOn che indica quando il token non sarà più valido.

Richiesta POST a:
- https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
Intestazioni:
- Content-type: application/x-www-form-urlencoded
Corpo (chiave-valore):
- grant_type: client_credentials
- client_id: {il tuo ID client dal passaggio precedente}
- client_secret: {il tuo segreto dal passaggio precedente}
- resource : https://api.dfp.microsoft.com (per int, https://api.dfp.microsoft-int.com)
Risposta:
- Usa il valore di access_token dalla risposta per il passaggio successivo.

Per ulteriori informazioni, vedi la seguente documentazione di Azure:

Chiamare le API

Per chiamare le API, eseguire la procedura seguente.

Passare le seguenti intestazioni HTTP obbligatorie per ogni richiesta.

Nome intestazione	Valore intestazione
Autorizzazione	Utilizzail seguente formato per l'intestazione. Sostituire accesstoken con il valore effettivo del token restituito da Microsoft Entra ID. Token di connessione accesstoken
x-ms-correlation-id	Invia un nuovo valore GUID in ogni set di chiamate API effettuate insieme.
x-ms-dfpenvid	Invia il valore GUID del tuo ID istanza.

Nome intestazione

Valore intestazione

Autorizzazione

Utilizzail seguente formato per l'intestazione. Sostituire accesstoken con il valore effettivo del token restituito da Microsoft Entra ID.

Token di connessione accesstoken

x-ms-correlation-id

Invia un nuovo valore GUID in ogni set di chiamate API effettuate insieme.

x-ms-dfpenvid

Invia il valore GUID del tuo ID istanza.

Genera un payload basato su evento. Compila i dati evento con le informazioni pertinenti dal sistema. Per la documentazione sugli eventi supportati, vedere API di Dynamics 365 Fraud Protection
Combina l'intestazione (che include il token di accesso) e il payload e quindi inviali all'endpoint di Fraud Protection
- Richiesta POST a:
  - <Base URL>/v1.0/merchantservices/events/purchase
- Intestazioni:
  - x-ms-correlation-id: {il GUID deve essere univoco per richiesta}
  - content-type: application/json
  - Autorizzazione: {il token del passaggio precedente}
  - x-ms-dfpenvid: {l'ID ambiente dell'ambiente di destinazione}
- Corpo:
  - Ottieni il corpo della richiesta di protezione dell'account di esempio dalla pagina Swagger condivisa.

Nota

Se crei un nuovo ambiente, includi l'ID ambiente nell'intestazione dell'API durante l'integrazione, in modo che le transazioni possano essere instradate correttamente.

Le seguenti opzioni sono accettabili per x-ms-dfpenvid nella chiamata API e il comportamento è identico.

Utilizza l'ID ambiente per l'ambiente che stai chiamando. L'ID è elencato nella pagina Integrazione nel campo ID ambiente.
Utilizza il percorso completo dell'ID API cliente dalla radice all'ambiente figlio che stai chiamando utilizzando la barra (/) come divisore. Ad esempio, /primary/XYZ.
Utilizza il percorso completo dell'ID ambiente o dell'ID API cliente dalla radice all'ambiente figlio che stai chiamando utilizzando la barra (/) come divisore. Ad esempio, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Per specificare l'ID API cliente quando crei un ambiente, consulta l'articolo Gestire ambienti.

Procedure consigliate

Ogni token di Microsoft Entra rimane valido per 60 minuti. È consigliabile memorizzarlo nella cache per un periodo più breve e riutilizzarlo.
Verifica che il tuo HttpClient abbia connessioni keep-alive.
Trasmetti sempre l'intestazione x-ms-dfpenvid e verifica che punti all'ambiente del commerciante fornitore per conto del quale desideri inviare le transazioni.
Archivia il segreto in un archivio di segreti.
Trasmetti sempre l'intestazione x-ms-correlation-id per future sessioni di debug con Fraud Protection.
Verifica che l'intestazione x-ms-correlation-id sia univoca per ogni transazione inviata a Fraud Protection.

Visualizzare l'app di esempio

Per un ulteriore riferimento, puoi visualizzare l'app fornitore di esempio e la documentazione per sviluppatori correlata. L'app di esempio fornisce un esempio di come chiamare le API di Fraud Protection, inclusi gli eventi API come l'invio degli aggiornamenti dell'account cliente, i rimborsi e i chargeback in tempo reale. La Documentazione per l'app di esempio è collegata al codice di esempio effettivo ogni volta che tali collegamenti sono possibili. In caso contrario, esempi di codice esistono direttamente nella documentazione.

Per indicazioni su come configurare il di esempio per il tuo utilizzo, vedi Configurare il sito di esempio.

Condividi tramite

Integrare le API di protezione di acquisti

Fasi di integrazione delle API

Creare applicazioni Microsoft Entra

Configurare le applicazioni Microsoft Entra

Crea un'altra applicazione

Gestire le applicazioni Microsoft Entra esistenti

Generare un token di accesso

ID e informazioni necessarie

Esempi: codici di esempio che mostrano come acquisire un token utilizzando un certificato o un segreto

Ottenere un token di accesso tramite un ID app e una chiave di certificato privata

Ottenere un token di accesso tramite un ID app e un segreto

Chiamare le API

Procedure consigliate

Visualizzare l'app di esempio

Commenti e suggerimenti

Risorse aggiuntive