Intégrer les API de protection des achats
Cet article explique comment intégrer les interfaces de programmation d’applications (API) en temps réel dans Microsoft Dynamics 365 Fraud Protection.
Pour tirer parti de la suite complète de fonctionnalités de Fraud Protection, vous devez envoyer vos données de transaction aux API en temps réel de Fraud Protection. 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 Fraud Protection. Dans l’expérience de protection, vous pouvez également honorer des décisions selon les règles que vous avez configurées.
Selon la façon dont vous utilisez Fraud Protection, vous pouvez utiliser différents ensembles des API de protection des achats suivantes :
- Achat
- PurchaseStatus
- BankEvent
- Rétrofacturation
- Remboursement
- UpdateAccount
- Libellé
Phases d’intégration de l’API
L’intégration des API de protection des achats se déroule en trois phases :
- Créez des applications Microsoft Entra par le biais de la protection contre les fraudes.
- Générez un jeton d’accès.
- Appelez les API.
Connexion
Important
Vous devez être administrateur général dans votre client Azure pour terminer la connexion initiale.
Visitez les portails suivants pour chaque environnement que vous comptez utiliser. Connectez-vous et acceptez les conditions générales si vous y êtes invité.
- Environnement de bac à sable
- Environnement de production (Vous pouvez déjà avoir effectué cette étape en production lors de l’inscription initiale.)
Créer des applications Microsoft Entra
Important
Vous devez être administrateur d’application, administrateur d’application cloud ou administrateur général dans votre client 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.
Dans le portail Fraud Protection, dans le volet de navigation gauche, sélectionnez Integration > Create Microsoft Entra Application > Setup now.
Complétez 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.
Entrez ou sélectionnez des valeurs pour les champs obligatoires suivants :
- Nom d’affichage de l’application : donnez à votre application un nom descriptif. La longueur maximale est de 93 caractères.
- Méthode d’authentification : choisissez si vous souhaitez vous authentifier via un certificat ou un secret (mot de passe).
Si vous avez sélectionné la méthode d’authentification par certificat, procédez comme suit :
- Sélectionnez Choisir un fichier pour charger la clé publique. (La clé privée correspondante est requise lorsque vous faites l’acquisition de jetons.)
- Sélectionnez Secret pour générer automatiquement un mot de passe une fois l’application créée.
Lorsque vous avez terminé de définir les champs obligatoires, sélectionnez Créer une application. La page de confirmation résume le nom, l’ID et l’empreinte de certificat ou le secret de votre application, selon la méthode d’authentification que vous avez sélectionnée.
Important
Enregistrez vos informations d’empreinte de certificat ou de secret à titre de référence. Le secret s’affiche 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 [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. Il est recommandé de mettre en cache et de réutiliser un jeton jusqu’à ce qu’il soit près d’expirer. Vous pouvez ensuite obtenir un nouveau jeton d’accès.
Les informations suivantes sont nécessaires pour obtenir un jeton.
ID et Informations obligatoires
- URI d’environnement : les URI de votre environnement de bac à sable ou de production apparaissent dans l’onglet Configuration de la page Gestion des API du portail de Fraud Protection.
- ID de répertoire (client) : cet ID est l’identificateur global unique (GUID) du domaine d’un client dans Azure. Il apparaît dans le portail Azure et dans l’onglet Configuration de la page Gestion des API du portail Fraud 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 API en temps réel ou trouvez-le ultérieurement sous Inscriptions d’applications dans le portail Azure. Il existera un ID pour chaque application que vous avez créée.
- Empreinte ou secret de certificat : obtenez l’empreinte ou le secret depuis la page de confirmation API en temps réel.
- ID d’instance : cet ID est le GUID de votre environnement dans Fraud Protection. Il apparaît dans la vignette Intégration sur le tableau de bord Fraud Protection.
Exemples : exemples de code qui indiquent comment acquérir un jeton avec votre certificat ou votre secret
Les exemples de code C# suivants fournissent des exemples pour acquérir un jeton avec votre certificat ou secret. Remplacez les espaces réservés par vos informations spécifiques. Pour les deux exemples C#, vous devrez importer le package NuGet Microsoft.Identity.Client.
Pour des exemples dans d’autres langages, voir https://aka.ms/aaddev.
Obtenir un jeton d’accès en utilisant un ID d’application et une clé de certificat privée
/// <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 en utilisant un ID d’application et 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 deviendra invalide.
Demande POST à :
https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
En-têtes :
- Content-type : application/x-www-form-urlencoded
Corps (valeur clé) :
- 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 de l’étape suivante.
Pour plus d’informations, consultez la documentation Azure suivante :
- Présentation de la bibliothèque d’authentification Microsoft (MSAL)
- Acquérir et mettre en cache des jetons à l’aide de la bibliothèque d’authentification Microsoft (MSAL)
Appeler les API
Pour appeler les API, procédez comme suit :
Passez les en-têtes HTTP requis suivants sur chaque demande.
Nom d’en-tête Valeur d’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.)
accesstoken du porteur
x-ms-correlation-id Envoyer une nouvelle valeur GUID sur chaque ensemble d’appels d’API qui sont réalisés ensemble. x-ms-dfpenvid Envoyez la valeur GUID de votre ID d’instance. Générez une charge utile basée sur événement. Remplissez les données d’événement avec des informations importantes de votre système. Pour obtenir de la documentation sur l’ensemble des événements pris en charge, consultez l’API Dynamics 365 Fraud Protection.
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
En-têtes :
- x-ms-correlation-id : {GUID qui doit être unique par demande}
- 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 la demande de protection des comptes à partir de la Page Swagger partagée.
Note
Si vous créez un nouvel environnement, incluez l’ID d’environnement dans l’en-tête de l’API pendant l’intégration, afin que les transactions puissent être correctement acheminé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 de l’environnement que vous appelez. Cet ID est répertorié sur la page Intégration dans le champ ID d’environnement.
- Utilisez le chemin d’accès complet de l’ID d’API du client depuis la racine jusqu’à l’environnement enfant que vous appelez en utilisant la barre oblique (/) comme diviseur. Par exemple, /primary/XYZ.
- Utilisez le chemin d’accès complet de l’ID d’API de l’environnement ou du client depuis la racine jusqu’à l’environnement enfant que vous appelez en utilisant la barre oblique (/) comme diviseur. Par exemple, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.
Pour spécifier l’ID de l’API client lorsque vous créez un environnement, consultez l’article Gérer les environnements.
Bonnes pratiques
- Chaque jeton Microsoft Entra reste valide pendant 60 minutes. Nous vous recommandons de le mettre en cache pendant une durée plus courte et de le réutiliser.
- Assurez-vous que votre HttpClient a des connexions keep-alive.
- Transmettez toujours l’en-tête x-ms-dfpenvid et assurez-vous qu’il pointe vers l’environnement du marchand au nom duquel vous souhaitez envoyer des transactions.
- Stockez le secret dans un magasin de secrets.
- Transmettez toujours l’en-tête x-ms-correlation-id pour les futures sessions de débogage avec Fraud Protection.
- Assurez-vous que l’en-tête x-ms-correlation-id est unique pour chaque transaction envoyée à Fraud Protection.
Afficher l’exemple d’application
Pour plus d’informations, vous pouvez consulter l’exemple d’application prestataire et la documentation de développement jointe. L’exemple d’application fournit un exemple sur la manière d’appeler les API Fraud Protection, y compris les événements d’API tels que l’envoi de mises à jour, de remboursements et de rétrofacturations de compte client en temps réel. La documentation concernant l’exemple d’application est associée à l’exemple de code réel à chaque fois que de telles associations sont possibles. Sinon, les exemples de code existent directement dans la documentation.
Pour obtenir des instructions sur la configuration de l’exemple de site pour votre utilisation, consultez Configurer l’exemple de site.