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

A maioria dos eventos 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

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.

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.

As regras são executadas como habitualmente

O evento é enriquecido, agregado e avaliado pelas mesmas regras que as aplicadas a um evento enviado pelo servidor.

Emissão de uma credencial

Para emitir uma credencial, é necessário que a ingestão de eventos 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.

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

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

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

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

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.

Primeiros passos

Funcionalidades

Referência

Consola

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

Fluxo

Emissão de uma credencial

Envio

O que o servidor impõe

Envio em lote

O que descartar em caso de contrapressão

Compatibilidade de cabeçalhos

Escolher a via

Próximos passos

Ingestão de eventos

Regras sobre eventos

​Fluxo

​Emissão de uma credencial

​Envio

​O que o servidor impõe

​Envio em lote

​O que descartar em caso de contrapressão

​Compatibilidade de cabeçalhos

​Escolher a via

​Próximos passos

Ingestão de eventos

Regras sobre eventos

Fluxo

Emissão de uma credencial

Envio

O que o servidor impõe

Envio em lote

O que descartar em caso de contrapressão

Compatibilidade de cabeçalhos

Escolher a via

Próximos passos