> ## 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.

# Enviament d'esdeveniments des del client amb SDK

> Captura inicis de sessió, activitat de joc i sessions des del dispositiu amb una credencial acotada. Didit aplica el vincle i la xarxa al servidor.

La majoria dels [esdeveniments](https://docs.didit.me/ca/transaction-monitoring/events.md) que importen per al frau passen al dispositiu: l'inici de sessió, la sessió, la partida de joc, la telemetria temporal que distingeix una persona d'un script. La via del dispositiu els envia sense posar una clau d'API en un navegador.

El teu backend emet una credencial de vida curta limitada a un sol usuari; l'aplicació envia els esdeveniments amb aquesta credencial.

## Flux

**1. Emet una credencial de monitoratge**

El teu backend crida `POST /v3/events/sdk-token/` amb la teva clau d'API i el `vendor_data` de l'usuari.

**2. Envia des del dispositiu**

L'aplicació envia una sol·licitud a `POST /v1/events/` (o `POST /v1/events/batch/`) amb la capçalera `X-Monitoring-Token`.

**3. Les regles s'executen com sempre**

L'esdeveniment s'enriqueix, s'agrega i s'avalua amb exactament les mateixes [regles](https://docs.didit.me/ca/transaction-monitoring/event-rules.md) que un esdeveniment enviat des del servidor.

## Emissió d'una credencial

> [!NOTE]
>
> Per emetre una credencial cal tenir activada l'[ingesta d'esdeveniments](https://docs.didit.me/ca/transaction-monitoring/events.md) a l'aplicació. Mentre estigui desactivada, aquest endpoint respon amb `403` i `{"code": "event_monitoring_disabled"}` en lloc de lliurar una credencial que mai no podria escriure.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'
```

```json theme={null}
{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}
```

| Camp | Valor per defecte | Notes |
| - | - | - |
| `vendor_data` | obligatori | El subjecte al qual pertanyen tots els esdeveniments enviats amb aquesta credencial. |
| `entity_type` | `individual` | `individual` o `company`. |
| `allowed_event_categories` | totes | Restringeix el que podria escriure una credencial filtrada. |
| `ttl_seconds` | 900 | 60 - 86400. |
| `max_uses` | 1000 | Un ús per **esdeveniment**, no per sol·licitud. |
| `bind_to_origin` | cap | Quan s'activa, el `Origin` del navegador ha de coincidir exactament. |

## Enviament

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'
```

Fixa't en el que el payload **no** conté: ni clau d'API, ni subjecte. Tots dos els aplica el servidor.

## Què aplica el servidor

* **Vinculació al subjecte.** La credencial queda limitada a un `vendor_data` concret en el moment de l'emissió. Un bloc `subject` al cos de la sol·licitud se sobreescriu, de manera que un client manipulat no pot escriure a la línia de temps d'un altre usuari.
* **Context de xarxa.** L'adreça, l'agent d'usuari, l'accept-language i l'origen es deriven de la sol·licitud, i aquests valors derivats pel servidor prevalen sobre qualsevol pista del client per a l'avaluació de regles. L'evidència de la regla registra la diferència com a [font del camp](https://docs.didit.me/ca/transaction-monitoring/event-rules.md#evidència).
* **Abast per categoria.** Una credencial limitada a `session` no pot enviar un esdeveniment `payment`; es rebutja amb `400`.
* **Pressupost d'usos.** Un lot gasta un ús per esdeveniment, de manera que un lot de 500 esdeveniments no pot passar com si fos un sol ús per a una credencial de 10 usos.
* **Vinculació a l'origen.** Quan s'activa `bind_to_origin`, es rebutja qualsevol sol·licitud el `Origin` de la qual no coincideixi, inclosa una que no tingui cap `Origin`.

## Enviament per lots

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'
```

Fins a 500 esdeveniments per enviament, amb els mateixos resultats per element que l'[endpoint de lots del servidor](https://docs.didit.me/ca/transaction-monitoring/events.md#lots). Un valor per defecte raonable és enviar cada 25 esdeveniments, cada 5 segons, o quan la pàgina o l'aplicació passa a segon pla.

### Què descartar amb contrapressió

Si cal descartar esdeveniments, descarta els més barats. Aquests es poden descartar sense risc:

`session.page_view` · `session.sdk_heartbeat` · `session.sdk_loaded` · `session.device_seen` · `session.bot_signal_observed` · `bonus.promotion_viewed` · `affiliate.referral_clicked`

Aquests no, envia'ls primer: tots els esdeveniments de `security`, `payment`, `dispute` i `responsible_gambling`, i també `gameplay.bet_placed`, `gameplay.bet_settled` i `gameplay.p2p_settlement`.

Els endpoints de llistat retornen la mateixa classificació per esdeveniment mitjançant el camp `is_droppable`, de manera que un client pot basar-se en aquest camp en lloc d'una còpia codificada.

## Compatibilitat de capçaleres

La capçalera canònica és `X-Monitoring-Token`. `X-Transaction-Token` s'accepta com a àlies temporal perquè una aplicació que ja té una via de credencial de transacció pugui migrar de manera progressiva.

> [!WARNING]
>
> L'àlies és transitori i s'eliminarà abans que l'API d'esdeveniments arribi a disponibilitat general. Envia `X-Monitoring-Token` en el codi nou.

## Triar una via

| | Via del dispositiu | Via del servidor |
| - | - | - |
| Endpoint | `POST /v1/events/` | `POST /v3/events/` |
| Autenticació | `X-Monitoring-Token` | `x-api-key` |
| Subjecte | Vinculat a la credencial | Al payload |
| Ideal per a | Inicis de sessió, sessions, joc, telemetria | Pagaments, disputes, esdeveniments derivats del registre comptable, càrregues retroactives |

Totes dues vies generen registres d'esdeveniments idèntics i executen les mateixes regles. Fes servir la via del servidor sempre que no hi hagi cap usuari final present.

## Següents passos

> [card] [Ingesta d'esdeveniments](https://docs.didit.me/ca/transaction-monitoring/events.md)
>
> El sobre, les categories, la conservació i la idempotència.

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


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