> ## 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 d'ingestió d'esdeveniments - Monitoratge no monetari

> Envia activitat no monetària (inicis de sessió, jocs, bonificacions, pagaments, disputes) al motor de Didit que puntua les teves transaccions.

Les transaccions són els diners. Els esdeveniments són tota la resta que la teva plataforma sap: l'inici de sessió que va preceder la retirada, la mà que va moure fitxes entre dos comptes, la bonificació reclamada dues vegades, el retrocàrrec que va arribar una setmana més tard.

Els esdeveniments fan servir un únic sobre per a totes les categories, són idempotents per disseny i els avalua el [mateix motor de regles](https://docs.didit.me/ca/transaction-monitoring/event-rules.md) que puntua les teves [transaccions](https://docs.didit.me/ca/transaction-monitoring/transactions.md).

> [!NOTE]
>
> La ingestió d'esdeveniments és **opcional**. Activa-la a **Transaccions → Configuració → Monitoratge d'esdeveniments**.
> Fins que no ho facis, no canvia res: les teves regles de transaccions existents continuen aplicant-se només a les transaccions, i no es pot crear una regla d'esdeveniments per accident, perquè una regla s'aplica a les transaccions tret que incloguis explícitament els esdeveniments.
>
> Mentre estigui desactivada, cada via d'escriptura - `POST /v3/events/`, `POST /v3/events/batch/`, `POST /v3/events/sdk-token/` i la via de dispositiu `/v1/events/` - respon `403` amb `{"code": "event_monitoring_disabled"}`, i no s'emmagatzema, no s'enriqueix ni s'avalua res. Les lectures no es veuen afectades.

## Endpoints

| Endpoint | Autenticació | Per a què serveix |
| - | - | - |
| `POST /v3/events/` | Clau d'API | Un esdeveniment des del teu backend |
| `POST /v3/events/batch/` | Clau d'API | Fins a 500 esdeveniments en una sol·licitud |
| `POST /v3/events/sdk-token/` | Clau d'API | Generar una credencial de dispositiu amb abast limitat |
| `POST /v1/events/` | `X-Monitoring-Token` | Un esdeveniment des del SDK del dispositiu |
| `POST /v1/events/batch/` | `X-Monitoring-Token` | Un buffer del SDK buidat |
| `GET /v3/events/` | Clau d'API | Llistar i filtrar esdeveniments |
| `GET /v3/events/{event_uuid}/` | Clau d'API | Un esdeveniment amb les seves evidències de regla |
| `GET /v3/events/subjects/{vendor_data}/` | Clau d'API | La línia de temps d'un subjecte (vegeu `entity_type` més avall) |
| `GET /v3/events/enrichment-metrics/` | Clau d'API | Estat de la memòria cau de l'enriquiment d'IP |

La via `/v3/` és la via de servidor i fa servir la mateixa autenticació `x-api-key` que la resta de l'API de transaccions. La via `/v1/events/` és la via de dispositiu: vegeu [Enviament d'esdeveniments des del SDK](https://docs.didit.me/ca/transaction-monitoring/sdk-event-submission.md).

## El sobre

```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": []
}
```

| Camp | Obligatori | Notes |
| - | - | - |
| `event_id` | sí | El teu propi identificador, únic per aplicació. És la clau d'idempotència. |
| `event_category` | sí | Una de les deu categories següents. |
| `action_type` | sí | Cadena de text lliure, de fins a 128 caràcters. |
| `occurred_at` | sí | Quan va passar al teu costat. Fins a 7 dies en el passat i 5 minuts en el futur. |
| `subject.vendor_data` | sí | El teu identificador d'usuari. S'associa al mateix usuari al qual s'associaria una transacció. |
| `subject.entity_type` | no | `individual` (per defecte) o `company`. |
| `business.vendor_data` | no | L'empresa a la qual pertany l'esdeveniment. |
| `session` | no | `session_id`, `sequence`, `page_url`, `referrer`. |
| `device_context` | no | `fingerprint`, `persistent_device_id`, `bot_score` i `network_context.ip_address`. |
| `transaction_context` | no | `amount`, `currency`, `direction`, `payment_reference_id`. |
| `payload` | no | Els camps de domini de la categoria. Fins a 16 KB. |
| `custom_values` | no | Fins a 100 claus escalars, als quals es pot accedir des de les regles com a `custom_values.<key>`. |

## Categories

Deu categories de primer nivell, cadascuna amb validació tipada i [camps de regla](https://docs.didit.me/ca/transaction-monitoring/event-rules.md#camps-d’esdeveniments) gestionats.

| Categoria | Accions habituals |
| - | - |
| `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` | Qualsevol cosa que defineixis |

`auth` és la categoria general del producte; `security` és el subconjunt de grau de risc amb el cicle de vida ordenat que llegeixen les regles de presa de control de comptes.

### Claus de payload obligatòries

Algunes accions no es poden correlacionar sense claus específiques, de manera que la validació les rebutja en lloc d'emmagatzemar evidències que no es poden associar.

| Acció | Obligatòria |
| - | - |
| `gameplay.p2p_settlement` | `game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role`, i una de les opcions `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`, i una de les opcions `dispute_id` / `chargeback_id` |
| `security.*_changed` | `changed_field`; els canvis de control del compte o de pagaments també necessiten `previous_reference_hash` o `new_reference_hash` |
| `session.bot_signal_observed` | `telemetry_schema_version`, més un `bot_score` o com a mínim una mètrica de telemetria |
| `responsible_gambling.self_exclusion_match` | `registry_source`, `exclusion_status`, `identity_match_ref` |

> [!WARNING]
>
> Envia **referències i hashes**, mai secrets en brut. Els instruments de pagament, les destinacions de retirada i els canvis de control del compte s'emmagatzemen com la referència amb hash que envies. Mai no enviïs un número de targeta, una adreça de retirada completa, un hash de contrasenya ni un secret de MFA.

### Exemple: una liquidació 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"
  }
}
```

### Exemple: un contracàrrec

```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
  }
}
```

Els cicles de vida de les disputes només permeten afegir esdeveniments: una correcció és un nou esdeveniment `dispute`, mai una modificació del primer.

## Idempotència

`event_id` és únic per aplicació i és tot el contracte d'idempotència.

* **Mateix `event_id`, mateix contingut** retorna `200` amb `"idempotent_replay": true` i l'esdeveniment emmagatzemat originalment. Torna a intentar-ho tantes vegades com vulguis.
* **Mateix `event_id`, contingut diferent** retorna `409`. Has reutilitzat un identificador per error.

## Lots

`POST /v3/events/batch/` accepta fins a **500 esdeveniments**. Un lot té èxit parcial per disseny: una visualització de pàgina malformada mai no ha de fer caure el contracàrrec que hi ha al costat.

```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 resposta és `207 Multi-Status` quan se n'ha rebutjat algun i `201 Created` quan tot s'ha emmagatzemat.

## Estats

| Estat | Significat |
| - | - |
| `ACCEPTED` | Emmagatzemat. Cap regla no ha canviat la seva situació (és la resposta habitual per a la majoria d'esdeveniments). |
| `APPROVED` | S'ha executat una regla i la puntuació s'ha mantingut per sota del teu llindar de revisió. |
| `IN_REVIEW` | Una regla l'ha portat per sobre del llindar de revisió, o s'ha establert l'estat directament. |
| `DECLINED` | Una regla l'ha rebutjat. |

`correlation_pending: true` significa que encara s'ha d'executar una regla entre subjectes; es resol en pocs minuts i l'estat i la puntuació de l'esdeveniment s'actualitzen directament, sense crear un nou esdeveniment. Consulta [regles asíncrones](https://docs.didit.me/ca/transaction-monitoring/event-rules.md#regles-en-temps-real-i-asíncrones).

## Retenció

Els esdeveniments tenen un volum molt més alt que les transaccions, així que cadascun s'assigna a una classe de retenció en arribar.

| Classe | Retenció en calent per defecte | Què hi va a parar |
| - | - | - |
| `low_value` | 14 dies | Visualitzacions de pàgina, senyals de pulsació, senyals de dispositiu vist, telemetria de bots, visualitzacions de promocions |
| `standard` | 30 dies | Autenticació, sessió, joc, bonificació, afiliació, personalitzat |
| `risk_relevant` | 90 dies | Esdeveniments de seguretat i de joc responsable, i **qualsevol esdeveniment que hagi coincidit amb una regla** |
| `monetary_or_compliance` | Retenció de transaccions | Esdeveniments de pagament i de disputa |

Dues regles es deriven de la taula:

* Un esdeveniment que coincideix amb una regla és una evidència, així que es promou automàticament a `risk_relevant`.
* Els esdeveniments de pagament i de disputa conserven la retenció de transaccions. Mai no caduquen segons la planificació d'esdeveniments, i les substitucions per classe no les poden escurçar.

Anul·la les tres classes que poden caducar per aplicació a **Transactions → Settings → Event monitoring** (d'1 a 730 dies cadascuna).

## Enriquiment d'IP

Els esdeveniments porten el mateix [enriquiment d'IP](https://docs.didit.me/ca/transaction-monitoring/ip-enrichment.md) que les transaccions: país, ASN, indicadors de VPN/proxy i de centre de dades. L'enriquiment es resol **per adreça IP única, mai per esdeveniment**. Una sessió que genera 200 visualitzacions de pàgina des d'una mateixa adreça resol aquesta adreça una sola vegada.

La telemetria de baix valor va més enllà: només llegeix l'enriquiment si algun altre esdeveniment ja ha resolt aquella adreça. Mai no activa una consulta pròpia.

`GET /v3/events/enrichment-metrics/` informa del resultat, i la consola mostra els mateixos números sobre la llista d'esdeveniments:

```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
}
```

## Consultar els esdeveniments

```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"
```

Filtres: `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`. Els filtres de valors múltiples repeteixen el paràmetre (`?status=A&status=B`).

### Cronologia d'un subjecte

```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` només és únic **dins** d'un tipus d'entitat: el mateix identificador pot correspondre a un usuari i a una empresa, i Didit els resol com a dos subjectes diferents. `entity_type` indica quin dels dos demanes: `individual` (el valor per defecte) o `company`. Si l'omets amb un identificador d'empresa, es retorna la cronologia de la persona, no de totes dues. S'hi apliquen els mateixos filtres de llista.

`GET /v3/events/{event_uuid}/` afegeix el payload, el context del dispositiu, l'enriquiment de la IP, els senyals de risc en memòria cau del subjecte i cada coincidència de regla amb la seva evidència, incloent-hi si cada camp coincident era derivat del servidor, derivat del SDK o proporcionat pel client.

`DELETE /v3/events/{event_uuid}/delete/` elimina un esdeveniment. Deixa de retornar-se en qualsevol lectura, i l'eliminació és irreversible.

## Següent

> [card] [Regles sobre esdeveniments](https://docs.didit.me/ca/transaction-monitoring/event-rules.md)
>
> Regles de velocitat, de ràtio, de seqüència i de correlació sobre les dades dels esdeveniments.

> [card] [Enviament d'esdeveniments amb el SDK](https://docs.didit.me/ca/transaction-monitoring/sdk-event-submission.md)
>
> Captura esdeveniments directament des del dispositiu amb una credencial limitada.


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