API etichette

Articolo
02/24/2025

Importante

A partire dal 3 febbraio 2025, Dynamics 365 Fraud Protection non è più disponibile per l'acquisto. Il supporto per la protezione delle frodi terminerà il 3 febbraio 2026. Per altre informazioni, vedere l'articolo Fine del supporto per Dynamics 365 Fraud Protection.

Questo articolo illustra come l'API delle etichette consente di inviare informazioni ai dashboard di report e monitoraggio in Microsoft Dynamics 365 Fraud Protection.

L'API delle etichette consente di inviare segnali di frode o non frode a Fraud Protection. Questi dati vengono utilizzati per il training del modello, la valutazione delle prestazioni del modello e la creazione di report. L'API delle etichette è un'API generica che etichetta gli eventi di valutazione utilizzando singole transazioni o ID evento o entità come utente o strumento di pagamento.

Scenari di etichette comuni per transazioni o eventi

Tutte le transazioni fraudolente sottoposte a escalation dai clienti
Attività fraudolenta o uso improprio di account identificati dal team di verifica
Qualsiasi analisi offline (come analisi di comportamento o connessioni scoperte a casi di frodi esistenti)
Segnali TC40/SAFE ricevuti
Annullamento di un precedente segnale di frode dopo che è stato identificato come non frode in base alle ultime informazioni disponibili
Rifiuti di addebito/rimborsi ricevuti
Annullamento di un rifiuto di addebito dopo una controversia

È consigliabile utilizzare l'API per il rifiuto di addebito o rimborso per fornire informazioni pertinenti a rifiuti di addebito e rimborsi. Per ulteriori informazioni sugli eventi supportati, vedi Servizio Dynamics 365 Fraud Protection.

Dettagli su account o strumenti di pagamento

Informazioni su account o strumenti di pagamento fraudolenti identificati dal team di verifica
Scenari di appropriazione di account sottoposti a escalation dai clienti

Schema API

Attributo	Tipo	Description
labelObjectType	Enum Valori previsti: PURCHASE, ACCOUNTCREATION, ACCOUNTLOGIN, ACCOUNT, PI, EMAIL	Questo attributo indica quanto vuoi sia esteso il contrassegno di un'etichetta. Ad esempio, è consigliabile contrassegnare una singola transazione come fraudolenta oppure contrassegnare tutte le transazioni di un account utente come fraudolente. A seconda del tipo di oggetto, Fraud Protection contrassegna le transazioni o gli eventi correlati come frode o non frode. Ad esempio, se il valore labelObjectType è PURCHASE, ACCOUNTCREATION o ACCOUNTLOGIN, Fraud Protection etichetta transazioni specifiche. Se il valore è ACCOUNT o PI, Fraud Protection contrassegna tutte le transazioni relative all'account utente o allo strumento di pagamento.
labelObjectId	Stringa	L'identificatore che corrisponde al valore dell'attributo labelObjectType. Fraud Protection utilizza questo valore per trovare transazioni ed eventi correlati. Gli ID dei tipi di oggetto etichetta sono i seguenti: PURCHASE: purchaseId ACCOUNTCREATION: signupId ACCOUNTLOGIN: loginId ACCOUNT: userId PI: merchantPaymentInstrumentId Questo attributo è molto importante, perché Fraud Protection lo utilizza per identificare l'evento di valutazione originale. Pertanto, il valore deve corrispondere alla transazione originale o all'ID evento.
labelSource	Stringa	L'origine delle informazioni sull'etichetta. Alcuni valori suggeriti sono Revisione manuale se un'etichetta di frode viene identificata dal team di revisione, e Escalation del cliente se un cliente si lamenta di una transazione falsamente rifiutata (in altre parole, un falso positivo). I dati TC40/SAFE sono un'altra origine per i dati delle etichette.
isFraud	Booleano	Questo attributo indica se l'etichetta è frode o non è frode. Se non viene fornito alcun valore, Fraud Protection utilizza vero come valore predefinito.
reasonText	Stringa	Il motivo per etichettare qualcosa come frode o non frode. Puoi tranquillamente ignorare i motivi se disponi di informazioni limitate sulle origini dell'etichetta. In alternativa, a seconda dei flussi di lavoro delle etichette, puoi eseguire il mapping di alcuni scenari ad alcuni di questi valori.
labelReasonCodes	Stringa	Codici motivo normalizzati o codici motivo ricevuti dal processore di pagamento. Puoi tranquillamente ignorare questo attributo se non hai i dettagli del motivo. Alcuni valori suggeriti sono Codice risposta processore, Codice risposta banca, Rimborso frode, Acquisizione account, Frode strumento di pagamento, Frode account, Abuso, Frode inintenzionale, Credenziali account fuoriuscite e Controlli protezione account superati.
labelState	Stringa	Il tipo di etichetta che stai inviando. Questo attributo viene utilizzato soprattutto se stai annullando un precedente segnale di frode o falso positivo. In entrambi i casi, sarai tu a impostare isFraud su falso. Tuttavia, lo stato può aiutare a identificare le etichette false positive.
Processore	Stringa	Il nome del processore di pagamento.
eventTimeStamp	DateTime (formato ISO 8601)	Il timestamp identificato dall'etichetta. Se l'API è integrata direttamente con il processo di rilevamento dell'etichetta e chiami l'API dell'etichetta non appena un agente di revisione segnala una transazione come frode, il valore può essere il timestamp corrente. Questo valore è particolarmente importante per determinare l'ordine degli eventi quando sono presenti più etichette. Ad esempio, se una transazione di acquisto o di creazione di un account viene etichettata come frode ma viene successivamente etichettata come non fraudolenta, Fraud Protection farà riferimento a questo valore per determinare quale delle due etichette è più recente e quindi corretta.
effectiveStartDate	DateTime (formato ISO 8601)	Le date effettive di inizio e fine hanno lo scopo di arricchire le etichette che si estendono su più di una transazione (e che di solito hanno un valore labelObjectType di ACCOUNT) per limitare l'impatto di tali etichette a un periodo di tempo specifico. Ad esempio, negli scenari di compromissione dell'account, queste date specificano l'intervallo di tempo in cui si desidera etichettare le transazioni o gli eventi.
effectiveEndDate	Formato DateTime (ISO 8601)	Le date effettive di inizio e fine hanno lo scopo di arricchire le etichette che si estendono su più di una transazione (e che di solito hanno un valore labelObjectType di ACCOUNT) per limitare l'impatto di tale etichetta a un periodo di tempo specifico. Ad esempio, negli scenari di compromissione dell'account, queste date specificano l'intervallo di tempo in cui si desidera etichettare le transazioni o gli eventi.
Importo	Double	Importo totale della frode. Puoi ignorare questo valore se nessun importo è disponibile. Ad esempio, negli scenari di creazione e accesso dell'account, potrebbe non esserci un importo associato. Nello scenario di acquisto, Fraud Protection utilizzerà l'importo della transazione.
Valuta	Stringa	Il codice valuta a tre caratteri dell'organizzazione internazionale per la standardizzazione (ISO) correlato all'importo.

Payload API di esempio per scenari comuni

Scenario 1

Il tuo team di revisione ha identificato le transazioni sospette esaminando le informazioni di 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"
    }
}

Scenario 2

Un utente ha perso l'accesso al proprio account e un attore malintenzionato ha utilizzato le credenziali dell'utente per accedere. Successivamente, l'utente ha recuperato le proprie credenziali e ha segnalato un intervallo di tempo in cui è stato compromesso.

{
    "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"
    }
}

Scenario 3

Hai bloccato l'accesso di un utente sospetto e in seguito l'utente ha chiamato il team di supporto per essere sbloccato. Se il team di supporto esamina le prove, conferma che l'utente è legittimo e sblocca l'utente, è necessario inviare un'etichetta con uno stato Falso positivo.

{
    "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"
    }
}

Condividi tramite