> ## 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 per crear esdeveniments de monitoratge
> Envia des del teu backend un esdeveniment de login, joc, bonificació, pagament, disputa o seguretat perquè Didit l'emmagatzemi i el puntuï.
Crea un prompt de l'API d'esdeveniments de monitoratge
Copia el prompt al porta-retalls
\
\`Send one non-monetary monitoring event (login, session, gameplay, bonus, affiliate, payment, dispute, security, responsible gambling or custom) from my backend to Didit.
Endpoint:
POST https://verification.didit.me/v3/events/
Authentication:
Use the x-api-key header with my Didit API key, from my backend only. A scoped key needs transactions: write.
Goal:
\- Record what happened on my platform so Didit's event rules can score it alongside my transactions, and read the verdict from the response.
Request body (application/json):
\{
"event_id": "login-2026-10-17-000001", // required - my id, unique per application, the idempotency key (max 128)
"event_category": "auth", // required - auth, session, gameplay, bonus, affiliate, payment, dispute, security, responsible_gambling, custom
"action_type": "login", // required - what happened inside the category (max 128)
"occurred_at": "2026-10-17T09:15:02.481Z", // required - at most 7 days in the past, 5 minutes in the future
"subject": { "vendor_data": "user-42", "entity_type": "individual" }, // required - entity_type individual (default) or company
"session": { "session_id": "web-session-abc", "sequence": 142 },
"device_context": { "fingerprint": "didit-fp-v2:a8c1", "network_context": { "ip_address": "203.0.113.42" } },
"transaction_context": { "amount": "1000.00", "currency": "EUR", "payment_reference_id": "dep_735" },
"payload": { "method": "password" }, // category fields, max 16 KB
"custom_values": { "vip_tier": "gold" } // max 100 scalar keys
}
Behavior:
\- Validated, stored, IP-enriched and evaluated by the real-time event rules before the response returns. Cross-subject and long-window rules run asynchronously within minutes (correlation_pending: true).
\- Some actions require payload keys, for example gameplay.p2p_settlement (game_id, counterparty_vendor_data, stake_amount, net_result_amount, role, and one of hand_id, round_id, match_id), payment.deposit_completed (payment_reference_id, amount, currency, payment_method, status) and dispute.chargeback_opened (payment_reference_id and one of dispute_id, chargeback_id). transaction_context keys count towards these requirements.
\- Send hashes and references, never a card number, a full withdrawal address, a password hash or an MFA secret.
\- Idempotency: the same event_id with the same event_category, action_type, occurred_at, subject.vendor_data and payload returns 200 with idempotent_replay true and the stored event's result. Different values in those fields return 409; the other fields are not compared. Retry safely on timeouts.
\- The IP address used for enrichment and rules is device_context.network_context.ip_address as you send it.
\- In a sandbox application no rules run: status is ACCEPTED and rules_evaluated_count is 0.
\- The subject resolves to the user (or company) with that vendor_data; one is created when none exists.
\- Event ingestion is opt-in: until it is switched on in Transactions > Settings > Event monitoring, this call returns 403 with code event_monitoring_disabled and stores nothing.
Example call:
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-10-17-000001","event_category":"auth","action_type":"login","occurred_at":"2026-10-17T09:15:02.481Z","subject":{"vendor_data":"user-42"},"device_context":{"network_context":{"ip_address":"203.0.113.42"}},"payload":{"method":"password"}}'
What to read from the response:
\- event_uuid - Didit id of the stored event.
\- status - ACCEPTED (stored, no rule changed it), APPROVED, IN_REVIEW or DECLINED.
\- score, rules_evaluated_count, rules_matched_count, rule_matches[] (rule_id, library_key, mode, is_async).
\- correlation_pending - when true, read GET /v3/events/{event_uuid}/ later for the final status.
\- retention_class and expires_at (null for payment and dispute events).
\- idempotent_replay - true when the event was already stored.
Failure modes:
\- 400 - validation error keyed by field (missing field, occurred_at outside the window, payload over 16 KB, nested custom_values, missing required payload keys).
\- 401 - the API key has expired.
\- 403 - missing API key (a wrong, revoked or expired key gets 401), a scoped key without transactions: write, or code event_monitoring_disabled.
\- 409 - event_id reused with different content; use a new event_id.
\- 429 - more than 600 ingestion requests per minute for this API key (event and transaction ingestion share this budget, apart from the 300 of every other write); honor Retry-After.
Side effects: stores the event, may create the subject's user or company, and applies the actions of matched active rules (score, status, tags, notes, list entries, cases).
For the full integration shape, see /integration/integration-prompt.`
\
Enganxa a
> [!NOTE]
>
> L'ingestió d'esdeveniments és opcional. Activa-la a **Transactions > Settings > Event monitoring** abans d'enviar esdeveniments; fins aleshores, aquest endpoint respon amb `403` i `"code": "event_monitoring_disabled"`.[Ingestió d'esdeveniments](https://docs.didit.me/ca/transaction-monitoring/events.md) explica l'embolcall, les deu categories, les claus obligatòries del payload i les classes de conservació. [Regles sobre esdeveniments](https://docs.didit.me/ca/transaction-monitoring/event-rules.md) explica quines regles s'executen durant la sol·licitud i quines s'executen de manera asíncrona. Per enviar esdeveniments des d'un navegador o una aplicació en lloc del teu backend, fes servir [Enviament d'esdeveniments amb el SDK](https://docs.didit.me/ca/transaction-monitoring/sdk-event-submission.md).
## OpenAPI
````yaml ca/openapi-25.json POST /v3/events/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/events/:
post:
tags:
- Monitoring Events
summary: Crea un esdeveniment de monitoratge
description: >-
Envia un esdeveniment no monetari (inici de sessió, sessió, joc,
bonificació, afiliat, pagament, disputa, seguretat, joc responsable o
personalitzat) des del teu backend. L'esdeveniment es valida contra el
contracte de la seva categoria, s'emmagatzema, s'enriqueix per IP un cop
per cada adreça pública única i s'avalua mitjançant les teves regles
d'esdeveniments en temps real abans de retornar la resposta; les regles
que creuen subjectes o amb finestres temporals llargues s'executen de
manera asíncrona (`correlation_pending: true`), i en una aplicació de
sandbox no s'executa cap regla. `event_id` és la clau d'idempotència: el
mateix `event_id` amb els mateixos valors de `event_category`,
`action_type`, `occurred_at`, `subject.vendor_data` i `payload` retorna
`200` amb `idempotent_replay: true` i el resultat emmagatzemat (els
altres camps de l'embolcall no es comparen), mentre que si els valors
són diferents es retorna `409`. La ingesta d'esdeveniments és opcional
per aplicació: fins que no s'activa, aquest endpoint retorna `403` amb
`code: event_monitoring_disabled` i no emmagatzema res. Una clau d'API
amb àmbit necessita `transactions: write`. Consulta [Ingesta
d'esdeveniments](https://docs.didit.me/ca/transaction-monitoring/events)
i [Regles sobre
esdeveniments](https://docs.didit.me/ca/transaction-monitoring/event-rules);
per enviar esdeveniments des d'un navegador o una aplicació, utilitza
[Enviament d'esdeveniments amb
l'SDK](https://docs.didit.me/ca/transaction-monitoring/sdk-event-submission).
operationId: create_monitoring_event
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventCreateRequest'
examples:
Login:
value:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
Deposit completed:
value:
event_id: deposit-2026-10-17-000002
event_category: payment
action_type: deposit_completed
occurred_at: '2026-10-17T09:16:40Z'
subject:
vendor_data: user-42
transaction_context:
amount: '100.00'
currency: EUR
direction: inbound
payment_reference_id: dep_736
payload:
payment_method: card
status: completed
Chargeback opened:
value:
event_id: chargeback-2026-10-16-000318
event_category: dispute
action_type: chargeback_opened
occurred_at: '2026-10-16T14:02:11Z'
subject:
vendor_data: user-42
payload:
payment_reference_id: dep_735
chargeback_id: cb_5521
amount: '250.00'
currency: EUR
reason_code: fraud
responses:
'200':
description: >-
Repetició idempotent: ja hi ha emmagatzemat un esdeveniment amb
aquest `event_id` i el mateix contingut. No s'ha emmagatzemat ni
avaluat res de nou; el cos descriu l'esdeveniment emmagatzemat.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Replay:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: true
rule_matches: []
'201':
description: L'esdeveniment s'ha emmagatzemat i avaluat.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Stored, no rule matched:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: false
rule_matches: []
Rule matched, async rule pending:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: IN_REVIEW
score: 40
rules_evaluated_count: 6
rules_matched_count: 1
correlation_pending: true
retention_class: risk_relevant
expires_at: '2027-01-15T09:15:02.481000Z'
idempotent_replay: false
rule_matches:
- rule_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
library_key: null
mode: ACTIVE
is_async: false
'400':
description: >-
La validació ha fallat. El cos està indexat per camp; els camps
niats són objectes niats. No s'emmagatzema res.
content:
application/json:
examples:
Missing fields:
value:
event_id:
- This field is required.
subject:
- This field is required.
Unknown category:
value:
event_category:
- '"login" is not a valid choice.'
occurred_at too old:
value:
occurred_at:
- >-
occurred_at is more than 7 days in the past. Use the
batch import lane for backfills.
occurred_at in the future:
value:
occurred_at:
- occurred_at is more than 5 minutes in the future.
Missing subject vendor_data:
value:
subject:
vendor_data:
- This field is required.
Missing required payload keys:
value:
payload:
- >-
payment.deposit_completed requires: payment_method,
status.
Missing one-of payload key:
value:
payload:
- >-
dispute.chargeback_opened requires one of: dispute_id,
chargeback_id.
Security change without changed_field:
value:
payload:
- security.*_changed requires 'changed_field'.
Payload too large:
value:
payload:
- >-
payload exceeds 16384 bytes. Summarise telemetry
client-side.
Too many custom_values:
value:
custom_values:
- custom_values accepts at most 100 keys.
Nested custom value:
value:
custom_values:
- >-
custom_values['limits'] must be a scalar - rule
conditions cannot address nested values.
'401':
description: >-
La clau d'API amb abast ha caducat. Només una clau caducada rep
`401`; una clau absent o no vàlida rep `403`.
content:
application/json:
examples:
Expired key:
value:
detail: This API key has expired.
'403':
description: >-
Falta la capçalera `x-api-key` (una clau incorrecta, revocada o
caducada rep un `401`), una clau amb àmbit sense `transactions:
write`, una clau limitada a determinats fluxos de treball o a
sessions aprovades (aquesta clau mai no accedeix a dades de
monitoratge de transaccions), o una sol·licitud des de fora de la
llista d'adreces IP permeses de la clau. També es retorna amb `code:
event_monitoring_disabled` mentre la ingesta d'esdeveniments estigui
desactivada per a l'aplicació; en aquest cas no s'emmagatzema res, i
la comprovació s'executa abans de validar el cos.
content:
application/json:
examples:
Event monitoring disabled:
value:
detail: >-
Event monitoring is not enabled for this application. Turn
on event ingestion in the transaction monitoring settings
before submitting events.
code: event_monitoring_disabled
Missing or invalid API key:
value:
detail: You do not have permission to perform this action.
Scoped key without access:
value:
detail: This API key has no write access to transactions.
Key limited to workflows or approved sessions:
value:
detail: >-
This API key only reaches sessions inside its workflow or
status limits, so it can't use this endpoint.
IP not allowed:
value:
detail: This API key can't be used from this IP address.
'409':
description: >-
`event_id` ja s'ha utilitzat per a un esdeveniment amb contingut
diferent (categoria, tipus d'acció, `occurred_at`, `vendor_data` del
subjecte o payload). Envia l'esdeveniment sota un `event_id` nou.
content:
application/json:
examples:
event_id reused:
value:
event_id: >-
event_id 'login-2026-10-17-000001' already exists with a
different payload.
'429':
description: >-
S'ha superat el límit de freqüència: les creacions de transaccions i
la ingesta d'esdeveniments (`POST /v3/transactions/`, `POST
/v3/events/`, `POST /v3/events/batch/`) comparteixen un pressupost
de 600 sol·licituds per minut per clau d'API, independent de les 300
que comparteixen la resta de sol·licituds d'escriptura. Espera els
segons indicats a `Retry-After` i reintenta-ho.
headers:
Retry-After:
description: >-
Segons d'espera abans de reintentar, arrodonits a l'alça perquè
el reintent caigui a la finestra següent.
schema:
type: integer
minimum: 1
example: 30
content:
application/json:
examples:
Throttled:
value:
detail: >-
Ingestion rate limit exceeded. You can make up to 600
requests per minute.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
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-10-17-000001",
"event_category": "auth",
"action_type": "login",
"occurred_at": "2026-10-17T09:15:02.481Z",
"subject": {"vendor_data": "user-42", "entity_type": "individual"},
"session": {"session_id": "web-session-abc", "sequence": 142},
"device_context": {
"fingerprint": "fp-a8c1",
"network_context": {"ip_address": "203.0.113.42"}
},
"payload": {"method": "password"}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.monitoring_events.create(
event_id="login-2026-10-17-000001",
event_category="auth",
action_type="login",
occurred_at="2026-10-17T09:15:02.481Z",
time_zone="Europe/Madrid",
subject={
"vendor_data": "user-42",
"entity_type": "individual",
},
session={
"session_id": "web-session-abc",
"sequence": 142,
},
device_context={
"fingerprint": "fp-a8c1",
"network_context": {
"ip_address": "203.0.113.42",
},
},
payload={"method": "password"},
custom_values={"vip_tier": "gold"},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.monitoringEvents.create({
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" },
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.time.OffsetDateTime;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.MonitoringEventCreateRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.monitoringEvents().create(MonitoringEventCreateRequest.builder()
.eventId("login-2026-10-17-000001")
.eventCategory(MonitoringEventCreateRequest.EventCategory.of("auth"))
.actionType("login")
.occurredAt(OffsetDateTime.parse("2026-10-17T09:15:02.481Z"))
.timeZone("Europe/Madrid")
.subject(MonitoringEventCreateRequest.Subject.builder()
.vendorData("user-42")
.entityType("individual")
.build())
.session(MonitoringEventCreateRequest.Session.builder()
.sessionId("web-session-abc")
.sequence(142L)
.build())
.deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()
.fingerprint("fp-a8c1")
.networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()
.ipAddress("203.0.113.42")
.build())
.build())
.payload(Map.of("method", "password"))
.customValues(Map.of("vip_tier", MonitoringEventCreateRequest.CustomValuesValue.ofString("gold")))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
monitoringEvents->create([
'event_id' => 'login-2026-10-17-000001',
'event_category' => 'auth',
'action_type' => 'login',
'occurred_at' => '2026-10-17T09:15:02.481Z',
'time_zone' => 'Europe/Madrid',
'subject' => [
'vendor_data' => 'user-42',
'entity_type' => 'individual',
],
'session' => [
'session_id' => 'web-session-abc',
'sequence' => 142,
],
'device_context' => [
'fingerprint' => 'fp-a8c1',
'network_context' => [
'ip_address' => '203.0.113.42',
],
],
'payload' => ['method' => 'password'],
'custom_values' => ['vip_tier' => 'gold'],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.monitoring_events.create(
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" }
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.MonitoringEvents.CreateAsync(new
MonitoringEventCreateRequest
{
EventId = "login-2026-10-17-000001",
EventCategory = "auth",
ActionType = "login",
OccurredAt = DateTimeOffset.Parse("2026-10-17T09:15:02.481Z"),
TimeZone = "Europe/Madrid",
Subject = new()
{
VendorData = "user-42",
EntityType = "individual",
},
Session = new MonitoringEventCreateRequestSession
{
SessionId = "web-session-abc",
Sequence = 142,
},
DeviceContext = new MonitoringEventCreateRequestDeviceContext
{
Fingerprint = "fp-a8c1",
NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext
{
IpAddress = "203.0.113.42",
},
},
Payload = new Dictionary { ["method"] = "password" },
CustomValues = new Dictionary { ["vip_tier"] = "gold" },
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
MonitoringEventCreateRequest:
type: object
description: >-
El sobre de l'esdeveniment, el mateix per a cada categoria. S'accepten
àlies en camelCase: `eventId`, `eventCategory` (o `category`),
`actionType`, `occurredAt`, `timeZone` (o `zoneId`), `deviceContext` (o
`device`), `transactionContext`, `customValues` (o `props`); dins de
`subject`: `vendorData`, `entityType`, `fullName`; dins de `session`:
`sessionId`, `pageUrl`; dins de `transaction_context`:
`paymentReferenceId`.
required:
- event_id
- event_category
- action_type
- occurred_at
- subject
properties:
event_id:
type: string
maxLength: 128
description: >-
El teu identificador per a l'esdeveniment, únic per aplicació. És la
clau d'idempotència: reenviar els mateixos `event_category`,
`action_type`, `occurred_at`, `subject.vendor_data` i `payload` amb
aquest identificador és una repetició; qualsevol diferència és un
conflicte.
example: login-2026-10-17-000001
event_category:
type: string
enum:
- auth
- session
- gameplay
- bonus
- affiliate
- payment
- dispute
- security
- responsible_gambling
- custom
description: Categoria de l'esdeveniment.
example: auth
action_type:
type: string
minLength: 1
maxLength: 128
description: >-
Què ha passat dins de la categoria. Vocabulari obert; les accions
gestionades llistades a [Event
ingestion](https://docs.didit.me/ca/transaction-monitoring/events)
(per exemple, `login`, `deposit_completed`, `chargeback_opened`)
desbloquegen la validació tipada i els camps de regles gestionades.
S'eliminen els espais en blanc inicials i finals.
example: login
occurred_at:
type: string
format: date-time
description: >-
Quan va ocórrer l'esdeveniment al teu costat, ISO 8601 (un valor
sense decalatge es llegeix com a UTC). No ha de ser de més de 7 dies
en el passat ni de més de 5 minuts en el futur.
example: '2026-10-17T09:15:02.481Z'
time_zone:
type: string
nullable: true
maxLength: 64
description: >-
Zona horària de l'ocurrència al teu costat, per exemple
`Europe/Madrid`. S'emmagatzema amb l'esdeveniment; no la retornen
els endpoints de lectura.
subject:
type: object
description: >-
L'usuari o empresa a qui pertany l'esdeveniment. Es resol en
l'usuari (o empresa) amb aquest `vendor_data` a la teva aplicació;
se'n crea un quan no n'hi ha cap.
required:
- vendor_data
properties:
vendor_data:
type: string
minLength: 1
maxLength: 255
description: El teu id per al subjecte.
example: user-42
entity_type:
type: string
maxLength: 32
default: individual
description: >-
`company` resol el subjecte com a empresa; qualsevol altre valor
(per defecte `individual`) el resol com a particular. El mateix
`vendor_data` en pot anomenar un de cada.
example: individual
full_name:
type: string
nullable: true
maxLength: 512
description: >-
Nom visible, utilitzat només quan aquest esdeveniment crea
l'usuari o l'empresa.
email:
type: string
format: email
nullable: true
description: >-
Validat com a adreça de correu electrònic; no s'emmagatzema a
l'esdeveniment.
phone:
type: string
nullable: true
maxLength: 32
description: Validat; no s'emmagatzema a l'esdeveniment.
country:
type: string
nullable: true
maxLength: 3
description: Validat; no s'emmagatzema a l'esdeveniment.
business:
type: object
description: >-
L'empresa a la qual pertany l'esdeveniment, quan difereix del
subjecte. Només es llegeix `vendor_data`.
additionalProperties: true
properties:
vendor_data:
type: string
maxLength: 255
description: >-
El teu id per a l'empresa. Es pot filtrar com a
`business_vendor_data`.
example: merchant-7
session:
type: object
description: El context de la teva sessió per a l'esdeveniment.
properties:
session_id:
type: string
nullable: true
maxLength: 255
description: >-
El teu identificador de sessió. Filtrable i retornat com a
`session_id`.
sequence:
type: integer
nullable: true
description: >-
Posició de l'esdeveniment dins de la sessió. Es retorna com a
`session_sequence`.
page_url:
type: string
nullable: true
maxLength: 2048
description: Validat; no s'emmagatzema a l'esdeveniment.
referrer:
type: string
nullable: true
maxLength: 2048
description: Validat; no s'emmagatzema a l'esdeveniment.
device_context:
type: object
additionalProperties: true
description: >-
Context del dispositiu i de la xarxa, emmagatzemat tal com s'ha
enviat i retornat per `GET /v3/events/{event_uuid}/`. En aquesta via
de servidor Didit no veu la connexió de l'usuari final, de manera
que l'adreça IP enriquida i utilitzada per les regles és
`network_context.ip_address` tal com l'envies.
properties:
fingerprint:
type: string
maxLength: 255
description: >-
Petjada digital del dispositiu. Es pot filtrar com a
`device_fingerprint`.
persistent_device_id:
type: string
maxLength: 255
description: El teu identificador de dispositiu persistent.
bot_score:
type: integer
description: Puntuació de bot de la teva pròpia detecció, com a enter.
network_context:
type: object
additionalProperties: true
properties:
ip_address:
type: string
maxLength: 64
description: >-
Adreça IP de l'usuari final. Les adreces públiques
s'enriqueixen una vegada per adreça única.
example: 203.0.113.42
transaction_context:
type: object
description: >-
Context monetari. Els valors no buits d'aquí també satisfan les
claus de payload requerides de l'acció.
properties:
amount:
type: string
nullable: true
description: Import com a cadena decimal (també s'accepta un número).
example: '1000.00'
currency:
type: string
nullable: true
maxLength: 10
description: Codi de moneda.
direction:
type: string
nullable: true
maxLength: 16
description: >-
Direcció del moviment de diners, per exemple `inbound` o
`outbound`.
payment_reference_id:
type: string
nullable: true
maxLength: 255
description: >-
La teva referència de pagament. Filtrable com a
`payment_reference_id`.
payload:
type: object
additionalProperties: true
description: >-
Els camps de domini de la categoria, com a màxim 16384 bytes un cop
codificats en JSON. Algunes accions requereixen claus (a `payload` o
`transaction_context`): `gameplay.p2p_settlement` necessita
`game_id`, `counterparty_vendor_data`, `stake_amount`,
`net_result_amount`, `role` i un de `hand_id`, `round_id`,
`match_id`; `gameplay.bet_placed` i `gameplay.bet_settled`
necessiten `game_id`; `payment.deposit_initiated`,
`payment.deposit_completed`, `payment.withdrawal_requested` i
`payment.withdrawal_completed` necessiten `payment_reference_id`,
`amount`, `currency`, `payment_method`, `status`;
`payment.withdrawal_address_changed` necessita
`withdrawal_address_hash`; `dispute.chargeback_opened`,
`dispute.chargeback_won` i `dispute.chargeback_lost` necessiten
`payment_reference_id` i un de `dispute_id`, `chargeback_id`;
`session.bot_signal_observed` necessita `telemetry_schema_version` i
un de `bot_score`, `actions_per_minute`, `timing_variance_ms`,
`pointer_entropy`, `keystroke_entropy`, `reaction_time_ms_p50`;
`responsible_gambling.self_exclusion_match` necessita
`registry_source`, `exclusion_status`, `identity_match_ref`. Tota
acció de `security` que acabi en `_changed` necessita
`changed_field`, a més de `previous_reference_hash` o
`new_reference_hash` quan el camp és `password`, `mfa_method`,
`mfa`, `email`, `phone`, `withdrawal_address`, `payout_method` o
`api_key`. Envia valors hash i referències, mai un número de
targeta, una adreça de retirada completa, un hash de contrasenya o
un secret MFA.
custom_values:
type: object
description: >-
Fins a 100 claus pròpies, accessibles des de les regles com a
`custom_values.`. Els valors han de ser escalars (string,
number, boolean o null); es rebutgen els objectes niats i les
matrius.
additionalProperties:
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
example:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
MonitoringEventIngestResult:
type: object
description: >-
Resultat de la ingesta d'un esdeveniment. Es retorna la mateixa
estructura tant per a un esdeveniment nou com per a una repetició
idempotent.
required:
- event_uuid
- event_id
- status
- score
- rules_evaluated_count
- rules_matched_count
- correlation_pending
- retention_class
- expires_at
- idempotent_replay
- rule_matches
properties:
event_uuid:
type: string
format: uuid
description: Identificador de Didit de l'esdeveniment emmagatzemat.
event_id:
type: string
description: El teu `event_id`.
status:
type: string
enum:
- ACCEPTED
- APPROVED
- IN_REVIEW
- DECLINED
description: >-
Estat després d'executar les regles en temps real. Consulta
`MonitoringEvent.status`.
score:
type: integer
description: Puntuació després de l'execució de les regles en temps real.
rules_evaluated_count:
type: integer
minimum: 0
description: >-
Nombre de regles d'esdeveniment avaluades a la sol·licitud. 0 en una
aplicació de sandbox, on no s'executa cap regla.
rules_matched_count:
type: integer
minimum: 0
description: >-
Nombre de regles que han coincidit, incloses les regles en mode
`TEST`.
correlation_pending:
type: boolean
description: >-
`true` quan encara s'ha d'executar una regla asíncrona. Consulta
`GET /v3/events/{event_uuid}/` uns minuts més tard per obtenir els
valors definitius de `status` i `score`.
retention_class:
type: string
enum:
- low_value
- standard
- risk_relevant
- monetary_or_compliance
description: >-
Classe de conservació de dades, després de qualsevol promoció per
una regla que hagi coincidit.
expires_at:
type: string
format: date-time
nullable: true
description: >-
Quan l'esdeveniment caduca segons la seva classe de conservació i
s'elimina. Null per a esdeveniments `monetary_or_compliance`
(pagaments i disputes).
idempotent_replay:
type: boolean
description: >-
`true` quan ja s'havia emmagatzemat un esdeveniment amb aquest
`event_id` i el mateix contingut; els valors són els de
l'esdeveniment emmagatzemat i no s'ha tornat a executar cap regla.
rule_matches:
type: array
description: Regles que han coincidit amb l'esdeveniment.
items:
type: object
required:
- rule_id
- library_key
- mode
- is_async
properties:
rule_id:
type: string
format: uuid
description: UUID de la regla.
library_key:
type: string
nullable: true
description: >-
Clau de la biblioteca quan la regla es va instal·lar des de la
biblioteca de regles; en cas contrari, null.
mode:
type: string
enum:
- ACTIVE
- TEST
description: >-
Les regles `TEST` registren la coincidència però no apliquen
cap acció.
is_async:
type: boolean
description: '`true` quan la coincidència prové de la passada asíncrona.'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
La clau d'API de la teva aplicació, des de Developers -> API keys a la
Business Console. La clau primària té accés complet. Una clau amb nom
pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
limitada a determinats fluxos de treball o a sessions aprovades, a una
llista d'adreces IP i a una data de caducitat. 401 significa que la clau
és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
clau, que la clau no té accés a aquest recurs o acció, o que la
sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
ruta de sessió significa que la sessió està fora dels fluxos de treball
o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
URL d'imatge, vídeo i PDF com a null, i una clau sense permís
d'escriptura de sessions rep els enllaços de sessió i els tokens com a
null. Consulta https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.