Partilhar via

Integre APIs de proteção de compra

  • Artigo

Este artigo explica como integrar interfaces de programação de aplicativos (APIs) em tempo real na Proteção contra Fraude do Microsoft Dynamics 365.

Para tirar partido do conjunto completo de funcionalidades de Proteção contra Fraudes, tem de enviar os seus dados de transação para as APIs de Proteção contra Fraude em tempo real. Na experiência de avaliação, o envio dos dados da transação permite analisar os resultados do uso da Proteção contra Fraudes. Na experiência de proteção, você também pode honrar decisões, com base nas regras que você configurou.

Dependendo de como você usa a Proteção contra fraude, você pode usar diferentes conjuntos das seguintes APIs de proteção de compra:

  • Comprar o
  • PurchaseStatus
  • Evento Bancário
  • Estorno
  • Reembolso
  • AtualizarConta
  • Etiqueta

Fases de integração de API

A integração das APIs de proteção de compra ocorre em três fases:

  1. Crie aplicações Microsoft Entra através da Proteção contra Fraudes.
  2. Gere um token de acesso.
  3. Chame as APIs.

Iniciar sessão

Importante

Tem de ser um administrador global no seu inquilino do Azure para concluir o início de sessão inicial.

Visite os portais a seguir para cada ambiente que você pretende usar. Inicie sessão e aceite os termos e condições se lhe for pedido para o fazer.

  • Ambiente Sandbox
  • Ambiente de produção (Talvez você já tenha concluído esta etapa na produção durante a inscrição inicial.)

Criar aplicativos 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 aplicações Microsoft Entra, siga estes passos.

  1. No portal Proteção contra fraudes, no painel de navegação esquerdo, selecione Integração > Criar Configuração de Aplicativo > Microsoft Entra agora.

  2. 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.

  3. Insira ou selecione valores para os seguintes campos obrigatórios:

    • Nome de exibição do aplicativo – Dê ao seu aplicativo um nome descritivo. O comprimento máximo é de 93 caracteres.
    • Método de autenticação – Selecione se deseja autenticar por meio de um certificado ou de um segredo (senha).

  4. Se você selecionou o método de autenticação de certificado, siga estas etapas:

    1. Selecione Escolher arquivo para carregar a chave pública. (A chave privada correspondente é necessária quando você adquire tokens.)
    2. Selecione Segredo para gerar automaticamente uma senha após a criação do aplicativo.

  5. Quando terminar de definir os campos obrigatórios, selecione Criar aplicativo. A página de confirmação resume o nome, a ID e a impressão digital ou segredo do certificado do seu aplicativo, dependendo do método de autenticação selecionado.

Importante

Guarde as informações da sua impressão digital secreta ou do certificado para referência futura. O segredo só será exibido uma vez.

Criar outro aplicativo

Para criar outro aplicativo, selecione Criar outro aplicativo. Você pode criar quantos aplicativos forem necessários para executar chamadas de API em cada um dos seus ambientes.

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 Como e por que os aplicativos são adicionados à ID do Microsoft Entra.

Gerar um token de acesso

Para integrar com segurança os seus sistemas com a Proteção contra Fraudes, obtenha um token Microsoft Entra e forneça-o no cabeçalho de cada chamada de API.

Nota

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 ele esteja perto de expirar. Em seguida, você pode obter um novo token de acesso.

As seguintes informações são necessárias para obter um token.

IDs e informações necessárias

  • URI do ambiente – Os URIs para sua área restrita ou ambiente de produção aparecem na guia Configuração da página Gerenciamento de API no portal Proteção contra fraude.
  • ID do diretório (locatário) – essa ID é 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 de Proteção contra Fraude.
  • ID do aplicativo (cliente) – Esta ID identifica o aplicativo Microsoft Entra que você criou para chamar APIs. Obtenha a ID na página de confirmação de APIs em tempo real ou encontre-a 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 – Obtenha a impressão digital ou o segredo na página de confirmação das APIs em tempo real.
  • ID da instância – Este ID é o GUID do seu ambiente na Proteção contra fraudes. Ele aparece no bloco Integração no painel Proteção contra fraudes.

Exemplos: exemplos de código que mostram como adquirir um token usando seu certificado ou segredo

Os exemplos de código C# a seguir 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#, você precisará importar o pacote NuGet Microsoft.Identity.Client.

Para exemplos em outros idiomas, consulte https://aka.ms/aaddev.

Obter um token de acesso usando uma ID de aplicativo e uma chave de certificado particular

/// <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 um ID de aplicativo e 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.

  • Pedido POST para:

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

  • Cabeçalhos:

    • Tipo de conteúdo: application/x-www-form-urlencoded

  • Corpo (chave-valor):

    • grant_type: client_credentials
    • client_id: {Sua ID de Cliente da etapa anterior}
    • client_secret: {Seu segredo da etapa anterior}
    • Recurso: https://api.dfp.microsoft.com (para INT, https://api.dfp.microsoft-int.com)

  • Resposta:

    • Use o valor de access_token da resposta para a próxima etapa.

Para obter mais informações, consulte a seguinte documentação do Azure:

Chamar as APIs

Para chamar as APIs, siga estas etapas.

  1. 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. (Substitua accesstoken pelo valor real do token retornado pelo ID do Microsoft Entra.)

    Token de acesso ao portador

    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 ID da instância.

  2. Gere uma carga útil baseada em eventos. Preencha os dados do evento com as informações relevantes do seu sistema. Para obter documentação sobre todos os eventos suportados, consulte API de Proteção contra Fraude do Dynamics 365.

  3. 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.

    • Pedido POST para:

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

    • Cabeçalhos:

      • x-ms-correlation-id: {Um GUID, que deve ser exclusivo por solicitação}
      • Tipo de conteúdo: Application/JSON
      • Autorização: {O token da etapa anterior}
      • x-ms-dfpenvid: {A ID do ambiente de destino}

    • Corpo:

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.

As opções a seguir são aceitáveis para x-ms-dfpenvid na chamada de API e o comportamento é idêntico.

  • Use o ID do ambiente para o ambiente que você está chamando. O ID está listado na página Integração no campo ID do Ambiente.
  • Use o pat completo do ID da API do Cliente da raiz para o ambiente filho que você está chamando usando a barra (/) como divisor. Por exemplo, /primary/XYZ.
  • Use o caminho completo do ID do ambiente ou do ID da API do cliente da raiz para o ambiente filho que você está chamando usando a barra (/) como divisor. Por exemplo, 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Para especificar o ID da API do cliente ao criar um ambiente, consulte o artigo Gerenciar ambientes.

Melhores práticas

  • Cada token do Microsoft Entra permanece válido por 60 minutos. Recomendamos que você o armazene em cache por um período mais curto e o reutilize.
  • Certifique-se de que seu HttpClient tenha conexões keep-alive.
  • Sempre passe o cabeçalho x-ms-dfpenvid e certifique-se de que ele aponta para o ambiente do comerciante para o qual você deseja enviar transações em nome.
  • Guarde o segredo numa loja secreta.
  • Sempre passe o cabeçalho x-ms-correlation-id para futuras sessões de depuração com a Proteção contra Fraude.
  • Certifique-se de que o cabeçalho x-ms-correlation-id é exclusivo para cada transação enviada para a Proteção contra fraude. 

Ver a aplicação de exemplo

Para referência adicional, você pode visualizar o aplicativo de comerciante de exemplo e a documentação do desenvolvedor que o acompanha. O aplicativo de exemplo fornece um exemplo de como chamar APIs de proteção contra fraude, incluindo eventos de API, como o envio de atualizações da conta do cliente, reembolsos e estornos em tempo real. A documentação do aplicativo de exemplo é vinculada ao código de exemplo real sempre que esses links são possíveis. Caso contrário, exemplos de código existem diretamente na documentação.

Para obter orientação sobre como configurar o site de exemplo para seu uso, consulte Configurar o site de exemplo.