Integrar APIs de proteção de compras
Este artigo explica como integrar APIs (interfaces de programação de aplicativos) em tempo real no Microsoft Dynamics 365 Fraud Protection.
Para aproveitar o conjunto completo de recursos do Fraud Protection, você deve enviar seus dados de transação para as APIs do Fraud Protection em tempo real. Na experiência de avaliação, o envio de seus dados de transação permite que você analise os resultados do uso do Fraud Protection. Na experiência de proteção, você também pode honrar as decisões com base nas regras que configurou.
Dependendo de como você usa o Fraud Protection, é possível usar conjuntos diferentes das seguintes APIs de proteção de compra:
- Comprar
- PurchaseStatus
- BankEvent
- Estorno
- Reembolso
- UpdateAccount
- Rótulo
Fases de integração da API
A integração das APIs de proteção de compra ocorre em três fases:
- Crie aplicativos Microsoft Entra por meio da Proteção contra Fraudes.
- Gerar um token de acesso.
- Chamar as APIs.
Entrar
Importante
Você deve ser um administrador global no seu locatário do Azure para concluir a entrada inicial.
Visite os seguintes portais para cada ambiente que você pretende usar. Faça logon e aceite os termos e condições, se solicitado.
- Ambiente de área restrita
- Ambiente de produção (Talvez você já tenha concluído esta etapa da produção durante a inscrição inicial.)
Criar aplicativos do Microsoft Entra
Importante
Você deve ser um administrador de aplicativo, administrador de aplicativo de nuvem ou administrador global em seu locatário do Azure para concluir esta etapa.
Para adquirir os tokens necessários para chamar as APIs, você deve configurar e usar os aplicativos do Microsoft Entra, conforme descrito nesta seção.
Configurar aplicativos do Microsoft Entra
Para configurar aplicativos do Microsoft Entra, siga estas etapas.
No portal Proteção contra fraudes, no painel de navegação esquerdo, selecione Integração > Criar instalação do aplicativo > Microsoft Entra agora.
Preencha a página para criar seu aplicativo. Recomendamos que você crie um aplicativo Microsoft Entra para cada ambiente que deseja integrar à Proteção contra Fraudes.
Insira ou selecione valores para os seguintes campos obrigatórios:
- Nome de exibição do aplicativo – Dê ao seu aplicativo um nome descritivo. O tamanho máximo é de 93 caracteres.
- Método de autenticação – Escolha se você deseja autenticar por meio de um certificado ou segredo (senha).
Se você selecionou o método de autenticação de certificado, siga estas etapas:
- Selecione Escolher o arquivo para carregar a chave pública. (A chave privada correspondente é exigida quando você adquire tokens.)
- Selecione Segredo para gerar automaticamente uma senha após a criação do aplicativo.
Quando terminar de definir os campos necessários, selecione Criar aplicativo. A página de confirmação resume o nome, a ID e a impressão digital de certificado ou segredo do seu aplicativo, dependendo do seu método de autenticação selecionado.
Importante
Salve as informações do segredo ou da impressão digital de certificado para referência futura. O segredo será exibido apenas uma vez.
Criar outro aplicativo
Para criar outro aplicativo, selecione Criar outro aplicativo. Você poderá criar quantos aplicativos forem necessários para executar chamadas de API em cada um de seus ambientes.
Gerenciar aplicativos existentes do Microsoft Entra
Depois de criar seus aplicativos do Microsoft Entra, você pode gerenciá-los por meio do [portal do Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Para obter mais informações, confira Como e por que os aplicativos são adicionados à ID do Microsoft Entra.
Gerar um token de acesso
Para integrar com segurança seus sistemas com a Proteção contra Fraude, obtenha um token Microsoft Entra e forneça-o no cabeçalho de cada chamada de API.
Observação
Os tokens de acesso têm uma vida útil limitada de 60 minutos. Recomendamos que você armazene em cache e reutilize um token até que esteja perto de expirar. Você pode então obter um novo token de acesso.
As informações a seguir são necessárias para obter um token.
IDs e informações necessárias
- URI de Ambiente – os URIs de seu ambiente de produção ou de área restrita aparecem na guia Configuração da página Gerenciamento de API no portal do Fraud Protection.
- ID do Diretório (locatário) – Esta ID do diretório é o Identificador Global Exclusivo (GUID) do domínio de um locatário no Azure. Ele aparece no portal do Azure e na guia Configuração da página Gerenciamento de API no portal do Fraud Protection.
- ID do aplicativo (cliente) – Essa ID identifica o aplicativo Microsoft Entra que você criou para chamar APIs. Obtenha a ID na página de confirmação APIs em tempo real ou localize-a posteriormente em Registros de aplicativos no portal do Azure. Haverá uma ID para cada aplicativo criado.
- Impressão digital de certificado ou segredo – Obtenha a impressão digital de certificado ou o segredo na página de confirmação das APIs em tempo real.
- ID da Instância – Esta ID é o GUID do seu ambiente no Fraud Protection. Ela aparece no bloco Integração no painel do Fraud Protection.
Exemplos: exemplos de código que mostram como adquirir um token usando seu certificado ou segredo
Os seguintes exemplos de código C# fornecem exemplos de aquisição de um token com seu certificado ou segredo. Substitua os espaços reservados por suas informações específicas. Para ambos os exemplos de C#, será necessário importar o pacote Microsoft.Identity.Client NuGet.
Para obter exemplos em outros idiomas, consulte o site https://aka.ms/aaddev.
Obter um token de acesso usando uma ID de aplicativo e uma chave de certificado privada
/// <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;
}
}
Obter um token de acesso usando uma ID de aplicativo e um segredo
/// <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;
}
}
O objeto AuthenticationResult em cada caso contém o valor AccessToken e uma propriedade ExpiresOn que indica quando o token se tornará inválido.
Solicitação POST para:
https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
Cabeçalhos:
- Content-type: application/x-www-form-urlencoded
Corpo (valor-chave):
- grant_type: client_credentials
- client_id : {Sua ID de cliente da etapa anterior}
- client_secret : {Seu segredo da etapa anterior}
- resource :
https://api.dfp.microsoft.com(for int,https://api.dfp.microsoft-int.com)
Resposta:
- Use o valor access‑token da resposta para a próxima etapa.
Para obter mais informações, consulte a seguinte documentação do Azure:
- Visão geral da Biblioteca de autenticação da Microsoft (MSAL)
- Obter e armazenar tokens usando a biblioteca de autenticação da Microsoft (MSAL)
Chamar as APIs
Para chamar as APIs, siga as etapas a seguir.
Passe os seguintes cabeçalhos HTTP necessários em cada solicitação.
Nome do cabeçalho Valor do cabeçalho Autorização Use o formato a seguir para este cabeçalho. (Substitua o accesstoken pelo valor de token real retornado pelo Microsoft Entra ID.)
Portador accesstoken
x-ms-correlation-id Envie um novo valor de GUID para cada conjunto de chamadas de API que são feitas juntas. x-ms-dfpenvid Envie o valor do GUID da sua ID de instância. Gere uma carga útil baseada em evento. Preencha os dados do evento com as informações relevantes do seu sistema. Para documentação sobre todos os eventos compatíveis, consulte API do Dynamics 365 Fraud Protection.
Combine o cabeçalho (que inclui o token de acesso) e a carga e envie-os para o ponto de extremidade do Fraud Protection.
Solicitação POST para:
<Base URL>/v1.0/merchantservices/events/purchase
Cabeçalhos:
- x-ms-correlation-id : {Um GUID, que deve ser exclusivo por solicitação}
- content-type: application/json
- Autorização: {O token da etapa anterior}
- x-ms-dfpenvid: {A ID do ambiente do ambiente de destino}
Corpo:
- Obtenha o corpo da solicitação de proteção de conta de amostra na página Swagger compartilhada.
Observação
Se você criar um novo ambiente, inclua a ID do ambiente no cabeçalho da API durante a integração, para que as transações possam ser roteadas corretamente.
As opções a seguir são aceitáveis para x-ms-dfpenvid na chamada à API e o comportamento é idêntico.
- Use a ID do ambiente para o ambiente que você está chamando. A ID está listada na página Integração no campo ID do ambiente.
- Use o padrão completo da ID da API do cliente da raiz para o ambiente filho que você está chamando usando a barra (/) como um divisor. Por exemplo, /primary/XYZ.
- Use o caminho completo da ID do ambiente ou da API do cliente da raiz para o ambiente filho que você está chamando usando a barra (/) como um divisor. Por exemplo, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.
Para especificar a ID da API do cliente ao criar um ambiente, consulte o artigo Gerenciar ambientes.
Práticas recomendadas
- Cada token do Microsoft Entra permanece válido por 60 minutos. Recomendamos armazená-lo em cache por um período mais curto e reutilizá-lo.
- Certifique-se de que seu HttpClient tenha conexões keep-alive.
- Sempre passe o cabeçalho x-ms-dfpenvid e verifique se ele aponta para o ambiente do comerciante em nome do qual você deseja enviar transações.
- Armazene o segredo em uma loja secreta.
- Sempre passe o cabeçalho x-ms-correlation-id para futuras sessões de depuração com o Fraud Protection.
- Certifique-se de que o cabeçalho x-ms-correlation-id seja exclusivo para cada transação enviada ao Fraud Protection.
Exibir o aplicativo de exemplo
Para referência adicional, consulte o aplicativo comercial de exemplo e a documentação do desenvolvedor que o acompanha. Esse aplicativo fornece um exemplo de como chamar APIs do Fraud Protection, incluindo eventos da API, como envio de atualizações, reembolsos e estornos de contas de clientes em tempo real. A documentação do aplicativo de exemplo está vinculada ao código de amostra real sempre que essas vinculações são possíveis. Caso contrário, os códigos de amostra estarão diretamente na documentação.
Para obter orientação sobre como configurar o site de exemplo para seu uso, consulte Configurar o site de exemplo.