API di ingestione eventi - Monitoraggio non monetario

Le transazioni sono il denaro. Gli eventi sono tutto il resto che la tua piattaforma conosce: il login che ha preceduto il prelievo, la mano che ha spostato le fiches tra due conti, il bonus riscosso due volte, il chargeback arrivato una settimana dopo. Gli eventi usano un’unica struttura per tutte le categorie, sono progettati per essere idempotenti e vengono valutati dallo stesso motore di regole che assegna il punteggio alle tue transazioni.

L’acquisizione degli eventi è opt-in. Attivala in Transactions → Settings → Event monitoring. Finché non la attivi, nulla cambia: le regole sulle transazioni esistenti continuano ad attivarsi solo sulle transazioni, e non è possibile creare per errore una regola sugli eventi, perché una regola si applica alle transazioni a meno che tu non includa esplicitamente gli eventi.Finché l’acquisizione non è attiva, ogni canale di scrittura - POST /v3/events/, POST /v3/events/batch/, POST /v3/events/sdk-token/ e il canale del dispositivo /v1/events/ - risponde 403 con {"code": "event_monitoring_disabled"}, e nulla viene memorizzato, arricchito o valutato. Le letture non sono interessate.

Endpoint

Endpoint	Autenticazione	Da usare per
`POST /v3/events/`	Chiave API	Un evento dal tuo backend
`POST /v3/events/batch/`	Chiave API	Fino a 500 eventi in una sola richiesta
`POST /v3/events/sdk-token/`	Chiave API	Generare una credenziale del dispositivo con ambito limitato
`POST /v1/events/`	`X-Monitoring-Token`	Un evento dall’SDK del dispositivo
`POST /v1/events/batch/`	`X-Monitoring-Token`	Un buffer SDK svuotato
`GET /v3/events/`	Chiave API	Elencare e filtrare gli eventi
`GET /v3/events/{event_uuid}/`	Chiave API	Un evento con le relative evidenze delle regole
`GET /v3/events/subjects/{vendor_data}/`	Chiave API	La cronologia di un soggetto (vedi `entity_type` sotto)
`GET /v3/events/enrichment-metrics/`	Chiave API	Stato della cache di arricchimento IP

Il canale /v3/ è il canale server e usa la stessa autenticazione x-api-key del resto dell’API delle transazioni. Il canale /v1/events/ è il canale del dispositivo - vedi Invio di eventi dall’SDK.

La struttura

curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'

{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}

Campo	Obbligatorio	Note
`event_id`	sì	Il tuo identificatore, unico per applicazione. È la chiave di idempotenza.
`event_category`	sì	Una delle dieci categorie elencate sotto.
`action_type`	sì	Stringa libera, fino a 128 caratteri.
`occurred_at`	sì	Quando si è verificato nel tuo sistema. Fino a 7 giorni nel passato, 5 minuti nel futuro.
`subject.vendor_data`	sì	Il tuo ID utente. Viene associato allo stesso utente a cui verrebbe associata una transazione.
`subject.entity_type`	no	`individual` (predefinito) o `company`.
`business.vendor_data`	no	L’azienda a cui appartiene l’evento.
`session`	no	`session_id`, `sequence`, `page_url`, `referrer`.
`device_context`	no	`fingerprint`, `persistent_device_id`, `bot_score` e `network_context.ip_address`.
`transaction_context`	no	`amount`, `currency`, `direction`, `payment_reference_id`.
`payload`	no	I campi di dominio della categoria. Fino a 16 KB.
`custom_values`	no	Fino a 100 chiavi scalari, accessibili nelle regole come `custom_values.<key>`.

Categorie

Dieci categorie di primo livello, ciascuna con validazione tipizzata e campi delle regole gestiti.

Categoria	Azioni tipiche
`auth`	`signup`, `login`, `login_failed`, `logout`, `password_forgot`, `password_reset`, `mfa_reset`, `mfa_challenge`
`session`	`session_started`, `session_ended`, `page_view`, `sdk_loaded`, `device_seen`, `bot_signal_observed`, `sdk_heartbeat`
`gameplay`	`round_started`, `round_completed`, `bet_placed`, `bet_settled`, `cashout`, `limit_change`, `p2p_settlement`
`bonus`	`bonus_claimed`, `bonus_wagered`, `bonus_released`, `promotion_viewed`
`affiliate`	`affiliate_attributed`, `referral_clicked`, `campaign_joined`, `commission_event`
`payment`	`deposit_initiated`, `deposit_completed`, `withdrawal_requested`, `withdrawal_completed`, `withdrawal_address_changed`, `payment_instrument_seen`
`dispute`	`chargeback_opened`, `chargeback_won`, `chargeback_lost`, `refund_issued`, `payment_dispute_updated`
`security`	`login_attempt`, `login_succeeded`, `login_failed`, `password_changed`, `mfa_changed`, `credential_reset`, `country_changed`, `device_changed`, `account_locked`
`responsible_gambling`	`self_exclusion_checked`, `self_exclusion_match`, `re_registration_attempt`, `limit_breach_attempt`, `registry_status_changed`
`custom`	Qualsiasi cosa tu definisca

auth è la categoria di prodotto generale; security è il sottoinsieme di rischio con il ciclo di vita ordinato utilizzato dalle regole contro la presa di controllo dell’account.

Chiavi obbligatorie del payload

Alcune azioni non possono essere correlate senza chiavi specifiche, quindi la validazione le rifiuta invece di memorizzare prove che nessuno può collegare.

Azione	Obbligatorio
`gameplay.p2p_settlement`	`game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role`, e uno tra `hand_id` / `round_id` / `match_id`
`gameplay.bet_placed`, `gameplay.bet_settled`	`game_id`
`payment.deposit_*`, `payment.withdrawal_completed`, `payment.withdrawal_requested`, `payment.deposit_initiated`	`payment_reference_id`, `amount`, `currency`, `payment_method`, `status`
`payment.withdrawal_address_changed`	`withdrawal_address_hash`
`dispute.chargeback_*`	`payment_reference_id`, e uno tra `dispute_id` / `chargeback_id`
`security.*_changed`	`changed_field`; anche le modifiche al controllo dell’account o dei pagamenti in uscita richiedono `previous_reference_hash` o `new_reference_hash`
`session.bot_signal_observed`	`telemetry_schema_version`, più un `bot_score` o almeno una metrica di telemetria
`responsible_gambling.self_exclusion_match`	`registry_source`, `exclusion_status`, `identity_match_ref`

Invia riferimenti e hash, mai segreti in chiaro. Gli strumenti di pagamento, le destinazioni di prelievo e le modifiche al controllo dell’account vengono memorizzati come riferimento con hash che invii. Non inviare mai un numero di carta, un indirizzo di prelievo completo, un hash della password o un segreto MFA.

Esempio: un regolamento P2P

{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}

Esempio: un chargeback

{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}

I cicli di vita delle dispute consentono solo aggiunte: una correzione è un nuovo evento dispute, mai una modifica del primo evento.

Idempotenza

event_id è univoco per applicazione e costituisce l’intero contratto di idempotenza.

Stesso event_id, stesso contenuto restituisce 200 con "idempotent_replay": true e l’evento memorizzato originariamente. Puoi effettuare nuovi tentativi quante volte vuoi.
Stesso event_id, contenuto diverso restituisce 409. Hai riutilizzato un id per errore.

Batch

POST /v3/events/batch/ accetta fino a 500 eventi. Un batch è parzialmente riuscito per progettazione: una visualizzazione di pagina malformata non deve mai compromettere il chargeback accanto a essa.

{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}

La risposta è 207 Multi-Status quando viene rifiutato qualcosa e 201 Created quando tutti gli eventi sono stati inseriti correttamente.

Stati

Stato	Significato
`ACCEPTED`	Memorizzato. Nessuna regola ha modificato il suo stato (è la risposta normale per la maggior parte degli eventi).
`APPROVED`	Una regola è stata eseguita e il punteggio è rimasto sotto la soglia di revisione.
`IN_REVIEW`	Una regola lo ha portato sopra la soglia di revisione, oppure ha impostato direttamente lo stato.
`DECLINED`	Una regola lo ha rifiutato.

correlation_pending: true significa che deve ancora essere eseguita una regola tra soggetti diversi; si risolve entro pochi minuti e lo stato e il punteggio dell’evento vengono aggiornati direttamente. Vedi regole asincrone.

Conservazione

Gli eventi hanno volumi molto più alti delle transazioni, quindi ciascuno viene assegnato a una classe di conservazione al momento dell’arrivo.

Classe	Conservazione a caldo predefinita	Cosa finisce qui
`low_value`	14 giorni	Visualizzazioni di pagina, heartbeat, segnalazioni di dispositivo visto, telemetria bot, visualizzazioni di promozioni
`standard`	30 giorni	Auth, sessione, gameplay, bonus, affiliate, custom
`risk_relevant`	90 giorni	Eventi di sicurezza e di gioco responsabile, e qualsiasi evento corrispondente a una regola
`monetary_or_compliance`	Conservazione delle transazioni	Eventi di pagamento e di disputa

Due regole derivano dalla tabella:

Un evento che corrisponde a una regola è una prova, quindi viene promosso automaticamente a risk_relevant.
Gli eventi di pagamento e di disputa mantengono la conservazione delle transazioni. Non scadono mai secondo la pianificazione degli eventi e le sostituzioni per classe non possono ridurla.

Configura le sostituzioni per le tre classi a scadenza per applicazione in Transactions → Settings → Event monitoring (da 1 a 730 giorni ciascuna).

Arricchimento IP

Gli eventi includono lo stesso arricchimento IP delle transazioni: paese, ASN, flag VPN/proxy e flag dei data center. L’arricchimento viene risolto per indirizzo IP univoco, mai per evento. Una sessione che genera 200 visualizzazioni di pagina da un solo indirizzo risolve quell’indirizzo una sola volta. La telemetria a basso valore va oltre: legge l’arricchimento solo se un altro evento ha già risolto quell’indirizzo. Non avvia mai una ricerca autonoma. GET /v3/events/enrichment-metrics/ riporta il risultato, e la console mostra gli stessi numeri sopra l’elenco degli eventi:

{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}

Lettura degli eventi

curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"

Filtri: event_category, action_type, status, retention_class, subject_vendor_data, business_vendor_data, session_id, device_fingerprint, ip_address, game_id, round_id, affiliate_code, payment_reference_id, counterparty_vendor_data, matched_only, occurred_from, occurred_to, search. I filtri con più valori ripetono il parametro (?status=A&status=B).

Cronologia di un soggetto

curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"

Un vendor_data è univoco solo all’interno di un tipo di entità: lo stesso ID può indicare un utente e un’azienda, e Didit li tratta come due soggetti diversi. entity_type indica quale dei due stai richiedendo: individual (il valore predefinito) o company. Se lo ometti con un ID di azienda, viene restituita la cronologia dell’individuo, non entrambe. Si applicano gli stessi filtri dell’elenco. GET /v3/events/{event_uuid}/ aggiunge il payload, il contesto del dispositivo, l’arricchimento IP, i segnali di rischio memorizzati nella cache del soggetto e ogni corrispondenza di regola con le relative evidenze, incluso se ciascun campo corrispondente è stato derivato dal server, dall’SDK o fornito dal cliente. DELETE /v3/events/{event_uuid}/delete/ elimina un evento. Non viene più restituito da nessuna lettura, e l’eliminazione è irreversibile.

Avanti

Regole sugli eventi

Regole di velocità, rapporto, sequenza e correlazione sui dati degli eventi.

Invio di eventi tramite SDK

Acquisisci gli eventi direttamente dal dispositivo con una credenziale limitata.

Primi passi

Funzionalità

Riferimento

Console

API di ingestione eventi - Monitoraggio non monetario

Endpoint

La struttura

Categorie

Chiavi obbligatorie del payload

Esempio: un regolamento P2P

Esempio: un chargeback

Idempotenza

Batch

Stati

Conservazione

Arricchimento IP

Lettura degli eventi

Cronologia di un soggetto

Avanti

Regole sugli eventi

Invio di eventi tramite SDK

​Endpoint

​La struttura

​Categorie

​Chiavi obbligatorie del payload

​Esempio: un regolamento P2P

​Esempio: un chargeback

​Idempotenza

​Batch

​Stati

​Conservazione

​Arricchimento IP

​Lettura degli eventi

​Cronologia di un soggetto

​Avanti

Regole sugli eventi

Invio di eventi tramite SDK

Endpoint

La struttura

Categorie

Chiavi obbligatorie del payload

Esempio: un regolamento P2P

Esempio: un chargeback

Idempotenza

Batch

Stati

Conservazione

Arricchimento IP

Lettura degli eventi

Cronologia di un soggetto

Avanti