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

# Submissão de eventos SDK: captura no lado do cliente

> Capture eventos de início de sessão, jogo e sessão no dispositivo com a Didit e uma credencial limitada. Vinculação aplicada no servidor.

A maioria dos [eventos](https://docs.didit.me/pt/transaction-monitoring/events.md) que importam para a deteção de fraude acontece no dispositivo: o início de sessão, a sessão, a ronda de jogo e a telemetria temporal que distingue uma pessoa de um script. A via do dispositivo envia estes eventos sem colocar uma chave de API num navegador.

O seu backend emite uma credencial de vida curta limitada a um único utilizador, e a aplicação envia os eventos com essa credencial.

## Fluxo

**1. Emitir uma credencial de monitorização**

O seu backend chama `POST /v3/events/sdk-token/` com a sua chave de API e o `vendor_data` do utilizador.

**2. Enviar a partir do dispositivo**

A aplicação envia para `POST /v1/events/` (ou `POST /v1/events/batch/`) com o cabeçalho `X-Monitoring-Token`.

**3. As regras são executadas como habitualmente**

O evento é enriquecido, agregado e avaliado pelas mesmas [regras](https://docs.didit.me/pt/transaction-monitoring/event-rules.md) que as aplicadas a um evento enviado pelo servidor.

## Emissão de uma credencial

> [!NOTE]
>
> Para emitir uma credencial, é necessário que a [ingestão de eventos](https://docs.didit.me/pt/transaction-monitoring/events.md) esteja ativada para a aplicação. Enquanto estiver desativada, este endpoint responde com `403` e `{"code": "event_monitoring_disabled"}`, em vez de entregar uma credencial que nunca poderia escrever eventos.

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

| Campo | Predefinição | Notas |
| - | - | - |
| `vendor_data` | obrigatório | O sujeito a que pertencem todos os eventos enviados com esta credencial. |
| `entity_type` | `individual` | `individual` ou `company`. |
| `allowed_event_categories` | todas | Restringe o que uma credencial divulgada poderia escrever. |
| `ttl_seconds` | 900 | 60 - 86400. |
| `max_uses` | 1000 | Uma utilização por **evento**, e não por pedido. |
| `bind_to_origin` | nenhum | Quando definido, o `Origin` do navegador tem de corresponder exatamente. |

## Envio

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

Repare no que o payload **não** inclui: nem chave de API, nem sujeito. Ambos são impostos pelo servidor.

## O que o servidor impõe

* **Vinculação do sujeito.** A credencial fica limitada a um único `vendor_data` no momento da emissão. Um bloco `subject` no corpo do pedido é substituído, pelo que um cliente adulterado não consegue escrever na linha temporal de outro utilizador.
* **Contexto de rede.** O endereço IP, o user agent, o accept-language e o origin são obtidos a partir do pedido, e estes valores derivados pelo servidor prevalecem sobre qualquer indicação do cliente na avaliação das regras. A evidência da regra regista a diferença como [origem do campo](https://docs.didit.me/pt/transaction-monitoring/event-rules.md#evidência).
* **Âmbito de categorias.** Uma credencial limitada a `session` não pode enviar um evento `payment`; o pedido é rejeitado com `400`.
* **Orçamento de utilizações.** Um lote gasta uma utilização por evento, pelo que um lote de 500 eventos não pode passar por uma credencial de 10 utilizações como se fosse uma única utilização.
* **Vinculação à origem.** Quando `bind_to_origin` está definido, um pedido cujo `Origin` não corresponde é recusado, incluindo um pedido que não tenha `Origin`.

## Envio em lote

```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": [ { "…": "…" }, { "…": "…" } ] }'
```

Até 500 eventos por envio, com os mesmos resultados por item do [endpoint de lote do servidor](https://docs.didit.me/pt/transaction-monitoring/events.md#lotes). Um envio predefinido razoável ocorre a cada 25 eventos, após 5 segundos ou quando a página ou a aplicação passa para segundo plano.

### O que descartar em caso de contrapressão

Se tiver de descartar eventos, descarte os de menor custo. Estes podem ser descartados em segurança:

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

Estes não são seguros para descartar: envie-os primeiro.

todos os eventos `security`, `payment`, `dispute` e `responsible_gambling`, bem como `gameplay.bet_placed`, `gameplay.bet_settled` e `gameplay.p2p_settlement`.

Os endpoints de listagem devolvem, para cada evento, a mesma classificação indicada por `is_droppable`, para que um cliente possa basear-se nela em vez de uma cópia fixa no código.

## Compatibilidade de cabeçalhos

O cabeçalho canónico é `X-Monitoring-Token`. `X-Transaction-Token` é aceite como alias temporário, para que uma aplicação que já use um caminho de credencial de transação possa migrar gradualmente.

> [!WARNING]
>
> O alias é transitório e será removido antes de a API de eventos chegar à disponibilidade geral. No código novo, envie `X-Monitoring-Token`.

## Escolher a via

| | Via do dispositivo | Via do servidor |
| - | - | - |
| Endpoint | `POST /v1/events/` | `POST /v3/events/` |
| Autenticação | `X-Monitoring-Token` | `x-api-key` |
| Sujeito | Vinculado à credencial | No payload |
| Ideal para | Inícios de sessão, sessões, jogabilidade, telemetria | Pagamentos, disputas, eventos derivados do livro-razão, preenchimentos retroativos |

Ambas produzem registos de evento idênticos e executam as mesmas regras. Use a via do servidor sempre que não houver nenhum utilizador final presente.

## Próximos passos

> [card] [Ingestão de eventos](https://docs.didit.me/pt/transaction-monitoring/events.md)
>
> O envelope, as categorias, a retenção e a idempotência.

> [card] [Regras sobre eventos](https://docs.didit.me/pt/transaction-monitoring/event-rules.md)
>
> Regras de velocidade, de rácio, de sequência e de correlação.


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