> ## 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: usuários e empresas na Didit

> Usuários e Empresas são as duas entidades principais da Didit. Cada uma reúne sessões KYC, transações, documentos, biometria e risco em um único perfil.

A Didit organiza tudo o que acontece na sua aplicação em torno de dois tipos de entidade principais:

| Entidade | Representa | Vinculada a |
| - | - | - |
| **Usuário** | Uma pessoa física | Sessões de verificação de usuários (KYC), biometria facial, transações (como solicitante/contraparte), listas de bloqueio |
| **Empresa** | Uma pessoa jurídica (empresa, LLC, empresário individual, fundo) | Sessões de verificação de empresas (KYB), diretores, UBOs, transações (como solicitante/contraparte), listas de bloqueio |

Toda sessão de verificação, toda transação e toda entrada de lista de bloqueio pode ser vinculada a uma entidade. Depois de vinculada, a entidade se torna um perfil durável que reúne histórico, sinais de risco e estado de conformidade ao longo do tempo.

## Entidade vs sessão

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

| Conceito | Escopo | Duração | Exemplo |
| - | - | - | - |
| **Sessão** | Um evento de verificação | Um único fluxo (de minutos a dias, enquanto está em revisão) | Uma única tentativa de KYC |
| **Entidade** | Um perfil durável | Existe enquanto o usuário/empresa existir na sua plataforma | O cliente "Jane Doe" com 3 sessões de verificação de usuários (KYC) ao longo de 2 anos |

Uma mesma entidade pode ter várias sessões: reverificações, reenvios, verificações adicionais, monitoramento contínuo periódico. A entidade reúne os resultados.

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

As entidades são criadas de uma de três maneiras:

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

Quando você cria uma sessão com um identificador `vendor_data` e não existe uma 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 Usuário para `user-42` é criada no momento em que a sessão começa.

**2. Pré-criada pela API de gerenciamento**

Crie a entidade primeiro e depois inicie sessões vinculadas a ela. Útil quando você quer definir sinais de risco (status, tags, 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 no console**

Sua equipe de conformidade pode criar usuários ou empresas diretamente no Business Console, o que é útil para onboarding manual, importações ou fluxos de remediação.

## Como as entidades vinculam tudo

O campo `vendor_data` é a chave de vinculação. Quando você passa `vendor_data` em qualquer sessão ou transação, a Didit a direciona 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 vinculação de `vendor_data`](https://docs.didit.me/entities/vendor-data-linking).

## O que você pode fazer com uma entidade

Para cada entidade Usuário ou Empresa, você pode:

| Operação | Finalidade |
| - | - |
| **Criar / atualizar** | Definir ou alterar os dados de perfil da entidade (nome, país, metadados personalizados) |
| **Alterar o status** | Marcar como `ACTIVE`, `FLAGGED` ou `BLOCKED` - a aplicação se propaga para sessões e transações futuras |
| **Anexar biometria** | Enviar uma referência facial para busca 1:N, detecção de duplicidade ou lista de bloqueio |
| **Consultar o histórico de KYC/KYB** | Recuperar todas as sessões vinculadas à entidade, com os resultados por recurso |
| **Consultar o histórico de transações** | Recuperar todas as transações em que a entidade é solicitante ou contraparte |
| **Adicionar a uma lista de bloqueio** | Bloquear sessões ou transações futuras envolvendo esta entidade |
| **Importar / exportar** | Enviar entidades em massa por CSV ou exportá-las para ferramentas externas de conformidade |
| **Excluir** | Excluir a entidade (o histórico é preservado para auditoria) |

Os passo a passo detalhados estão em [Usuários](https://docs.didit.me/entities/users/overview.md) e [Empresas](https://docs.didit.me/entities/businesses/overview.md).

## Relações entre usuário e empresa

Um mesmo Usuário pode estar vinculado a uma ou várias Empresas. Isso acontece naturalmente durante o KYB:

* Um Usuário pode ser **diretor** de uma Empresa e **UBO** de outra.
* A sessão de verificação de usuário (KYC) de um Usuário pode ser vinculada à sessão de verificação de empresa (KYB) de uma Empresa pelo fluxo de [Pessoas-chave](https://docs.didit.me/business-verification/key-people.md).

A Didit preserva essas relações: ao inspecionar uma entidade Empresa, você vê cada Usuário vinculado, e ao inspecionar uma entidade Usuário, você vê cada Empresa a que ele está associado.

## Ciclo de vida e status

Toda entidade tem um status que define se a Didit aplica bloqueios a novas atividades:

| Status | Efeito |
| - | - |
| `ACTIVE` | Normal - sessões e transações seguem como configurado pelos fluxos e regras |
| `FLAGGED` | Sessões e transações são permitidas, mas encaminhadas automaticamente para revisão manual |
| `BLOCKED` | Sessões e transações são recusadas automaticamente e nenhuma nova sessão pode ser criada |

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

## Próximos passos

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

> **[Vinculação por vendor data](https://docs.didit.me/entities/vendor-data-linking.md)**
>
> Como `vendor_data` vincula sessões, transações e entidades.

> **[Usuários](https://docs.didit.me/entities/users/overview.md)**
>
> Detalhes das entidades Usuário, operações e fluxos no console.

> **[Empresas](https://docs.didit.me/entities/businesses/overview.md)**
>
> Detalhes das entidades Empresa, operações e fluxos no console.

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

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


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