Integrar APIs de proteção de conta
Para aproveitar o conjunto completo de recursos da Proteção contra Fraude do Microsoft Dynamics 365, envie seus dados de transação para as interfaces de programação de aplicativos (APIs) em tempo real. Na experiência de avaliação, você pode analisar os resultados do uso da Proteção contra fraudes. Na experiência de proteção, você também pode honrar decisões baseadas nas regras que você configurou.
Dependendo de como você optar por usar a Proteção contra fraude, você pode usar diferentes APIs de proteção de conta. Por exemplo, AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate e Label.
Para obter informações sobre todos os eventos suportados, consulte API de Proteção contra Fraude do Dynamics 365.
Configurar
Iniciar sessão
Importante
Para concluir a integração inicial da API, você deve ser um Administrador Global em seu locatário do Microsoft Azure.
Para iniciar sessão na Proteção contra fraudes:
Aceda ao portal de Proteção contra Fraudes, inicie sessão e aceite os termos e condições se lhe for pedido para os aceitar.
Esta etapa garante que a Proteção contra Fraude esteja configurada corretamente em seu locatário do Azure. (Talvez você já tenha concluído esta etapa durante a inscrição inicial.)
Criar aplicativos Microsoft Entra
Importante
Para concluir esta etapa, você deve ser um Administrador de Aplicativo, um Administrador de Aplicativo de Nuvem ou um Administrador Global em seu locatário do Azure.
Para adquirir os tokens necessários para chamar as APIs, você deve usar aplicativos Microsoft Entra. Você pode configurar esses aplicativos usando a página APIs em tempo real em Proteção contra fraude.
Para configurar os aplicativos Microsoft Entra:
No painel de navegação esquerdo, selecione Configuração e, em seguida, selecione APIs em tempo real.
Preencha os campos para criar seu aplicativo. Os seguintes campos são obrigatórios:
- Nome de exibição do aplicativo – Insira um nome descritivo para seu aplicativo. O comprimento máximo é de 93 caracteres.
- Ambiente – Selecione o ponto de extremidade de produção.
- Método de autenticação – Selecione se um certificado ou um segredo (senha) é usado para autenticação. Se você selecionar Certificado, selecione Escolher arquivo para carregar a chave pública. Ao adquirir tokens, você precisará da chave privada correspondente. Se você selecionar Segredo, uma senha será gerada para você depois que o aplicativo for criado.
Quando terminar de preencher os campos, selecione Criar aplicativo.
A página de confirmação resume o nome e a ID do aplicativo, bem como a impressão digital do certificado ou o segredo, dependendo do método de autenticação selecionado.
Importante
Guarde as informações sobre a impressão digital ou o segredo do seu certificado para referência futura. O segredo será mostrado apenas uma vez.
Você pode criar quantos aplicativos forem necessários para executar chamadas de API em seus ambientes de produção.
Para criar outro aplicativo:
- Selecione Criar outro aplicativo.
- Preencha os campos para criar seu aplicativo e selecione Criar aplicativo.
Gerenciar aplicativos existentes do Microsoft Entra
Depois de criar seus aplicativos 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, consulte o site de documentação do Azure.
Chame as APIs de Proteção contra Fraude em tempo real
Use as informações desta seção para integrar seus sistemas com a Proteção contra fraudes.
IDs e informações necessárias
- API Endpoint – O URI do seu ambiente aparece no bloco Informações da conta no painel Proteção contra fraudes.
- ID do diretório (locatário) – A ID do diretório é o identificador global exclusivo (GUID) para o domínio de um locatário no Azure. Ele aparece no portal do Azure e no bloco Informações da conta no painel Proteção contra fraude.
- ID do aplicativo (cliente) – A ID do aplicativo identifica o aplicativo Microsoft Entra que você criou para chamar APIs. Você pode encontrar esse ID na página de confirmação que aparece depois de selecionar Criar aplicativo na página APIs em tempo real. Você também pode encontrá-lo mais tarde, em Registros de aplicativos no portal do Azure. Haverá um ID para cada aplicativo que você criou.
- Impressão digital ou segredo do certificado – Você pode encontrar a impressão digital do certificado ou o segredo na página de confirmação que aparece depois de selecionar Criar aplicativo na página APIs em tempo real.
- ID da instância - O ID da instância é o identificador global exclusivo (GUID) do seu ambiente na Proteção contra fraudes. Ele aparece no bloco Integração no painel Proteção contra fraudes.
Gerar um token de acesso
Você deve gerar esse token e fornecê-lo a cada chamada de API. Observe que os tokens de acesso têm uma vida útil limitada. Recomendamos que você armazene em cache e reutilize cada token de acesso até que seja hora de obter um novo token de acesso.
Os exemplos de código C# a seguir fornecem exemplos que mostram como adquirir um token usando seu certificado ou segredo. Substitua os espaços reservados usando suas próprias informações.
Impressão digital do certificado
public async Task<string> AcquireTokenWithCertificateAsync()
{
var x509Cert = CertificateUtility.GetByThumbprint("<Certificate thumbprint>");
var clientAssertion = new ClientAssertionCertificate("<Client ID>", x509Cert);
var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);
return authenticationResult.AccessToken;
}
Segredo
public async Task<string> AcquireTokenWithSecretAsync()
{
var clientAssertion = new ClientCredential("<Client ID>", "<Client secret>");
var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);
return authenticationResult.AccessToken;
}
Response
Nos bastidores, o código anterior gera uma solicitação HTTP e recebe uma resposta semelhante ao exemplo a seguir.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: <date>
Content-Length: <content length>
{
"token_type":"Bearer",
"expires_in":"3599",
"ext_expires_in":"3599",
"expires_on":"<date timestamp>",
"not_before":"<date timestamp>",
"resource":"https://api.dfp.dynamics.com",
"access_token":"<your access token; e.g.: eyJ0eXA...NFLCQ>"
}
Para obter mais informações, consulte a documentação do Azure:
- Use a asserção do cliente para obter tokens de acesso do Microsoft Entra ID
- Tokens de acesso da cache
Chamar as APIs
Para chamar as APIs, siga estas etapas.
Passe os seguintes cabeçalhos HTTP necessários em cada solicitação.
Nome do cabeçalho Valor do cabeçalho Autorização Use o seguinte formato para este cabeçalho: Bearer accesstoken, onde accesstoken é o token retornado pelo Microsoft Entra ID. x-ms-correlation-id Envie um novo valor de GUID em cada conjunto de chamadas de API feitas em conjunto. x-ms-dfpenvid Envie o valor GUID do seu ID de instância. Gere uma carga útil baseada em eventos. Preencha os dados do evento com as informações relevantes do seu sistema. Para obter informações sobre todos os eventos suportados, consulte API de Proteção contra Fraude do Dynamics 365.
Combine o cabeçalho (que inclui o token de acesso) e a carga útil e, em seguida, envie-os para o ponto de extremidade da Proteção contra fraudes.
Nota
Se você criar um novo ambiente, inclua o ID do ambiente no cabeçalho da API durante a integração, para que as transações possam ser roteadas corretamente.
Ver a aplicação de exemplo
Para obter referência adicional, visualize o aplicativo de comerciante de exemplo e consulte a documentação do desenvolvedor que o acompanha. O aplicativo de exemplo fornece um exemplo que mostra como chamar APIs de proteção contra fraude em tempo real. A documentação do aplicativo de exemplo é vinculada ao código de exemplo real sempre que os links são possíveis. Caso contrário, exemplos de código são incluídos diretamente na documentação.
Para obter informações sobre como configurar o site de exemplo para que você possa usá-lo, consulte Configurar o site de exemplo.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários