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

# Visão Geral de Entidades

> Gerencie empresas, indivíduos e transações na plataforma de análise de risco gu1 — no modelo universal de entidades gu1 para KYC, KYB e análise de risco.

## O que são Entidades?

Entidades são os objetos principais no gu1 que representam os sujeitos da sua análise de risco. Uma entidade pode ser uma empresa, um indivíduo, uma transação ou qualquer tipo personalizado relevante para o seu negócio.

Cada entidade contém:

* **Informações de identidade** (nome, ID externo, tipo)
* **Avaliação de risco** (pontuação de risco, status)
* **Dados personalizados** (JSON flexível para seus campos específicos)
* **Relacionamentos** (conexões com outras entidades)
* **Resultados de análise** (insights gerados por IA)
* **Linha do tempo** (histórico de mudanças e eventos)

## Tipos de Entidades

<CardGroup cols={2}>
  <Card title="Empresa" icon="building">
    Entidades corporativas para análise KYB
  </Card>

  <Card title="Pessoa" icon="user">
    Entidades individuais para análise KYC
  </Card>

  <Card title="Transação" icon="money-bill-transfer">
    Transações financeiras para monitoramento
  </Card>

  <Card title="Personalizado" icon="shapes">
    Qualquer tipo de entidade personalizado para o seu negócio
  </Card>
</CardGroup>

## Ciclo de Vida da Entidade

<Steps>
  <Step title="Criação">
    Entidade é criada via API com informações básicas e dados personalizados opcionais
  </Step>

  <Step title="Enriquecimento">
    Dados adicionais são adicionados através de atualizações ou integrações
  </Step>

  <Step title="Análise">
    Análise de risco alimentada por IA é gerada automaticamente
  </Step>

  <Step title="Avaliação de Regras">
    Regras de risco são aplicadas para calcular a pontuação de risco e gerar alertas
  </Step>

  <Step title="Investigação">
    Alertas acionam investigações para revisão manual
  </Step>

  <Step title="Resolução">
    Status da entidade é atualizado com base nos resultados da investigação
  </Step>
</Steps>

## Status da Entidade

Entidades podem ter diferentes status ao longo do seu ciclo de vida:

| Status            | Descrição                                      | Caso de Uso         |
| ----------------- | ---------------------------------------------- | ------------------- |
| **active**        | Entidade está ativa e sendo monitorada         | Operação normal     |
| **inactive**      | Entidade não está mais ativa                   | Contas encerradas   |
| **under\_review** | Entidade está sendo investigada                | Alerta acionado     |
| **approved**      | Entidade passou em todas as verificações       | Baixo risco         |
| **rejected**      | Entidade falhou nas verificações de compliance | Alto risco          |
| **suspended**     | Entidade temporariamente suspensa              | Informação pendente |

## Pontuação de Risco

Cada entidade tem uma pontuação de risco (0-100) calculada com base em:

<AccordionGroup>
  <Accordion icon="brain" title="Análise de IA">
    Modelos de machine learning analisam comportamento, padrões e anomalias da entidade
  </Accordion>

  <Accordion icon="sliders" title="Pontuação Baseada em Regras">
    Regras personalizadas avaliam condições específicas e atribuem pontos de risco
  </Accordion>

  <Accordion icon="shield-check" title="Verificações de Compliance">
    Listas de sanções, PEPs, resultados de triagem de mídia adversa
  </Accordion>

  <Accordion icon="chart-line" title="Comportamento Histórico">
    Padrões de transações, atividade da conta e mudanças ao longo do tempo
  </Accordion>

  <Accordion icon="link" title="Análise de Relacionamentos">
    Entidades conectadas e seus perfis de risco
  </Accordion>
</AccordionGroup>

**Faixas de Pontuação de Risco:**

* **0-25**: Baixo risco (verde)
* **26-50**: Risco médio (amarelo)
* **51-75**: Alto risco (laranja)
* **76-100**: Risco crítico (vermelho)

## Estrutura de Dados da Entidade

```json theme={null}
{
  "id": "a7c4c07f-a1f5-49d6-8c17-1577d0787a2e",
  "type": "company",
  "name": "Acme Corporation",
  "externalId": "TAX123456789",
  "country": "US",
  "riskScore": 35,
  "status": "active",
  "entityData": {
    "industry": "Technology",
    "annual_revenue": 5000000,
    "employees": 50,
    "incorporation_date": "2010-01-15",
    "beneficial_owners": [
      {
        "name": "John Doe",
        "ownership": 60,
        "isPEP": false
      }
    ],
    "compliance": {
      "kyb_completed": true,
      "sanctions_checked": true,
      "adverse_media_found": false
    }
  },
  "organizationId": "org_abc123",
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T14:30:00Z"
}
```

## Campos Principais

| Campo        | Tipo   | Obrigatório | Descrição                                               |
| ------------ | ------ | ----------- | ------------------------------------------------------- |
| `type`       | string | Sim         | Tipo de entidade (company, person, transaction, custom) |
| `name`       | string | Sim         | Nome da entidade                                        |
| `externalId` | string | Não         | Seu identificador único para esta entidade              |
| `country`    | string | Não         | Código de país ISO (ex: "US", "UK")                     |
| `entityData` | object | Não         | JSON flexível para campos personalizados                |
| `riskScore`  | number | Não         | Pontuação de risco 0-100 (calculada automaticamente)    |
| `status`     | enum   | Não         | Status da entidade (padrão: "active")                   |

## Dados Personalizados da Entidade

O campo `entityData` é um objeto JSON flexível onde você pode armazenar quaisquer campos personalizados relevantes para o seu caso de uso:

**Exemplo KYB:**

```json theme={null}
{
  "entityData": {
    "tax_id": "12-3456789",
    "industry": "Financial Services",
    "annual_revenue": 10000000,
    "employees": 150,
    "incorporation_date": "2015-03-20",
    "website": "https://example.com",
    "beneficial_owners": [...],
    "licenses": [...]
  }
}
```

**Exemplo KYC:**

```json theme={null}
{
  "entityData": {
    "date_of_birth": "1985-06-15",
    "nationality": "US",
    "occupation": "Software Engineer",
    "annual_income": 120000,
    "identity_verified": true,
    "pep_status": false,
    "documents": [...]
  }
}
```

**Exemplo de Transação:**

```json theme={null}
{
  "entityData": {
    "amount": 50000,
    "currency": "USD",
    "sender_account": "ACC123",
    "receiver_account": "ACC456",
    "transaction_type": "wire_transfer",
    "purpose": "Business payment",
    "timestamp": "2025-10-03T10:30:00Z"
  }
}
```

## Operações Comuns

<CardGroup cols={2}>
  <Card title="Criar Entidade" icon="plus" href="/api-reference/entities/create">
    POST /entities - Criar nova entidade
  </Card>

  <Card title="Obter Entidade" icon="eye" href="/api-reference/entities/get">
    GET /entities/:id - Recuperar detalhes da entidade
  </Card>

  <Card title="Listar Entidades" icon="list" href="/api-reference/entities/list">
    GET /entities - Consultar entidades com filtros
  </Card>

  <Card title="Atualizar Entidade" icon="pen" href="/api-reference/entities/update">
    PUT /entities/:id - Atualizar dados da entidade
  </Card>

  <Card title="Excluir Entidade" icon="trash" href="/api-reference/entities/list">
    DELETE /entities/:id - Remover entidade
  </Card>

  <Card title="Importação em Massa" icon="layer-group" href="/en/api-reference/bulk-imports/import-entities">
    POST /entities/bulk - Importar múltiplas entidades
  </Card>
</CardGroup>

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="key" title="Use IDs Externos">
    Sempre defina `externalId` com seu identificador interno para facilitar a reconciliação e atualizações
  </Accordion>

  <Accordion icon="tag" title="Tipos de Entidade Consistentes">
    Use valores de tipo de entidade consistentes em toda a sua organização (ex: "company" vs "corporate")
  </Accordion>

  <Accordion icon="globe" title="Defina Códigos de País">
    Sempre inclua códigos de país ISO para avaliação de risco adequada e verificações de compliance
  </Accordion>

  <Accordion icon="database" title="Estruture os Dados da Entidade">
    Organize `entityData` com nomes de campos consistentes e objetos aninhados para dados complexos
  </Accordion>

  <Accordion icon="clock-rotate-left" title="Rastreie Atualizações">
    Use o timestamp `updatedAt` para detectar mudanças e sincronizar com seus sistemas
  </Accordion>

  <Accordion icon="gauge" title="Operações em Massa">
    Use importação em massa para criar múltiplas entidades (>10) para melhorar o desempenho
  </Accordion>
</AccordionGroup>

## Recursos Avançados

### Análise Alimentada por IA

Cada entidade pode ter análise de risco gerada por IA:

```bash theme={null}
POST /ai-analysis/entity/:entityId
```

Retorna análise abrangente incluindo:

* Resumo executivo
* Padrões comportamentais
* Fatores de risco identificados
* Recomendações
* Pontuação de confiança

[Saiba mais →](/api-reference/data-ingestion/overview)

### Relacionamentos de Entidades

Conecte entidades para mostrar propriedade, transações ou outros relacionamentos:

```json theme={null}
{
  "sourceEntityId": "entity_1",
  "targetEntityId": "entity_2",
  "relationshipType": "owns",
  "strength": 0.85
}
```

### Anexos de Documentos

Anexe documentos (carteiras de identidade, licenças, contratos) às entidades:

```bash theme={null}
POST /documents/entity/:entityId/upload
```

[Saiba mais →](/en/api-reference/documents/upload)

## Fluxos de Trabalho de Exemplo

<CardGroup cols={2}>
  <Card title="Onboarding KYB" icon="building" href="/use-cases/kyb/workflow">
    Fluxo de trabalho completo de onboarding de empresas
  </Card>

  <Card title="Verificação KYC" icon="id-card" href="/pt/use-cases/kyc/fluxo-completo">
    Processo de verificação de clientes individuais
  </Card>

  <Card title="Monitoramento de Transações" icon="money-bill-transfer" href="/pt/use-cases/transaction-monitoring/fraud-detection">
    Triagem de transações em tempo real
  </Card>

  <Card title="Monitoramento Contínuo" icon="chart-line" href="/quickstart">
    Configuração de monitoramento contínuo de entidades
  </Card>
</CardGroup>

## Próximos Passos

<Steps>
  <Step title="Crie Sua Primeira Entidade">
    Siga o guia [Criar Entidade](/api-reference/entities/create) para adicionar uma entidade
  </Step>

  <Step title="Configure o Mapeamento de Dados">
    Use [Schemas Personalizados](/api-reference/data-ingestion/custom-schemas) para importações estruturadas
  </Step>

  <Step title="Configure Regras">
    Aplique regras de risco através do painel para calcular pontuações de risco
  </Step>

  <Step title="Monitore e Aja">
    Configure webhooks para receber alertas quando as pontuações de risco mudarem
  </Step>
</Steps>