> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API di ingestione eventi - Monitoraggio non monetario

> Invia attività non monetarie (login, gioco, bonus, pagamenti, contestazioni, sicurezza account) al motore Didit che valuta le transazioni.

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](https://docs.didit.me/it/transaction-monitoring/event-rules.md) che assegna il punteggio alle tue [transazioni](https://docs.didit.me/it/transaction-monitoring/transactions.md).

> [!NOTE]
>
> 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](https://docs.didit.me/it/transaction-monitoring/sdk-event-submission.md).

## La struttura

```bash theme={null}
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" }
  }'
```

```json theme={null}
{
  "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](https://docs.didit.me/it/transaction-monitoring/event-rules.md#campi-degli-eventi) 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` |

> [!WARNING]
>
> 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://docs.didit.me/it/transaction-monitoring/event-rules.md#in-tempo-reale-e-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](https://docs.didit.me/it/transaction-monitoring/ip-enrichment.md) 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:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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

> [card] [Regole sugli eventi](https://docs.didit.me/it/transaction-monitoring/event-rules.md)
>
> Regole di velocità, rapporto, sequenza e correlazione sui dati degli eventi.

> [card] [Invio di eventi tramite SDK](https://docs.didit.me/it/transaction-monitoring/sdk-event-submission.md)
>
> Acquisisci gli eventi direttamente dal dispositivo con una credenziale limitata.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.