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

# Tem eventos? (por entidade)

> Verificação booleana rápida se uma entidade tem eventos de usuário vinculados — mesmo escopo de listar por entidade, sem retornar linhas ou totais.

## Visão geral

Use este endpoint quando você só precisa saber **se** uma entidade tem eventos de usuário (badges na UI, visibilidade de abas, pré-checagens), não a linha do tempo completa. Usa o **mesmo escopo de vínculo** que [Listar por entidade](/pt/api-reference/events/list-by-entity): `entity_id`, `entity_external_id` ou `tax_id` na sua organização.

<Tip>
  Prefira este endpoint em vez de listar com `limit=1` quando só precisar de sim/não — evita `COUNT(*)`, ordenação e serializar payloads de eventos.
</Tip>

<Note>
  **Identificadores de entidade:** você pode consultar por query param sem o UUID interno. Prioridade de busca: `entity_id` → `entity_external_id` → `tax_id` (se enviar mais de um, vence o de maior prioridade). Para `tax_id`, a comparação no DB normaliza caracteres não alfanuméricos (ex.: `20-24245549-6` e `20242455496`).

  A rota legada `GET …/entity/{entityId}/has-events` continua disponível quando você já tem o UUID.
</Note>

## Desempenho

Projetado para baixa latência:

| Aspecto       | Comportamento                                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Consultas** | Duas idas: lookup da entidade + uma sonda `LIMIT 1` em `user_events`                                                                                |
| **Não faz**   | `COUNT(*)`, `ORDER BY`, paginação nem colunas completas de evento/metadata                                                                          |
| **Índices**   | `organization_id` + `entity_id` usa `idx_user_events_organization_entity_id`; `entity_external_id` e `tax_id` têm índices dedicados nas ramas do OR |

A latência típica é dominada por rede e autenticação, não por varrer históricos grandes.

## Endpoint

```
GET https://api.gu1.ai/events/user/entity/has-events
```

## Autenticação

Requer API key válida no header Authorization:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parâmetros de consulta

Pelo menos **um** é obrigatório. Se enviar vários, a prioridade é `entity_id` → `entity_external_id` → `tax_id`.

<ParamField query="entity_id" type="string">
  UUID da entidade (maior prioridade)

  Exemplo: `?entity_id=550e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField query="entity_external_id" type="string">
  Identificador externo da entidade no seu sistema

  Exemplo: `?entity_external_id=user_12345`
</ParamField>

<ParamField query="tax_id" type="string">
  Documento fiscal (CUIT/CUIL/CPF/CNPJ, etc.). Comparação exata e normalizada (somente alfanuméricos)

  Exemplo: `?tax_id=20242455496`
</ParamField>

## Resposta

<ResponseField name="success" type="boolean">
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="hasEvents" type="boolean">
  `true` se existir pelo menos um evento vinculado (mesmo escopo de listar por entidade); caso contrário `false`
</ResponseField>

<ResponseField name="entityId" type="string">
  UUID interno da entidade resolvida (útil quando consultou por `entity_external_id` ou `tax_id`)
</ResponseField>

### Exemplo — com eventos

```json theme={null}
{
  "success": true,
  "hasEvents": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Exemplo — sem eventos

```json theme={null}
{
  "success": true,
  "hasEvents": false,
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Erros

| Estado | Código             | Quando                                                      |
| ------ | ------------------ | ----------------------------------------------------------- |
| 400    | —                  | Falta qualquer identificador de entidade na query           |
| 404    | `ENTITY_NOT_FOUND` | A entidade não existe na org ou está excluída (soft delete) |
| 401    | —                  | API key ausente ou inválida                                 |
| 403    | —                  | Permissões insuficientes (`events:read`)                    |

## Exemplos

```bash theme={null}
# Por external ID (caso típico sem UUID interno)
curl "https://api.gu1.ai/events/user/entity/has-events?entity_external_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Por tax ID
curl "https://api.gu1.ai/events/user/entity/has-events?tax_id=20242455496" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Legado: UUID no path
curl "https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000/has-events" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript theme={null}
const res = await fetch(
  'https://api.gu1.ai/events/user/entity/has-events?entity_external_id=user_12345',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { hasEvents, entityId } = await res.json();
if (hasEvents) {
  const timeline = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}?limit=50`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
}
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Listar por entidade" icon="list" href="/pt/api-reference/events/list-by-entity">
    Linha do tempo completa quando `hasEvents` é true
  </Card>

  <Card title="Listar eventos" icon="filter" href="/pt/api-reference/events/list">
    Consultar com filtros
  </Card>

  <Card title="Estatísticas" icon="chart-bar" href="/pt/api-reference/events/stats">
    Contagens por tipo de evento
  </Card>

  <Card title="Overview" icon="book" href="/pt/api-reference/events/overview">
    Overview de eventos de usuário
  </Card>
</CardGroup>