API de Rótulos

Artigo
07/29/2024

Este artigo explica como a API de rótulos permite que você envie informações para os painéis de relatório e monitoramento no Microsoft Dynamics 365 Fraud Protection.

A API de etiquetas permite que você envie sinais de fraude ou não fraude para o Fraud Protection. Esses dados são usados para treinamento de modelo, avaliação de desempenho de modelo e relatórios. A API de etiquetas é uma API geral que rotula eventos de avaliação usando IDs de transação ou evento individuais ou entidades como usuário ou meio de pagamento.

Cenários de etiquetas comuns para transações ou eventos

Quaisquer transações fraudulentas encaminhadas por seus clientes
Atividade fraudulenta ou abuso de conta identificado por sua equipe de análise
Qualquer análise offline (como análise de comportamento ou conexões descobertas com casos de fraude existentes)
Sinais TC40/SAFE que são recebidos
Reversão de um sinal de fraude anterior após ser identificado como não fraude com base nas informações mais recentes disponíveis
Estornos/reembolsos recebidos
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 com suporte, consulte Serviço do Dynamics 365 Fraud Protection.

Detalhes da conta ou instrumento de pagamento

Informações fraudulentas da conta ou meio de pagamento identificadas pela sua equipe de análise
Cenários de tomada de conta encaminhados por seus clientes

Esquema de API

Atributo	Tipo	Descrição
labelObjectType	Enum Valores esperados: PURCHASE, ACCOUNTCREATION, ACCOUNTLOGIN, ACCOUNT, PI, EMAIL	Esse atributo indica o quanto você deseja sinalizar uma etiqueta. Por exemplo, talvez você queira 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, o Fraud Protection sinaliza transações ou eventos relacionados como fraude ou não fraude. Por exemplo, se o valor labelObjectType for PURCHASE, ACCOUNTCREATION ou ACCOUNTLOGIN, o Fraud Protection rotula transações específicas. Se o valor for ACCOUNT ou PI, o Fraud Protection sinaliza todas as transações relacionadas à conta do usuário ou instrumento de pagamento.
labelObjectId	Cadeia de caracteres	O identificador que corresponde ao valor do atributo labelObjectType. O Fraud Protection usa esse valor para localizar transações e eventos relacionados. As IDs dos tipos de objeto de etiqueta são os seguintes: PURCHASE: purchaseId ACCOUNTCREATION: signupId ACCOUNTLOGIN: loginId ACCOUNT: userId PI: merchantPaymentInstrumentId Esse atributo é muito importante, pois o Fraud Protection o utiliza para identificar o evento de avaliação original. Portanto, o valor deve corresponder à transação original ou ID do evento.
labelSource	Cadeia de caracteres	A fonte de informações da etiqueta. Alguns valores sugeridos são ManualReview se uma etiqueta de fraude for identificada 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 de TC40/SAFE são outra fonte de dados de etiqueta.
isFraud	Booliano	Este atributo indica se o rótulo é fraude ou não fraude. Se nenhum valor for fornecido, o Fraud Protection usará true como valor padrão.
reasonText	Cadeia de caracteres	O motivo para etiquetar algo como fraude ou não fraude. Você pode ignorar os motivos com segurança se tiver informações limitadas sobre suas fontes de etiquetas. Como alternativa, dependendo de seus fluxos de trabalho de etiqueta, é possível mapear alguns cenários para alguns desses valores.
labelReasonCodes	Cadeia de caracteres	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 do Banco, Reembolso de Fraude, Tomada de Conta, Fraude de Meio de Pagamento, Fraude de Conta, Abuso, Fraude Amigável, Credenciais da Conta Vazadas e Verificações de Proteção da Conta Aprovadas.
labelState	Cadeia de caracteres	O tipo de etiqueta 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. Contudo, o estado pode ajudar a identificar rótulos falsos positivos.
Processador	Cadeia de caracteres	O nome do processador de pagamento.
eventTimeStamp	DateTime (formato ISO 8601)	O carimbo de data/hora identificado pela etiqueta. Se a API estiver integrada diretamente ao processo de detecção de etiquetas e você chamar a API de etiquetas 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árias etiquetas. Por exemplo, se uma transação de compra ou criação de conta for etiquetada como fraude, mas posteriormente etiquetada como não fraude, o Fraud Protection se referirá a esse valor para determinar qual das duas etiquetas é mais recente e, portanto, correto.
effectiveStartDate	DateTime (formato ISO 8601)	As datas efetivas de início e término destinam-se a enriquecer etiquetas maiores que uma transação (e que geralmente têm um valor labelObjectType de ACCOUNT) para limitar o impacto dessas etiquetas a um período específico. Por exemplo, em cenários de comprometimento de conta, essas datas especificam o período no qual você deseja etiquetas as transações ou eventos.
effectiveEndDate	Formato DateTime (ISO 8601)	As datas efetivas de início e término destinam-se a enriquecer etiquetas maiores que uma transação (e que geralmente têm um valor labelObjectType de ACCOUNT) para limitar o impacto dessa etiqueta a um período específico. Por exemplo, em cenários de comprometimento de conta, essas datas especificam o período no qual você deseja etiquetas as transações ou eventos.
Valor	Duplo	O valor total da fraude. É possível ignorar esse valor se nenhum valor estiver disponível. Por exemplo, em cenários de criação e entrada de conta, pode não haver um valor associado. No cenário de compra, o Fraud Protection usará o valor da transação.
Moeda	Cadeia de caracteres	O código de moeda da Organização Internacional de Normalização (ISO) de três caracteres que está relacionado ao valor.

Exemplos de cargas de API para cenários comuns

Cenário 1

Sua equipe de revisão identificou transações suspeitas analisando 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 agente mal-intencionado usou as credenciais desse usuário para fazer o logon. Posteriormente, 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 as credenciais de um usuário suspeito e, depois, este entrou em contato com a equipe de suporte solicitando o desbloqueio. 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 uma etiqueta com o 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"
    }
}

Compartilhar via