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

# Entidades: Utilizadores e Empresas na Didit

> Utilizadores e Empresas são as entidades principais da Didit, agregando sessões KYC, transações, documentos, biometria e risco num só perfil.

A Didit organiza tudo o que acontece na sua aplicação em torno de dois tipos de entidades de primeira classe:

| Entidade | Representa | Ligada a |
| - | - | - |
| **Utilizador** | Uma pessoa individual | Sessões de Verificação de utilizadores (KYC), biometria facial, transações (como requerente ou contraparte), listas de bloqueio |
| **Empresa** | Uma entidade jurídica (sociedade, LLC, empresário em nome individual, fundo) | Sessões de Verificação de empresas (KYB), dirigentes, UBOs, transações (como requerente ou contraparte), listas de bloqueio |

Qualquer sessão de verificação, transação ou entrada numa lista de bloqueio pode ser associada a uma entidade. Depois de associada, a entidade torna-se um perfil duradouro que agrega o histórico, os sinais de risco e o estado de conformidade ao longo do tempo.

## Entidade vs sessão

Uma **entidade** e uma **sessão** são coisas diferentes.

| Conceito | Âmbito | Duração | Exemplo |
| - | - | - | - |
| **Sessão** | Um único evento de verificação | Um único fluxo (de minutos a dias enquanto está em análise) | Uma única tentativa de KYC |
| **Entidade** | Um perfil duradouro | Existe enquanto o utilizador ou a empresa existir na sua plataforma | O cliente "Jane Doe" com 3 sessões de Verificação de utilizadores (KYC) ao longo de 2 anos |

Uma única entidade pode ter muitas sessões: reverificações, reenvios, verificações adicionais e monitorização contínua periódica. A entidade agrega os resultados.

## Criação automática vs pré-criação manual

As entidades são criadas de uma das três formas:

**1. Criada automaticamente a partir de uma sessão**

Quando cria uma sessão com um identificador `vendor_data` e não existe nenhuma entidade correspondente, a Didit cria a entidade automaticamente. Este é o caminho mais comum.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "workflow_id": "wf_kyc_standard", "vendor_data": "user-42" }'
```

Uma entidade de Utilizador para `user-42` é criada no momento em que a sessão começa.

**2. Pré-criada através da Management API**

Crie primeiro a entidade e depois inicie sessões com ela. Útil quando pretende introduzir sinais de risco (estado, etiquetas, metadados personalizados) antes da primeira verificação.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "vendor_data": "user-42", "display_name": "Jane Doe" }'
```

**3. Criada na consola**

A sua equipa de conformidade pode criar utilizadores ou empresas diretamente na Business Console, o que é útil para o onboarding manual, importações ou fluxos de correção.

## Como as entidades associam tudo

O campo `vendor_data` é a chave de associação. Quando envia `vendor_data` em qualquer sessão ou transação, a Didit encaminha-o para a entidade correspondente.

```mermaid theme={null}
flowchart LR
    VD["vendor_data:<br/>user-42"] --> U[User entity]
    S1[User Verification (KYC) session #1] --> VD
    S2[User Verification (KYC) session #2] --> VD
    T1[Transaction #1] --> VD
    T2[Transaction #2] --> VD
    F[Face biometric] --> VD
    D[Documents] --> VD
    BL[Blocklist entry] --> VD
```

Saiba mais no [guia de associação por `vendor_data`](https://docs.didit.me/pt/entities/vendor-data-linking).

## O que pode fazer com uma entidade

Para cada entidade de Utilizador ou de Empresa, pode:

| Operação | Finalidade |
| - | - |
| **Criar / atualizar** | Definir ou alterar os dados de perfil da entidade (nome, país, metadados personalizados) |
| **Alterar estado** | Marcar como `ACTIVE`, `FLAGGED` ou `BLOCKED`; a aplicação deste estado propaga-se às sessões e transações futuras |
| **Associar biometria** | Carregar uma referência facial para pesquisa 1:N, deteção de duplicados ou inclusão em lista de bloqueio |
| **Rever o histórico de KYC/KYB** | Obter todas as sessões associadas à entidade, com resultados por funcionalidade |
| **Rever o histórico de transações** | Obter todas as transações em que a entidade é requerente ou contraparte |
| **Adicionar a uma lista de bloqueio** | Bloquear sessões ou transações futuras que envolvam esta entidade |
| **Importar / exportar** | Carregar entidades em massa a partir de CSV ou exportar para ferramentas externas de conformidade |
| **Eliminar** | Eliminar a entidade (o histórico é preservado para auditoria) |

Os guias detalhados estão em [Utilizadores](https://docs.didit.me/pt/entities/users/overview.md) e [Empresas](https://docs.didit.me/pt/entities/businesses/overview.md).

## Relações entre utilizadores e empresas

Um único utilizador pode estar associado a uma ou várias empresas. Isto acontece naturalmente durante o KYB:

* Um utilizador pode ser **administrador** de uma empresa e **UBO** de outra.
* A sessão de Verificação de utilizadores (KYC) de um utilizador pode ser associada à sessão de Verificação de empresas (KYB) de uma empresa através do fluxo de [Pessoas-chave](https://docs.didit.me/pt/business-verification/key-people.md).

A Didit preserva estas relações: ao consultar uma entidade de Empresa, pode ver todos os utilizadores associados e, ao consultar uma entidade de utilizador, pode ver todas as empresas a que está associado.

## Ciclo de vida e estados

Cada entidade tem um estado que determina se a Didit aplica bloqueios à nova atividade:

| Estado | Efeito |
| - | - |
| `ACTIVE` | Normal: as sessões e transações prosseguem conforme configurado pelos fluxos e regras |
| `FLAGGED` | As sessões e transações são permitidas, mas são encaminhadas automaticamente para análise manual |
| `BLOCKED` | As sessões e transações são recusadas automaticamente, e não podem ser criadas novas sessões |

Consulte o [ciclo de vida completo da entidade](https://docs.didit.me/pt/entities/lifecycle.md) para transições e eventos de webhook.

## Próximos passos

> [card] [Ciclo de vida](https://docs.didit.me/pt/entities/lifecycle.md)
>
> Estados, transições e eventos de ciclo de vida de cada entidade.

> [card] [Associação por vendor\_data](https://docs.didit.me/pt/entities/vendor-data-linking.md)
>
> Como o `vendor_data` associa sessões, transações e entidades.

> [card] [Utilizadores](https://docs.didit.me/pt/entities/users/overview.md)
>
> Análise detalhada das entidades de Utilizador, operações e fluxos na consola.

> [card] [Empresas](https://docs.didit.me/pt/entities/businesses/overview.md)
>
> Análise detalhada das entidades de Empresa, operações e fluxos na consola.

> [card] [Webhooks de entidades](https://docs.didit.me/pt/entities/webhooks.md)
>
> Eventos em tempo real para cada alteração de entidade.

> [card] [Lista de bloqueio](https://docs.didit.me/pt/console/blocklist-users.md)
>
> Como as entradas da lista de bloqueio interagem com as entidades de Utilizador e de Empresa.


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