Condividi tramite

Integrare le API di protezione degli acquisti

Importante

A partire dal 3 febbraio 2025, Dynamics 365 Fraud Protection non è più disponibile per l'acquisto. Il supporto per la protezione delle frodi terminerà il 3 febbraio 2026. Per altre informazioni, vedere l'articolo Fine del supporto per Dynamics 365 Fraud Protection.

Questo articolo illustra come integrare le API (Application Programming Interface) in tempo reale in Microsoft Dynamics 365 Fraud Protection.

Per sfruttare la suite completa di funzionalità di Protezione dalle frodi, è necessario inviare i dati delle transazioni alle API di protezione dalle frodi in tempo reale. Nell'esperienza di valutazione l'invio dei dati delle transazioni consente di analizzare i risultati dell'uso di Protezione dalle frodi. Nell'esperienza di protezione è anche possibile rispettare le decisioni in base alle regole configurate.

A seconda del modo in cui si usa La protezione dalle frodi, è possibile usare diversi set di API di protezione degli acquisti seguenti:

  • Acquisto
  • PurchaseStatus
  • Evento della Banca
  • Rifiuto di addebito
  • Rimborso
  • AggiornaAccount
  • Etichetta

Fasi di integrazione dell'API

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

  1. Creare applicazioni Microsoft Entra tramite Fraud Protection.
  2. Genera un token di accesso.
  3. Chiamare le API.

Accedere

Importante

Per completare l'accesso iniziale, è necessario essere un amministratore globale nel tenant di Azure.

Visitare i portali seguenti per ogni ambiente che si intende usare. Effettua l'accesso e accetta i termini e le condizioni se ti viene richiesto di farlo.

Creare applicazioni Microsoft Entra

Importante

Per completare questo passaggio, è necessario essere un amministratore dell'applicazione, un amministratore di applicazioni cloud o un amministratore globale nel tenant di Azure.

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.

  1. Nel riquadro di spostamento sinistro del portale di Protezione dalle frodi selezionare Integrazione > Crea applicazione Microsoft Entra Application > Setup now.

  2. Completare la pagina per creare l'app. È consigliabile creare un'applicazione Microsoft Entra per ogni ambiente che si vuole integrare con Fraud Protection.

  3. Immettere o selezionare i valori per i campi obbligatori seguenti:

    • Nome visualizzato dell'applicazione : assegnare all'applicazione un nome descrittivo. La lunghezza massima consentita è di 93 caratteri.
    • Metodo di autenticazione: selezionare se si vuole eseguire l'autenticazione tramite un certificato o un segreto (password).

  4. Se è stato selezionato il metodo di autenticazione del certificato, seguire questa procedura:

    1. Selezionare Scegli file per caricare la chiave pubblica. La chiave privata corrispondente è necessaria quando si acquisiscono i token.
    2. Selezionare Segreto per generare automaticamente una password dopo la creazione dell'applicazione.

  5. Al termine dell'impostazione dei campi obbligatori, selezionare Crea applicazione. La pagina di conferma riepiloga il nome, l'ID e l'identificazione personale o il segreto del certificato dell'app, a seconda del metodo di autenticazione selezionato.

Importante

Salva le informazioni sull'impronta digitale del segreto o del certificato per uso futuro. Il segreto verrà visualizzato una sola volta.

Creare un'altra applicazione

Per creare un'altra applicazione, selezionare Crea un'altra applicazione. È possibile creare tutte le app necessarie per eseguire chiamate API in ognuno degli ambienti.

Gestire le applicazioni Microsoft Entra esistenti

Dopo aver creato le app Microsoft Entra, è possibile gestirle tramite il [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.

Annotazioni

I token di accesso hanno una durata limitata di 60 minuti. È consigliabile memorizzare nella cache e riutilizzare un token fino alla scadenza. È quindi possibile ottenere un nuovo token di accesso.

Per ottenere un token sono necessarie le informazioni seguenti.

ID e informazioni necessarie

  • URI dell'ambiente : gli URI per l'ambiente sandbox o di produzione vengono visualizzati nella scheda Configurazione della pagina Gestione API nel portale di Protezione dalle frodi.
  • ID directory (tenant): ID 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 di Protezione dalle frodi.
  • ID applicazione (client): questo ID identifica l'app Microsoft Entra creata per chiamare le API. Ottenere l'ID dalla pagina di conferma delle API in tempo reale o trovarla più avanti in Registrazioni app nel portale di Azure. Ci sarà un ID per ogni app creata.
  • Impronta digitale o segreto del certificato – ottenere l'impronta digitale o il segreto dalla pagina di conferma delle API in tempo reale.
  • ID istanza : questo ID è il GUID dell'ambiente in Protezione dalle frodi. Appare nel riquadro Integrazione nel dashboard di Fraud Protection.

Esempi: esempi di codice che illustrano come acquisire un token usando il certificato o il segreto

Gli esempi di codice C# seguenti forniscono esempi di acquisizione di un token con il certificato o il segreto. Sostituite i segnaposto con le informazioni specifiche. Per entrambi gli esempi C#, è necessario importare il pacchetto NuGet Microsoft.Identity.Client.

Per esempi in altre lingue, vedere https://aka.ms/aaddev.

Ottenere un token di accesso usando un ID app e una chiave del certificato privato

/// <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 usando 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 il valore AccessToken e una proprietà ExpiresOn che indica quando il token diventa non valido.

  • Invio di una richiesta POST a:

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

  • Intestazioni:

    • Tipo di contenuto: application/x-www-form-urlencoded

  • Corpo (chiave-valore):

    • grant_type: client_credentials
    • client_id: {ID client del passaggio precedente}
    • client_secret: {Segreto del passaggio precedente}
    • resource: https://api.dfp.microsoft.com (per int, https://api.dfp.microsoft-int.com)

  • Risposta:

    • Usare il valore di access_token dalla risposta per il passaggio successivo.

Per altre informazioni, vedere la documentazione di Azure seguente:

Chiamare le API

Per chiamare le API, seguire questa procedura.

  1. Passare le seguenti intestazioni HTTP obbligatorie per ogni richiesta.

    Nome dell'intestazione Valore intestazione
    Autorizzazione

    Utilizzare il seguente formato per questa intestazione. Sostituire accesstoken con il valore effettivo del token restituito da Microsoft Entra ID.

    Bearer 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 dell'ID istanza.

  2. Genera un payload basato su evento. Compila i dati evento con le informazioni pertinenti dal sistema. Per la documentazione su tutti gli eventi supportati, vedere l'API Dynamics 365 Fraud Protection.

  3. Combina l'intestazione (che include il token di accesso) e il payload e quindi inviali all'endpoint di Fraud Protection

    • Invio di una richiesta POST a:

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

    • Intestazioni:

      • x-ms-correlation-id: {UN GUID, che deve essere univoco per ogni richiesta}
      • content-type: application/json
      • Autorizzazione: {Token del passaggio precedente}
      • x-ms-dfpenvid: {ID ambiente dell'ambiente di destinazione}

    • Corpo:

      • Ottieni dalla pagina Swagger condivisa il corpo della richiesta di protezione dell'account di esempio.

Annotazioni

Se si crea un nuovo ambiente, includere l'ID ambiente nell'intestazione DELL'API durante l'integrazione, in modo che le transazioni possano essere indirizzate correttamente.

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

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

Per specificare l'ID API del cliente quando si crea un ambiente, vedere l'articolo Gestire gli ambienti.

Procedure consigliate

  • Ogni token di Microsoft Entra rimane valido per 60 minuti. È consigliabile memorizzarla nella cache per una durata più breve e riutilizzarla.
  • Assicurati che il tuo HttpClient abbia connessioni keep-alive.
  • Passare sempre l'intestazione x-ms-dfpenvid e assicurarsi che punti all'ambiente del commerciante per conto di cui si desidera inviare transazioni.
  • Archiviare il segreto in un archivio segreto.
  • Includere sempre l'intestazione x-ms-correlation-id per le sessioni di debug future con la Protezione dalle Frodi.
  • Assicurarsi che l'intestazione x-ms-correlation-id sia univoca per ogni transazione inviata a Fraud Protection. 

Visualizzare l'app di esempio

Per informazioni di riferimento aggiuntive, è possibile visualizzare l'app commerciante di esempio e la documentazione per sviluppatori associata. L'app di esempio fornisce un esempio di come chiamare le API di Protezione dalle frodi, inclusi gli eventi API, ad esempio l'invio di aggiornamenti, rimborsi e chargeback degli account dei clienti 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, gli esempi di codice esistono direttamente nella documentazione.

Per indicazioni su come configurare il sito di esempio per l'uso, vedere Configurare il sito di esempio.