Envio de eventos pelo SDK - Captura de eventos no cliente

A maioria dos eventos relevantes para fraude acontece no dispositivo: o login, a sessão, a rodada de jogo, os dados de telemetria de temporização que distinguem uma pessoa de um script. O canal do dispositivo envia esses eventos sem colocar uma chave de API no navegador. Seu backend emite uma credencial de curta duração restrita a um usuário; o app envia os eventos com ela.

Fluxo

Emita uma credencial de monitoramento

Seu backend chama POST /v3/events/sdk-token/ com sua chave de API e o vendor_data do usuário.

Envie a partir do dispositivo

O app envia para POST /v1/events/ (ou POST /v1/events/batch/) com o cabeçalho X-Monitoring-Token.

As regras são executadas normalmente

O evento é enriquecido, consolidado e avaliado exatamente pelas mesmas regras que um evento enviado pelo servidor.

Emissão de uma credencial

A emissão exige que a ingestão de eventos esteja ativada para a aplicação. Enquanto ela estiver desativada, este endpoint responde 403 com {"code": "event_monitoring_disabled"} em vez de entregar uma credencial que nunca poderia gravar.

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	Padrão	Observações
`vendor_data`	obrigatório	O titular ao qual pertence cada evento enviado com esta credencial.
`entity_type`	`individual`	`individual` ou `company`.
`allowed_event_categories`	todas	Restringe o que uma credencial vazada poderia gravar.
`ttl_seconds`	900	60 - 86400.
`max_uses`	1000	Um uso por evento, não por requisição.
`bind_to_origin`	nenhum	Quando definido, o `Origin` do navegador deve 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" }
  }'

Observe o que o payload não contém: nenhuma chave de API e nenhum titular. Ambos são exigidos no lado do servidor.

O que o servidor impõe

Vinculação ao titular. A credencial é restrita a um vendor_data no momento da emissão. Um bloco subject no corpo da requisição é sobrescrito, então um cliente adulterado não consegue gravar na linha do tempo de outro usuário.
Contexto de rede. O endereço IP, o user agent, o accept-language e a origem são derivados da requisição, e esses valores derivados pelo servidor prevalecem sobre qualquer indicação do cliente na avaliação de regras. As evidências da regra registram a diferença como uma fonte do campo.
Escopo de categoria. Uma credencial restrita a session não pode enviar um evento payment; ele é rejeitado com 400.
Limite de usos. Um lote consome um uso por evento, então um lote de 500 eventos não pode ser contabilizado como um único uso em uma credencial de 10 usos
Vinculação à origem. Quando bind_to_origin está definido, uma requisição cujo Origin não corresponde é recusada, inclusive uma sem nenhum 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 bom padrão de envio é a cada 25 eventos, a cada 5 segundos ou quando a página ou o app vai para segundo plano.

O que descartar sob contrapressão

Se você precisar descartar eventos, descarte os de menor valor. Estes podem ser descartados com 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 podem ser descartados; envie-os primeiro: todo evento security, payment, dispute e responsible_gambling, além de gameplay.bet_placed, gameplay.bet_settled e gameplay.p2p_settlement. Os endpoints de listagem retornam a mesma classificação de cada evento indicada por is_droppable, para que um cliente possa se basear nela em vez de em uma cópia fixa no código.

Compatibilidade de cabeçalhos

O cabeçalho canônico é X-Monitoring-Token. X-Transaction-Token é aceito como alias temporário para que um app que já usa um caminho de credencial de transação possa migrar de forma gradual.

O alias é transitório e será removido antes de a API de eventos atingir disponibilidade geral. Envie X-Monitoring-Token em código novo.

Como escolher um canal

	Canal do dispositivo	Canal do servidor
Endpoint	`POST /v1/events/`	`POST /v3/events/`
Autenticação	`X-Monitoring-Token`	`x-api-key`
Titular	Vinculado à credencial	No payload
Ideal para	Logins, sessões, jogo, telemetria	Pagamentos, disputas, eventos derivados do livro-razão, cargas retroativas

Ambos produzem registros de eventos idênticos e executam regras idênticas. Use o canal do servidor sempre que não houver um usuário final presente.

Primeiros passos

Recursos

Referência

Console

Envio de eventos pelo SDK - Captura de eventos no cliente

Fluxo

Emissão de uma credencial

Envio

O que o servidor impõe

Envio em lote

O que descartar sob contrapressão

Compatibilidade de cabeçalhos

Como escolher um canal

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 sob contrapressão

​Compatibilidade de cabeçalhos

​Como escolher um canal

​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 sob contrapressão

Compatibilidade de cabeçalhos

Como escolher um canal

Próximos passos