Partager via

Intégrer des API de protection des achats

Important

Depuis le 3 février 2025, Dynamics 365 Fraud Protection n’est plus disponible pour l’achat. La prise en charge de la protection contre les fraudes prendra fin le 3 février 2026. Pour plus d’informations, consultez l’article Fin de prise en charge de Dynamics 365 Fraud Protection.

Cet article explique comment intégrer des interfaces de programmation d’applications en temps réel dans Microsoft Dynamics 365 Fraud Protection.

Pour tirer parti de la suite complète de fonctionnalités de protection contre les fraudes, vous devez envoyer vos données de transaction aux API de protection contre les fraudes en temps réel. Dans l’expérience d’évaluation, l’envoi de vos données de transaction vous permet d’analyser les résultats de l’utilisation de la protection contre les fraudes. Dans l’expérience de protection, vous pouvez également respecter les décisions en fonction des règles que vous avez configurées.

Selon la façon dont vous utilisez la protection contre les fraudes, vous pouvez utiliser différents ensembles d’API de protection d’achat suivantes :

  • Achats
  • Statut d'achat
  • Événement Bancaire
  • Rétrofacturation
  • Remboursement
  • Mise à jour du compte
  • Étiquette

Phases d’intégration d’API

L’intégration des API de protection d’achat se produit en trois phases :

  1. Créez des applications Microsoft Entra par le biais de la protection contre les fraudes.
  2. Générez un jeton d’accès.
  3. Appelez les API.

Connectez-vous

Important

Vous devez être administrateur général dans votre locataire Azure pour terminer la connexion initiale.

Visitez les portails suivants pour chaque environnement que vous envisagez d’utiliser. Connectez-vous et acceptez les conditions générales si vous y êtes invité.

Créer des applications Microsoft Entra

Important

Vous devez être administrateur d’application, administrateur d’application cloud ou administrateur général dans votre locataire Azure pour effectuer cette étape.

Pour acquérir les jetons requis pour appeler les API, vous devez configurer et utiliser les applications Microsoft Entra, comme décrit dans cette section.

Configurer des applications Microsoft Entra

Pour configurer des applications Microsoft Entra, procédez comme suit.

  1. Dans le portail Fraud Protection, dans le volet de navigation gauche, sélectionnez Integration > Create Microsoft Entra Application > Setup now.

  2. Terminez la page pour créer votre application. Nous vous recommandons de créer une application Microsoft Entra pour chaque environnement que vous souhaitez intégrer à Fraud Protection.

  3. Entrez ou sélectionnez des valeurs pour les champs obligatoires suivants :

    • Nom complet de l’application : donnez un nom descriptif à votre application. La longueur maximale est de 93 caractères.
    • Méthode d’authentification : indiquez si vous souhaitez vous authentifier via un certificat ou un secret (mot de passe).

  4. Si vous avez sélectionné la méthode d’authentification par certificat, procédez comme suit :

    1. Sélectionnez Choisir un fichier pour charger la clé publique. (La clé privée correspondante est requise lorsque vous achetez des jetons.)
    2. Sélectionnez Secret pour générer automatiquement un mot de passe après la création de l’application.

  5. Une fois que vous avez terminé de définir les champs requis, sélectionnez Créer une application. La page de confirmation récapitule le nom, l’ID et l’empreinte numérique ou le secret de votre application, selon la méthode d’authentification que vous avez sélectionnée.

Important

Enregistrez vos informations d’empreinte secrète ou de certificat pour référence ultérieure. Le secret ne s’affiche qu’une seule fois.

Créer une autre application

Pour créer une autre application, sélectionnez Créer une autre application. Vous pouvez créer autant d’applications que nécessaire pour exécuter des appels d’API dans chacun de vos environnements.

Gérer les applications Microsoft Entra existantes

Après avoir créé vos applications Microsoft Entra, vous pouvez les gérer via le [portail Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Pour plus d’informations, consultez Comment et pourquoi les applications sont ajoutées à Microsoft Entra ID.

Générer un jeton d’accès

Pour intégrer en toute sécurité vos systèmes à Fraud Protection, obtenez un jeton Microsoft Entra et fournissez-le dans l’en-tête de chaque appel d’API.

Remarque

Les jetons d’accès ont une durée de vie limitée de 60 minutes. Nous vous recommandons de mettre en cache et de réutiliser un jeton jusqu’à ce qu’il soit proche de l’expiration. Vous pouvez ensuite obtenir un nouveau jeton d’accès.

Les informations suivantes sont nécessaires pour obtenir un jeton.

ID et informations requis

  • URI d’environnement : les URI de votre environnement de bac à sable ou de production s’affichent sous l’onglet Configuration de la page Gestion des API dans le portail Fraud Protection.
  • ID d’annuaire (locataire) : cet ID est l’identificateur global unique (GUID) du domaine d’un locataire dans Azure. Il apparaît dans le portail Azure et sous l’onglet Configuration de la page Gestion des API dans le portail Fraude Protection.
  • ID d’application (client) : cet ID identifie l’application Microsoft Entra que vous avez créée pour appeler des API. Obtenez l’ID à partir de la page de confirmation des API en temps réel ou recherchez-le ultérieurement sous Inscriptions d’applications dans le portail Azure. Il y aura un ID pour chaque application que vous avez créée.
  • Empreinte numérique ou secret du certificat : obtenez l’empreinte numérique ou le secret à partir de la page de confirmation des API en temps réel.
  • ID d’instance : cet ID est le GUID de votre environnement dans La protection contre les fraudes. Il apparaît dans la vignette Intégration dans le tableau de bord Protection contre les fraudes.

Exemples de code qui montrent comment acquérir un jeton à l’aide de votre certificat ou de votre secret

Les exemples de code C# suivants fournissent des exemples d’acquisition d’un jeton avec votre certificat ou votre secret. Remplacez les espaces réservés par vos informations spécifiques. Pour les deux exemples C#, vous devez importer le package NuGet Microsoft.Identity.Client.

Pour obtenir des exemples dans d’autres langues, consultez https://aka.ms/aaddev.

Obtenir un jeton d’accès à l’aide d’un ID d’application et d’une clé de certificat privé

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

Obtenir un jeton d’accès à l’aide d’un ID d’application et d’un secret

/// <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’objet AuthenticationResult dans chaque cas contient la valeur AccessToken et une propriété ExpiresOn qui indique quand le jeton devient non valide.

  • Demande POST à :

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

  • Headers :

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

  • Corps (clé-valeur) :

    • grant_type : client_credentials
    • client_id : {Votre ID client de l’étape précédente}
    • client_secret : {Votre secret de l’étape précédente}
    • ressource : https://api.dfp.microsoft.com (pour int, https://api.dfp.microsoft-int.com)

  • Réponse :

    • Utilisez la valeur de access_token de la réponse pour l’étape suivante.

Pour plus d’informations, consultez la documentation Azure suivante :

Appeler les API

Pour appeler les API, procédez comme suit.

  1. Transmettez les en-têtes HTTP requis suivants sur chaque requête.

    Nom de l’en-tête Valeur de l’en-tête
    Autorisation

    Utilisez le format suivant pour cet en-tête. (Remplacez accesstoken par la valeur de jeton réelle retournée par l’ID Microsoft Entra.)

    Porteur accesstoken
    x-ms-correlation-id Envoyez une nouvelle valeur GUID sur chaque ensemble d’appels d’API effectués ensemble.
    x-ms-dfpenvid Envoyez la valeur GUID de votre ID d’instance.

  2. Générez une charge utile basée sur les événements. Renseignez les données d’événement avec les informations pertinentes de votre système. Pour obtenir de la documentation sur tous les événements pris en charge, consultez l’API Dynamics 365 Fraud Protection.

  3. Combinez l’en-tête (qui inclut le jeton d’accès) et la charge utile, puis envoyez-les à votre point de terminaison Fraud Protection.

    • Demande POST à :

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

    • Headers :

      • x-ms-correlation-id: {Un GUID, qui doit être unique par requête}
      • content-type : application/json
      • Autorisation : {Jeton de l’étape précédente}
      • x-ms-dfpenvid : {ID d’environnement de l’environnement cible}

    • Corps :

      • Obtenez l'exemple de corps de requête pour la protection d'un compte depuis la page Swagger partagée.

Remarque

Si vous créez un environnement, incluez l’ID d’environnement dans l’en-tête d’API pendant l’intégration, afin que les transactions puissent être correctement routées.

Les options suivantes sont acceptables pour x-ms-dfpenvid dans l’appel d’API et le comportement est identique.

  • Utilisez l'ID d'environnement pour l'environnement que vous appelez. L’ID est répertorié dans la page Intégration dans le champ ID d’environnement .
  • Utilisez le chemin complet de l’ID d’API client de la racine jusqu’à l’environnement enfant que vous appelez, en utilisant la barre oblique (/) comme séparateur. Par exemple, /primary/XYZ.
  • Utilisez le chemin complet de l’ID d’environnement ou de l’ID d’API client de la racine vers l’environnement enfant que vous appelez à l’aide de la barre oblique (/) comme séparateur. Par exemple, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Pour spécifier l’ID d’API client lorsque vous créez un environnement, consultez l’article Gérer les environnements.

Meilleures pratiques

  • Chaque jeton Microsoft Entra reste valide pendant 60 minutes. Nous vous recommandons de la mettre en cache pendant une durée plus courte et de la réutiliser.
  • Assurez-vous que votre HttpClient maintient des connexions persistantes.
  • Passez toujours l’en-tête x-ms-dfpenvid et assurez-vous qu'il pointe vers l'environnement du marchand pour lequel vous souhaitez envoyer des transactions.
  • Stockez le secret dans un magasin de secrets.
  • Transmettez toujours l’en-tête x-ms-correlation-id lors des sessions de débogage futures avec Fraud Protection.
  • Vérifiez que l’en-tête x-ms-correlation-id est unique pour chaque transaction envoyée à Fraud Protection. 

Afficher l’exemple d’application

Pour obtenir des informations de référence supplémentaires, vous pouvez consulter l’exemple d’application marchande et la documentation du développeur associée. L'application exemple illustre comment appeler les API de protection contre la fraude, y compris les événements API tels que l'envoi de mises à jour de compte client, de remboursements et de rétrofacturations en temps réel. La documentation de l’exemple d’application est liée à un exemple de code réel chaque fois que ces liens sont possibles. Sinon, des exemples de code existent directement dans la documentation.

Pour obtenir des conseils sur la configuration de l’exemple de site pour votre utilisation, consultez Configurer l’exemple de site.