API d'ingestió d'esdeveniments - Monitoratge no monetari

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 que puntua les teves transaccions.

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.

El sobre

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

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

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

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

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

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

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 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:

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

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

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

Regles sobre esdeveniments

Regles de velocitat, de ràtio, de seqüència i de correlació sobre les dades dels esdeveniments.

Enviament d'esdeveniments amb el SDK

Captura esdeveniments directament des del dispositiu amb una credencial limitada.

Primers passos

Funcionalitats

Referència

Consola

API d'ingestió d'esdeveniments - Monitoratge no monetari

Endpoints

El sobre

Categories

Claus de payload obligatòries

Exemple: una liquidació P2P

Exemple: un contracàrrec

Idempotència

Lots

Estats

Retenció

Enriquiment d’IP

Consultar els esdeveniments

Cronologia d’un subjecte

Següent

Regles sobre esdeveniments

Enviament d'esdeveniments amb el SDK

​Endpoints

​El sobre

​Categories

​Claus de payload obligatòries

​Exemple: una liquidació P2P

​Exemple: un contracàrrec

​Idempotència

​Lots

​Estats

​Retenció

​Enriquiment d’IP

​Consultar els esdeveniments

​Cronologia d’un subjecte

​Següent

Regles sobre esdeveniments

Enviament d'esdeveniments amb el SDK

Endpoints

El sobre

Categories

Claus de payload obligatòries

Exemple: una liquidació P2P

Exemple: un contracàrrec

Idempotència

Lots

Estats

Retenció

Enriquiment d’IP

Consultar els esdeveniments

Cronologia d’un subjecte

Següent