Entidades: Utilizadores e Empresas na Didit

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:

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.

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.

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.

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

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

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.

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

Próximos passos

Ciclo de vida

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

Associação por vendor_data

Como o vendor_data associa sessões, transações e entidades.

Utilizadores

Análise detalhada das entidades de Utilizador, operações e fluxos na consola.

Empresas

Análise detalhada das entidades de Empresa, operações e fluxos na consola.

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 de Utilizador e de Empresa.

Visão geral

Preços

Fluxos e verificação

Revisão e operações