Entidades: usuários e empresas na Didit

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:

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.

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.

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.

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" }'

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. Saiba mais no guia de vinculação de vendor_data.

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 e Empresas.

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.

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 completo, com transições e eventos de webhook.

Próximos passos

Ciclo de vida

Estados, transições e eventos do ciclo de vida de cada entidade.

Vinculação por vendor data

Como vendor_data vincula sessões, transações e entidades.

Usuários

Detalhes das entidades Usuário, operações e fluxos no console.

Empresas

Detalhes das entidades Empresa, operações e fluxos no console.

Webhooks de entidades

Eventos em tempo real para cada alteração de entidade.

Lista de bloqueio

Como as entradas da lista de bloqueio interagem com as entidades Usuário e Empresa.

Visão geral

Fluxos e verificação