API de etiquetas

Artigo
07/29/2024

Este artigo explica como a API de rótulos permite enviar informações para os painéis de relatório e monitoramento na Proteção contra Fraude do Microsoft Dynamics 365.

A API de etiquetas permite-lhe enviar sinais de fraude ou não fraude para a Proteção contra Fraude. Esses dados são usados para treinamento de modelos, avaliação de desempenho de modelos e relatórios. A API de rótulos é uma API geral que rotula eventos de avaliação usando IDs de transações ou eventos individuais ou entidades como usuário ou instrumento de pagamento.

Cenários de rótulo comuns para transações ou eventos

Quaisquer transações fraudulentas que sejam escaladas pelos seus clientes
Atividade fraudulenta ou abuso de conta identificado pela sua equipe de avaliações
Qualquer análise offline (como análise de comportamento ou conexões descobertas com casos de fraude existentes)
TC40/SAFE sinais recebidos
Reversão de um sinal de fraude anterior após ser identificado como não fraude com base nas últimas informações disponíveis
Estornos/reembolsos recebidos
Reversão de estorno após uma disputa

Recomendamos que você use a API de estorno e reembolso para fornecer informações relacionadas a estornos e reembolsos. Para obter mais informações sobre eventos suportados, consulte Dynamics 365 Fraud Protection Service.

Dados da conta ou do instrumento de pagamento

Informações fraudulentas da conta ou do instrumento de pagamento identificadas pela sua equipe de revisão
Cenários de aquisição de conta que são escalados pelos seus clientes

Esquema da API

Atributo	Tipo	Description
labelObjectType	Enumeração Valores esperados: PURCHASE, ACCOUNTCREATION, ACCOUNTLOGIN, ACCOUNT, PI, EMAIL	Esse atributo indica a extensão com que você deseja sinalizar um rótulo. Por exemplo, você pode marcar uma única transação como fraudulenta ou marcar todas as transações de uma conta de usuário como fraudulentas. Dependendo do tipo de objeto, a Proteção contra Fraude sinaliza transações ou eventos relacionados como fraude ou não fraude. Por exemplo, se o valor labelObjectType for PURCHASE, ACCOUNTCREATION ou ACCOUNTLOGIN, a Proteção contra fraude rotulará transações específicas. Se o valor for CONTA ou PI, a Proteção contra Fraude sinaliza todas as transações relacionadas à conta do usuário ou instrumento de pagamento.
labelObjectId	String	O identificador que corresponde ao valor do atributo labelObjectType . A Proteção contra Fraude usa esse valor para encontrar transações e eventos relacionados. As IDs dos tipos de objeto de rótulo são as seguintes: COMPRA: purchaseId ACCOUNTCREATION: signupId ACCOUNTLOGIN: loginId CONTA: userId PI: merchantPaymentInstrumentId Este atributo é muito importante, porque a Proteção contra Fraude usa-o para identificar o evento de avaliação original. Portanto, o valor deve corresponder à transação original ou ID do evento.
labelFonte	String	A fonte de informação do rótulo. Alguns valores sugeridos são ManualReview se um rótulo de fraude for identificado pela equipe de revisão e CustomerEscalation se um cliente reclamar de uma transação falsamente rejeitada (em outras palavras, um falso positivo). Os dados TC40/SAFE são outra fonte de dados de rótulos.
isFraude	Boolean	Este atributo indica se o rótulo é fraudulento ou não fraudulento. Se nenhum valor for fornecido, a Proteção contra fraude usará true como o valor padrão.
reasonText	String	A razão para rotular algo de fraude ou não-fraude. Você pode ignorar os motivos com segurança se tiver informações limitadas sobre as fontes do rótulo. Como alternativa, dependendo dos fluxos de trabalho de rótulos, você pode mapear alguns cenários para alguns desses valores.
labelReasonCodes	String	Códigos de motivo normalizados ou códigos de motivo recebidos do processador de pagamento. Você pode ignorar esse atributo com segurança se não tiver detalhes do motivo. Alguns valores sugeridos são Código de Resposta do Processador, Código de Resposta Bancária, Reembolso de Fraude, Aquisição de Conta, Fraude de Instrumento de Pagamento, Fraude de Conta, Abuso, Fraude Amigável, Credenciais de Conta Vazadas e Verificações de Proteção de Conta Aprovadas.
labelState [en]	String	O tipo de rótulo que você está enviando. Esse atributo é usado especialmente se você estiver revertendo um sinal de fraude anterior ou falso positivo. Em ambos os casos, você definirá isFraud como false. No entanto, o Estado pode ajudar a identificar rótulos falsos positivos.
Processador	String	O nome do processador de pagamento.
eventTimeStamp	DateTime (formato ISO 8601)	O carimbo de data/hora identificado pelo rótulo. Se a API for integrada diretamente com o processo de deteção de rótulo e você chamar a API de rótulo assim que um agente de revisão sinalizar uma transação como fraude, o valor poderá ser o carimbo de data/hora atual. Esse valor é especialmente importante para determinar a ordem dos eventos quando há vários rótulos. Por exemplo, se uma transação de compra ou criação de conta for rotulada como fraude, mas posteriormente rotulada como não fraude, a Proteção contra Fraude fará referência a esse valor para determinar qual dos dois rótulos é mais recente e, portanto, correto.
effectiveStartDate	DateTime (formato ISO 8601)	As datas de início e término efetivas destinam-se a enriquecer rótulos que são mais amplos do que uma transação (e que geralmente têm um valor labelObjectType de ACCOUNT) para limitar o impacto desses rótulos a um período de tempo específico. Por exemplo, em cenários de comprometimento de conta, essas datas especificam o período de tempo no qual você deseja rotular as transações ou eventos.
effectiveEndDate	Formato DateTime (ISO 8601)	As datas de início e término efetivas destinam-se a enriquecer rótulos que são mais amplos do que uma transação (e que geralmente têm um valor labelObjectType de ACCOUNT) para limitar o impacto desse rótulo a um período de tempo específico. Por exemplo, em cenários de comprometimento de conta, essas datas especificam o período de tempo no qual você deseja rotular as transações ou eventos.
Montante	Duplo	O montante total da fraude. Você pode ignorar esse valor se nenhum valor estiver disponível. Por exemplo, em cenários de criação de conta e entrada, pode não haver um valor associado. No cenário de compra, a Proteção contra Fraude usará o valor da transação.
Moeda	String	O código de moeda de três caracteres da Organização Internacional de Normalização (ISO) que está relacionado com o montante.

Exemplos de cargas úteis de API para cenários comuns

Cenário 1

Sua equipe de revisão identificou transações suspeitas examinando as informações de pagamento.

{
    "labelObjectType": "PURCHASE",
    "labelObjectId": "<purchase transaction Id, i.e., purchaseId>",
    "labelSource": "ManualReview",
    "isFraud": true,
    "labelState": "Fraud",
    "eventTimeStamp": "2022-10-04T16:24:36.045Z",
    "_metadata": {
        "trackingId": "<guid or identifier>",
        "merchantTimeStamp": "2022-10-04T20:44:14.706Z"
    }
}

Cenário 2

Um usuário perdeu o acesso à sua conta e um ator mal-intencionado usou as credenciais desse usuário para entrar. Mais tarde, o usuário recuperou suas credenciais e relatou um intervalo de tempo comprometido.

{
    "labelObjectType": "ACCOUNT",
    "labelObjectId": "<userId>",
    "labelSource": "CustomerEscalation",
    "isFraud": true,
    "reasonText": "AccountCompromise",
    "labelState": "Fraud",
    "eventTimeStamp": "2022-10-04T12:21:46.326Z",
    "effectiveStartDate": "2022-10-03T10:00:00.000Z",
    "effectiveEndDate": "2022-10-04T12:16:00.000Z",
    "_metadata": {
        "trackingId": "<guid or identifier>",
        "merchantTimeStamp": "2022-10-04T12:21:46.326Z"
    }
}

Cenário 3

Você bloqueou um login de usuário suspeito e, mais tarde, o usuário chamou a equipe de suporte para ser desbloqueado. Se a equipe de suporte revisar as evidências, confirmar que o usuário é o usuário legítimo e desbloqueá-lo, você deverá enviar um rótulo que tenha um estado FalsePositive .

{
    "labelObjectType": "ACCOUNT",
    "labelObjectId": "<userId>",
    "labelSource": "CustomerEscalation",
    "isFraud": false,
    "reasonText": "AccountCompromise",
    "labelState": "FalsePositive",
    "eventTimeStamp": "2022-10-04T16:21:46.326Z",
    "_metadata": {
        "trackingId": "<guid or identifier>",
        "merchantTimeStamp": "2022-10-04T16:21:46.326Z"
    }
}

Partilhar via