Delen via

API's voor aankoopbescherming integreren

  • Artikel

In dit artikel wordt uitgelegd hoe u realtime API's (Application Programming Interfaces) in Microsoft Dynamics 365 Fraud Protection integreert.

Als u de volledige reeks functies van Fraud Protection wilt gebruiken, verzendt u uw transactiegegevens naar de realtime API's voor Fraud Protection. Met de evaluatiefunctie kunt u de resultaten van het gebruik van Fraud Protection analyseren wanneer u uw transactiegegevens verzendt. Met de beschermingsfunctie kunt u beslissingen bevestigen op basis van de regels die u hebt geconfigureerd.

Afhankelijk van hoe u Fraud Protection gebruikt, kunt u gebruikmaken van verschillende sets van de volgende API's voor aankoopbescherming:

  • Inkoop
  • PurchaseStatus
  • BankEvent
  • Terugstorting
  • Restitutie
  • UpdateAccount
  • Label

Integratiefasen van API

De integratie van API's voor aankoopbescherming vindt in drie fasen plaats:

  1. Maak Microsoft Entra-toepassingen via Fraudebeveiliging.
  2. Een toegangstoken genereren.
  3. De API's aanroepen.

Aanmelden

Belangrijk

U moet een globale beheerder zijn in uw Azure-tenant om de eerste aanmelding te voltooien.

Bezoek de volgende portals voor elke omgeving die u wilt gebruiken. Meld u aan en accepteer de voorwaarden als u hierom wordt gevraagd.

Microsoft Entra-toepassingen maken

Belangrijk

U moet een toepassingsbeheerder, cloudtoepassingsbeheerder of globale beheerder zijn in uw Azure-tenant om deze stap te voltooien.

Als u de tokens wilt verkrijgen die nodig zijn om de API's aan te roepen, moet u Microsoft Entra-toepassingen configureren en gebruiken, zoals beschreven in deze sectie.

Microsoft Entra-toepassingen configureren

Volg deze stappen om Microsoft Entra-toepassingen te configureren.

  1. Selecteer in de portal Fraudebeveiliging in het navigatiedeelvenster links de optie Integratie > Microsoft Entra Application > Setup nu maken.

  2. Vul de pagina in om uw app te maken. U wordt aangeraden één Microsoft Entra-toepassing te maken voor elke omgeving die u wilt integreren met Fraud Protection.

  3. Typ of selecteer waarden voor de volgende verplichte velden:

    • Weergavenaam van toepassing: geef uw toepassing een beschrijvende naam. De tekst mag maximaal 93 tekens lang zijn.
    • Verificatiemethode: kies of u wilt verifiëren via een certificaat of een geheim (wachtwoord).

  4. Als u de methode voor certificaatverificatie hebt geselecteerd, volgt u deze stappen:

    1. Selecteer Bestand kiezen om de openbare sleutel te uploaden. (De bijpassende persoonlijke sleutel is vereist wanneer u tokens ontvangt.)
    2. Selecteer Geheim om automatisch een wachtwoord te genereren nadat de toepassing is gemaakt.

  5. Wanneer u klaar bent met het instellen van de vereiste velden, selecteert u Toepassing maken. De bevestigingspagina biedt een overzicht met de naam, de id en de certificaatvingerafdruk of het geheim, afhankelijk van uw geselecteerde verificatiemethode.

Belangrijk

Sla de vingerafdrukinformatie voor uw geheim of certificaat op voor toekomstige referentie. Het geheim wordt slechts eenmaal getoond.

Nog een toepassing maken

Als u nog een toepassing wilt maken, selecteert u Nog een toepassing maken. U kunt zoveel apps maken als nodig zijn om API-aanroepen in al uw omgevingen uit te voeren.

Bestaande Microsoft Entra-toepassingen beheren

Nadat u uw Microsoft Entra-apps hebt gemaakt, kunt u deze beheren via [Azure Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Zie Hoe en waarom toepassingen worden toegevoegd aan Microsoft Entra ID voor meer informatie.

Een toegangstoken genereren

Als u uw systemen veilig wilt integreren met Fraud Protection, haalt u een Microsoft Entra-token op en geeft u dit op in de header van elke API-aanroep.

Notitie

Toegangstokens een hebben een beperkte levensduur van 60 minuten. We raden u aan een token in de cache te plaatsen en opnieuw te gebruiken totdat het bijna is verstreken. Vervolgens kunt u een nieuw toegangstoken krijgen.

De volgende informatie is nodig om een token te verkrijgen.

Vereiste id's en gegevens

  • Omgevings-URI: de URI's voor uw sandbox- of productieomgeving worden weergegeven op het tabblad Configuratie van de pagina API-beheer in de Fraud Protection-portal.
  • Directory-id (tenant): deze id is de GUID (Globally Unique Identifier) van het domein van een tenant in Azure. Deze wordt weergegeven in de Azure-portal en op het tabblad Configuratie van de pagina API-beheer in de Fraud Protection-portal.
  • Toepassings-id (client): deze id identificeert de Microsoft Entra-app die u hebt gemaakt om API's aan te roepen. Haal de id op van de bevestigingspagina Realtime API's of vind deze later in de Azure-portal onder App-registraties. Er is één id voor elke app die u hebt gemaakt.
  • Vingerafdruk van certificaat of geheim: haal de vingerafdruk of het geheim op via de bevestigingspagina voor de realtime API.
  • realtime API: deze id is de GUID van uw omgeving in Fraud Protection. Deze wordt weergegeven op de tegel Integratie van het Fraud Protection-dashboard.

Voorbeelden: codevoorbeelden die laten zien hoe u een token verkrijgt met behulp van uw certificaat of geheim

De volgende voorbeelden in C#-code laten zien hoe u een token met uw certificaat of geheim aanvraagt. Vervang de tijdelijke aanduidingen door uw specifieke informatie. Voor beide voorbeelden van C# moet u het Microsoft.Identity.Client NuGet-pakket importeren.

Voorbeelden in andere talen https://aka.ms/aaddev vindt u hier.

Een toegangstoken krijgen door een app-id en een persoonlijke certificaatsleutel te gebruiken

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

Een toegangstoken krijgen door een app-id en geheim te gebruiken

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

Het object AuthenticationResult bevat in beide gevallen de waarde AccessToken en een eigenschap ExpiresOn waarmee wordt aangegeven wanneer het token ongeldig wordt.

  • POST-aanvraag naar:

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

  • Headers:

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

  • Body (key-value):

    • grant_type: client_credentials
    • client_id: {uw client-id uit de vorige stap}
    • client_secret: {uw geheim uit de vorige stap}
    • resource: https://api.dfp.microsoft.com (voor int.: https://api.dfp.microsoft-int.com)

  • Respons:

    • Gebruik de waarde van access_token uit de respons voor de volgende stap.

Raadpleeg de volgende Azure-documentatie voor meer informatie:

De API's aanroepen

Volg deze stappen om de API's aan te roepen.

  1. Geef bij elk verzoek de volgende vereiste HTTP-headers door.

    Headernaam Headerwaarde
    Autorisatie

    Gebruik de volgende indeling voor deze header. (Vervang het toegangstoken door de werkelijke tokenwaarde die wordt geretourneerd door Microsoft Entra-id.)

    Accesstoken van bearer
    x-ms-correlation-id Verzend een nieuwe GUID-waarde voor elke set API-aanroepen die samen worden ingediend.
    x-ms-dfpenvid Verzend de GUID-waarde van uw exemplaar-id.

  2. Genereer een op gebeurtenissen gebaseerde payload. Vul voor de gebeurtenisgegevens de relevante informatie van uw systeem in. Zie Dynamics 365 Fraud Protection-API voor documentatie over alle ondersteunde gebeurtenissen.

  3. Combineer de header (inclusief de toegangstoken) en de payload en stuur deze vervolgens naar uw Fraud Protection-eindpunt.

    • POST-aanvraag naar:

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

    • Headers:

      • x-ms-correlation-id : {GUID moet uniek zijn per aanvraag}
      • content-type: application/json
      • Autorisatie: {Het token uit de vorige stap}
      • x-ms-dfpenvid: {De omgevings-id van de doelomgeving}

    • Body:

      • Haal de aanvraagbody van de voorbeeldaccountbeveiliging op van de gedeelde Swagger-pagina.

Opmerking

Als u een nieuwe omgeving maakt, neemt u tijdens de integratie de omgevings-id op in de API-header, zodat de transacties correct kunnen worden gerouteerd.

De volgende opties zijn acceptabel voor x-ms-dfpenvid in de API-aanroep en het gedrag is identiek.

  • Gebruik de omgevings-id voor de omgeving die u aanroept. De id wordt vermeld op de pagina Integratie in het veld Omgevings-id.
  • Gebruik het volledige pad van de klant-API-id van de hoofdmap tot de onderliggende omgeving die u aanroept met de slash (/) als scheidingsteken. Bijvoorbeeld /primair/XYZ.
  • Gebruik het volledige pad van de omgevings-id of klant-API-id van de hoofdmap tot de onderliggende omgeving die u aanroept met de slash (/) als scheidingsteken. Bijvoorbeeld 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Zie het artikel Omgevingen beheren om de klant-API-id op te geven bij het maken van een omgeving.

Aanbevolen procedures

  • Elk Microsoft Entra-token blijft 60 minuten geldig. U wordt aangeraden dit token voor een kortere duur in de cache op te slaan en opnieuw te gebruiken.
  • Zorg ervoor dat uw HttpClient keep-alive-verbindingen heeft.
  • Geef altijd de header x-ms-dfpenvid door en zorg dat deze wijst naar de omgeving van de verkoper namens wie u transacties wilt verzenden.
  • Sla het geheim op in een geheimenarchief.
  • Geef altijd de header x-ms-correlation-id voor toekomstige foutopsporingssessies met Fraud Protection door.
  • Zorg dat de header x-ms-correlation-id uniek is voor elke transactie die naar Fraud Protection wordt verzonden. 

De voorbeeld-app weergeven

Voor extra referentie kunt u de voorbeeld verkopers-app en de bijbehorende documentatie voor ontwikkelaars raadplegen. De voorbeeld-app geeft een voorbeeld van hoe u Fraud Protection-API's kunt aanroepen, inclusief API-gebeurtenissen, zoals het verzenden van klantaccountupdates, terugbetalingen en terugstortingen in realtime. De documentatie voor de voorbeeld-app is gekoppeld aan de werkelijke voorbeeldcode wanneer dergelijke koppelingen mogelijk zijn. Anders bestaan er codevoorbeelden direct in de documentatie.

Raadpleeg voor meer informatie over het configureren van de voorbeeldsite voor uw gebruik De voorbeeldsite configureren.