> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sinais de risco

> Ingerir sinais de detecção de fraude de qualquer fonte, normalizar eventos de identidade em sinais pontuados e consultá-los por entidade, pontuação ou tipo.

Os sinais de risco permitem que você alimente dados de detecção de fraude no Truthlocks de qualquer provedor upstream — serviços de impressão digital de dispositivos, APIs de reputação de IP, ferramentas de verificação de e-mail, mecanismos de análise de documentos ou suas próprias regras internas. Uma vez ingeridos, os sinais estão disponíveis através da API e da página **Risco e Fraude > Sinais** no console.

> [!NOTE]
>
> O Firewall de Identidade Antifraude está **geralmente disponível**. Todos os cinco caminhos de detecção — ingestão direta de sinal, normalização de eventos, varredura de deepfake, detecção de ATO e pontuação de velocidade — são integrados com exemplos de API multilíngues (cURL, JavaScript, Python), guias completos e [notificações de webhook](https://docs.truthlocks.com/pt/guides/webhooks.md) em tempo real para todos os tipos de sinal. [Decisões de risco](https://docs.truthlocks.com/pt/api-reference/risk/evaluate.md) automatizadas, [gerenciamento de casos](#case-management) e [exportação SIEM de fraude](#siem-export) já estão disponíveis.

Você pode criar sinais de cinco maneiras:

* **Ingestão direta** — envie um sinal totalmente pontuado via `POST /v1/risk/signals` quando você já tiver uma pontuação de risco de um provedor externo. Suporta novas tentativas idempotentes via o cabeçalho `Idempotency-Key`.
* **Normalização de eventos** — envie um evento de identidade bruto via `POST /v1/risk/events` e deixe a plataforma mapeá-lo para um tipo de sinal e pontuação base automaticamente. Consulte [normalização de eventos](#event-normalization).
* **Pontuação de sinal de deepfake e falsificação de identidade** — envie indicadores ou pontuações produzidos externamente para avaliação de limite via `POST /v1/risk/deepfake/scan`. Scans que pontuam 60 ou mais automaticamente ingerem um sinal de risco. Consulte o [guia de detecção de deepfake](https://docs.truthlocks.com/pt/guides/deepfake-detection.md).
* **Detecção de tomada de conta** — avalie eventos de login contra heurísticas baseadas em velocidade via `POST /v1/risk/ato/evaluate`. Alertas são criados e sinais de risco são ingeridos automaticamente quando os limites são excedidos. Consulte o [guia de detecção de ATO](https://docs.truthlocks.com/pt/guides/ato-detection.md).
* **Pontuação de velocidade e anomalia** — registre as ações do sujeito via `POST /v1/risk/velocity/record` e faça com que a plataforma rastreie a frequência em janelas de tempo contínuas (1 m, 5 m, 1 h, 24 h). Ações que produzem uma pontuação de velocidade ponderada de 60 ou superior ingerem automaticamente um sinal de risco. Consulte o [guia de pontuação de velocidade](https://docs.truthlocks.com/pt/guides/velocity-scoring.md).

### Escolhendo um caminho de ingestão

| Cenário | Usar | Endpoint |
| :- | :- | :- |
| Você tem uma pontuação de risco de uma ferramenta de fraude externa | Ingestão direta | `POST /v1/risk/signals` |
| Você quer que eventos nativos da plataforma (logins falhos, detecções de deepfake) sejam pontuados automaticamente | Normalização de eventos | `POST /v1/risk/events` |
| Você quer pontuar indicadores de deepfake ou personificação fornecidos | Varredura de Deepfake | `POST /v1/risk/deepfake/scan` |
| Você quer detectar tentativas de tomada de conta com base na velocidade de login | Detecção de ATO | `POST /v1/risk/ato/evaluate` |
| Você quer detectar anomalias de velocidade em qualquer tipo de ação | Pontuação de velocidade | `POST /v1/risk/velocity/record` |
| Você usa múltiplas fontes de sinal | Todas as cinco — os sinais chegam no mesmo pipeline | Qualquer endpoint |

Todos os cinco caminhos produzem os mesmos registros de sinal de risco. Você pode consultar, filtrar e revisar sinais de qualquer caminho usando o [endpoint de lista](https://docs.truthlocks.com/pt/api-reference/risk-signals/list.md) e a página do console **Risco e Fraude > Sinais**.

## Como funciona

**1. Sinais de ingestão**

Envie uma solicitação `POST` para `/v1/risk/signals` com a fonte do sinal, tipo, pontuação de risco e o assunto a que se refere. Anexe qualquer contexto extra no objeto `payload`.

**2. Consultar e filtrar**

Use `GET /v1/risk/signals` para listar sinais com filtros para origem, tipo de sinal, assunto e pontuação mínima. Os resultados são paginados com paginação baseada em cursor.

**3. Revisar no console**

Abra **Risco e Fraude > Sinais** na console do locatário para navegar pelos sinais, filtrar por fonte ou pontuação e inspecionar detalhes de sinais individuais.

## Pré-requisitos

* Um inquilino Truthlocks ativo com uma chave de API
* Pelo menos uma fonte upstream de detecção de fraude que produz sinais pontuados

## Ingestão de um sinal

Envie uma requisição `POST` com os campos obrigatórios:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/signals \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "signal_source": "external",
    "signal_type": "velocity",
    "risk_score": 85,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f",
    "payload": {
      "ip": "203.0.113.42",
      "country": "US",
      "reason": "multiple_accounts_same_device"
    },
    "ip_address": "203.0.113.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/signals", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    signal_source: "external",
    signal_type: "velocity",
    risk_score: 85,
    subject_type: "user",
    subject_id: "usr_8f14e45f",
    payload: {
      ip: "203.0.113.42",
      country: "US",
      reason: "multiple_accounts_same_device",
    },
    ip_address: "203.0.113.42",
  }),
});
const signal = await response.json();
```

```python Python theme={null}
import httpx
import uuid

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/signals",
    headers={
        "X-API-Key": "tl_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "signal_source": "external",
        "signal_type": "velocity",
        "risk_score": 85,
        "subject_type": "user",
        "subject_id": "usr_8f14e45f",
        "payload": {
            "ip": "203.0.113.42",
            "country": "US",
            "reason": "multiple_accounts_same_device",
        },
        "ip_address": "203.0.113.42",
    },
)
signal = resp.json()
```

### Campos obrigatórios

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `signal_source` | string | Origem do sinal — `verification`, `login`, `attestation`, `external`, ou `manual` |
| `signal_type` | string | O que foi detectado (por exemplo, `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`) |
| `risk_score` | integer | Pontuação de risco de `0` (seguro) a `100` (alto risco). Pontuações iguais ou superiores a 80 acionam revisão automática. |
| `subject_type` | string | Tipo de entidade: `user`, `issuer`, `attestation`, `session`, `ip`, ou `device` |
| `subject_id` | string | Identificador da entidade sendo avaliada |

### Campos opcionais

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `payload` | object | JSON arbitrário com contexto específico do sinal (endereços IP, geolocalização, motivos) |
| `ip_address` | string | Endereço IP de origem associado a este evento |
| `user_agent` | string | String User-Agent associada a este evento |

### Idempotência

Inclua um cabeçalho `Idempotency-Key` (UUID) para evitar sinais duplicados durante as retentativas. Se você enviar a mesma chave duas vezes, a duplicata será ignorada silenciosamente.

## Consultando sinais

### Listar com filtros

```bash theme={null}
curl "https://api.truthlocks.com/v1/risk/signals?source=external&min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."
```

Filtros disponíveis:

| Parâmetro | Descrição |
| :- | :- |
| `source` | Filtrar por fonte de sinal |
| `signal_type` | Filtrar por tipo de sinal |
| `subject_type` | Filtrar por tipo de sujeito |
| `subject_id` | Filtrar por ID do sujeito |
| `min_score` | Limite mínimo de pontuação (0–100) |
| `limit` | Resultados por página (máx. 100) |
| `cursor` | Cursor para a próxima página |

### Obter um único sinal

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: tl_live_..."
```

## Visualização do Console

A página **Risco e Fraude > Sinais** no console fornece uma lista pesquisável e filtrável de todos os sinais ingeridos. Cada linha mostra a origem, tipo, pontuação (codificada por cores por gravidade), referência do assunto e carimbo de data/hora.

Use os filtros na parte superior da página para restringir os resultados por fonte, tipo de sinal ou pontuação mínima. Clique em qualquer linha para ver os detalhes completos do sinal, incluindo o objeto de metadados `payload`.

## Diretrizes de pontuação

A pontuação consistente entre as fontes torna a análise downstream mais confiável. Recomendamos os seguintes intervalos:

| Intervalo | Interpretação | Exemplo |
| :- | :- | :- |
| 0 – 30 | Baixo risco | Dispositivo conhecido e bom, IP respeitável |
| 30 – 60 | Risco moderado | Uso de VPN, velocidade de novas contas |
| 60 – 80 | Risco crítico | E-mail descartável, IP de datacenter |
| 80 – 100 | Risco crítico | Dispositivo de fraude conhecido, viagem impossível |

> [!WARNING]
>
> Pontuações iguais ou superiores a 80 acionam decisões de revisão automática. A interpretação da pontuação além do limite automático é por sua conta — a plataforma armazena e retorna as pontuações como estão e não as normaliza entre as fontes.

## Normalização de eventos

Em vez de construir sinais de risco manualmente, você pode enviar eventos de identidade brutos e deixar a plataforma normalizá-los em sinais automaticamente. Isso é útil quando você deseja alimentar eventos nativos da plataforma — logins falhos, assinaturas inválidas, suspeitos de deepfake — diretamente no pipeline de risco sem mapeá-los para tipos de sinal você mesmo.

Envie uma requisição `POST` para `/v1/risk/events` com a origem, tipo e assunto do evento:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/events \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_source": "login",
    "event_type": "login.failed.repeated",
    "subject_id": "user_abc123",
    "ip_address": "198.51.100.42",
    "payload": { "attempt_count": 8, "window_seconds": 120 }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/events", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_source: "login",
    event_type: "login.failed.repeated",
    subject_id: "user_abc123",
    ip_address: "198.51.100.42",
    payload: { attempt_count: 8, window_seconds: 120 },
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/events",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "event_source": "login",
        "event_type": "login.failed.repeated",
        "subject_id": "user_abc123",
        "ip_address": "198.51.100.42",
        "payload": {"attempt_count": 8, "window_seconds": 120},
    },
)
result = resp.json()
```

A resposta inclui tanto o `event_id` bruto quanto o `signal_id` normalizado, para que você possa rastrear todo o pipeline do evento ao sinal:

```json theme={null}
{
  "event_id": "2a4b6c8d-...",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed.repeated",
  "signal_type": "ato",
  "risk_score": 70,
  "normalized": true,
  "created_at": "2027-05-01T10:00:00Z"
}
```

Quando `normalized` é `true`, o evento correspondeu a um mapeamento conhecido. Quando `false`, a plataforma usou o fallback genérico.

### Mapeamentos de eventos integrados

A plataforma vem com mapeamentos pré-calibrados para eventos de identidade comuns:

| Tipo de evento | Tipo de sinal | Pontuação base |
| :- | :- | :- |
| `verification.failed` | behavior | 60 |
| `verification.invalid_sig` | behavior | 75 |
| `login.failed.repeated` | ato | 70 |
| `login.suspicious_geo` | geo\_anomaly | 65 |
| `attestation.deepfake_suspect` | deepfake | 85 |
| `session.hijack_suspect` | ato | 90 |

Tipos de evento desconhecidos são aceitos com o tipo de sinal `behavior` e uma pontuação base de 10.

### Campos de evento

**Obrigatório:**

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `event_source` | string | Sistema que gerou o evento — `attestation`, `verification`, `login`, ou `consumer_portal` |
| `event_type` | string | Nome do evento bruto (por exemplo, `login.failed.repeated`, `attestation.deepfake_suspect`) |
| `subject_id` | string | Identificador da entidade envolvida no evento |

**Opcional:**

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `event_ref_id` | string | ID de referência externa (ID de atestado, ID de sessão) para referência cruzada |
| `ip_address` | string | Endereço IP de origem |
| `payload` | object | Carga de evento bruta para contexto de enriquecimento |

> [!NOTE]
>
> Use a normalização de eventos quando seus eventos se originarem de dentro da plataforma (logins, verificações, atestações). Use o [endpoint de ingestão direta de sinal](https://docs.truthlocks.com/pt/api-reference/risk/ingest-signal.md) quando você já tiver um sinal pontuado de uma fonte externa.

## Isolamento de inquilino

Os sinais de risco são totalmente isolados por inquilino usando [segurança em nível de linha (RLS)](https://docs.truthlocks.com/pt/security/rls.md). Cada sinal é vinculado ao inquilino autenticado no momento da ingestão, e as consultas só podem retornar sinais que pertencem ao inquilino chamador.

## Detecção de deepfake e personificação

A [API de detecção de deepfake](https://docs.truthlocks.com/pt/guides/deepfake-detection.md) estende o pipeline de sinal de risco com varredura automatizada para conteúdo manipulado e fraude de identidade. Envie imagens, vídeos, documentos ou atestados para análise, e as varreduras que excedem o limite de risco criam automaticamente um sinal de risco — nenhuma chamada de API extra é necessária.

Consulte o [guia de detecção de deepfake e personificação](https://docs.truthlocks.com/pt/guides/deepfake-detection.md) para o fluxo de trabalho completo, referência de indicadores e exemplos de código.

## Detecção de aquisição de conta

A [API de detecção de ATO](https://docs.truthlocks.com/pt/guides/ato-detection.md) estende o pipeline de sinal de risco com monitoramento de login baseado em velocidade. Envie eventos de login para `POST /v1/risk/ato/evaluate` e a plataforma rastreia tentativas falhas por assunto em uma janela contínua de uma hora. Quando um assunto ultrapassa um limite (5, 10 ou 20 logins falhos), um alerta é criado e um sinal de risco é ingerido automaticamente — nenhuma chamada de API extra é necessária.

Consulte o [guia de detecção de aquisição de conta](https://docs.truthlocks.com/pt/guides/ato-detection.md) para o fluxo de trabalho completo, referência de limite e padrões de integração.

## Pontuação de velocidade e anomalia

A [API de pontuação de velocidade](https://docs.truthlocks.com/pt/guides/velocity-scoring.md) estende o pipeline de sinal de risco com rastreamento de ações em várias janelas e detecção de anomalias. Registre qualquer ação do sujeito via `POST /v1/risk/velocity/record` e a plataforma rastreia a frequência em quatro janelas contínuas (1 m, 5 m, 1 h, 24 h). Uma pontuação de velocidade ponderada é calculada a partir das contagens da janela, com viés para janelas curtas para detecção de rajadas. Quando a pontuação atinge 60 ou mais, um sinal de risco com `signal_type: "velocity"` é ingerido automaticamente — nenhuma chamada de API extra é necessária.

Consulte o [guia de pontuação de velocidade e anomalia](https://docs.truthlocks.com/pt/guides/velocity-scoring.md) para o fluxo de trabalho completo, modelo de pontuação e padrões de integração.

## Notificações de webhook

Sinais de risco criados por qualquer um dos cinco caminhos de detecção podem acionar notificações [webhook](https://docs.truthlocks.com/pt/guides/webhooks.md) em tempo real. Assine `risk.signal.created` ou `risk.signal.escalated` para reagir a novos sinais sem sondagem. Isso cobre sinais de ingestão direta, normalização de eventos, varreduras de deepfake, alertas de ATO e anomalias de velocidade.

Consulte o [guia de webhooks](https://docs.truthlocks.com/pt/guides/webhooks.md#risk-signal-notifications) para exemplos de payload e padrões de integração.

## Medição de uso

Os recursos Anti-Fraude são medidos por ciclo de faturação. Cada caminho de deteção incrementa o seu próprio contador de uso:

| Métrica | Ação medida |
| :- | :- |
| `antifraud.risk_signals` | Sinais de risco ingeridos ou gerados (todos os cinco caminhos) |
| `antifraud.deepfake_scans` | Pedidos de análise de deepfake e personificação |
| `antifraud.velocity_records` | Registros de ação de pontuação de velocidade |

As cotas variam de acordo com o nível do plano. Você pode verificar seu consumo atual com a [API de uso](https://docs.truthlocks.com/pt/api-reference/billing/usage.md) ou no console em **Configurações > Faturamento > Uso** na seção **Anti-Fraude**. Para verificar se uma operação específica é permitida antes de realizá-la, use o [endpoint de verificação de limite](https://docs.truthlocks.com/pt/api-reference/billing/entitlements.md).

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

A resposta inclui todos os contadores Anti-Fraude com os campos `used`, `limit` e `period` para que você possa monitorar o consumo programaticamente.

> [!NOTE]
>
> Consulte a [visão geral de faturamento](https://docs.truthlocks.com/pt/billing/overview.md#metered-products) para a lista completa de 16 produtos medidos e suas taxas padrão.

## O que vem a seguir

* [Guia de pontuação de velocidade e anomalias](https://docs.truthlocks.com/pt/guides/velocity-scoring.md)
* [Guia de detecção de aquisição de conta](https://docs.truthlocks.com/pt/guides/ato-detection.md)
* [Guia de detecção de deepfake e personificação](https://docs.truthlocks.com/pt/guides/deepfake-detection.md)
* [Ingerir referência da API de sinal de risco](https://docs.truthlocks.com/api-reference/risk-signals/ingest)
* [Normalizar referência da API de evento de identidade](https://docs.truthlocks.com/pt/api-reference/risk/normalize-event.md)
* [Listar referência da API de sinais de risco](https://docs.truthlocks.com/pt/api-reference/risk-signals/list.md)
* [Obter referência da API de sinal de risco](https://docs.truthlocks.com/pt/api-reference/risk-signals/get.md)
* [Segurança em nível de linha](https://docs.truthlocks.com/pt/security/rls.md)


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