Visão Geral de Entidades

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

Empresa

Entidades corporativas para análise KYB

Pessoa

Entidades individuais para análise KYC

Transação

Transações financeiras para monitoramento

Personalizado

Qualquer tipo de entidade personalizado para o seu negócio

Ciclo de Vida da Entidade

Criação

Entidade é criada via API com informações básicas e dados personalizados opcionais

Enriquecimento

Dados adicionais são adicionados através de atualizações ou integrações

Análise

Análise de risco alimentada por IA é gerada automaticamente

Avaliação de Regras

Regras de risco são aplicadas para calcular a pontuação de risco e gerar alertas

Investigação

Alertas acionam investigações para revisão manual

Resolução

Status da entidade é atualizado com base nos resultados da investigação

Status da Entidade

Entidades pessoa e empresa usam o enum Postgres entity_status. Não há um grafo de transições obrigatório: depois da criação, um rótulo da matriz de risco, uma ação de regra (updateEntityStatus), uma automação ou um PATCH manual podem mover a entidade para qualquer status permitido (salvo se changeStatusManual estiver travado).

Padrão na criação

Se você omitir status na criação (manual ou automática), o Gu1 define under_review.
Você pode enviar outro valor explicitamente, por exemplo status: "not_started". Esse valor substitui o padrão, a menos que depois a matriz/regra/automação altere o status novamente.

Valores canônicos

Status	Significado	Uso típico
`not_started`	Cadastrada, revisão/análise ainda não iniciada	Equivalente opt-in ao `NOT_STARTED` da V2. Envie na criação se não quiser o padrão `under_review`.
`under_review`	Em revisão / análise em andamento	Padrão na criação. Também quando regras ou rótulos pedem acompanhamento manual.
`pending_verification`	Aguardando conclusão de KYC/KYB	Verificação de identidade ou empresa ainda pendente (docs/biometria). Diferente de `under_review` (análise de compliance ativa).
`awaiting_information`	Aguardando dados do cliente	Foi pedida informação ao cliente (em geral documentos de onboarding por e-mail) e ele ainda não terminou de enviar. Distinto de `pending_verification` (KYC/KYB de identidade). O agente de onboarding define este status ao enviar o pedido e restaura o anterior após o upload.
`active`	Verificada e operacional (“aprovada”)	Cliente pode operar após onboarding/revisão bem-sucedidos.
`inactive`	Encerrada ou inativa	Fim do relacionamento ou longa inatividade; só consultas históricas.
`suspended`	Suspensão temporária	Operações bloqueadas até resolver; reversível.
`blocked`	Bloqueio permanente de alto risco	Risco confirmado / sanções / ordem judicial; operações bloqueadas.
`rejected`	Onboarding negado	Falhou KYC/KYB ou política; sem operações. Prefira `blocked` se já houve atividade.
`expired`	Dados/documentos vencidos	É preciso renovar documentação.
`deleted`	Soft delete	Auditoria/arquivo; não é um passo normal de onboarding.

Não existe o status approved. Em produto, “aprovado” é active. pending_verification é um status de ciclo de vida suportado (aguardando conclusão de KYC/KYB); awaiting_information é espera de dados pedidos ao cliente (por exemplo documentos de onboarding por e-mail), não captura de identidade. Ambos são distintos de not_started (análise ainda não iniciada) e de under_review (revisão de compliance em andamento). Rótulos legacy V2: NOT_STARTED → not_started, IN_PROGRESS → under_review, APPROVED → active, DENIED → rejected.

Fluxos de exemplo (incluindo matriz de risco)

Não há status intermediário obrigatório entre a criação e a aprovação/negação. O que acontece depende dos rótulos da matriz e das regras:

Criar com not_started → matriz/regras não alteram o status → permanece not_started até algo atualizar.
Criar com not_started → faixa de score ou regra define under_review → precisa de análise manual antes de active / rejected / etc.
Criar com not_started → matriz/regra define active direto → aprovado sem passar por under_review.
Criar com not_started → matriz/regra define rejected ou blocked direto → negado/bloqueado sem status intermediário de revisão.
Criar com o padrão under_review → depois matriz/manual para active ou rejected.

Configure o binding score→status nos rótulos da matriz e/ou ações updateEntityStatus para alinhar ao comportamento da V2.

Bloqueio de operações

Somente blocked, suspended e rejected bloqueiam operações da entidade por padrão. not_started, under_review, pending_verification e awaiting_information não bloqueiam da mesma forma.

Pontuação de Risco

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

Análise de IA

Modelos de machine learning analisam comportamento, padrões e anomalias da entidade

Pontuação Baseada em Regras

Regras personalizadas avaliam condições específicas e atribuem pontos de risco

Verificações de Compliance

Listas de sanções, PEPs, resultados de triagem de mídia adversa

Comportamento Histórico

Padrões de transações, atividade da conta e mudanças ao longo do tempo

Análise de Relacionamentos

Entidades conectadas e seus perfis de risco

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

{
  "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: `"under_review"`)

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:

{
  "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:

{
  "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:

{
  "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

Criar Entidade

POST /entities - Criar nova entidade

Obter Entidade

GET /entities/:id - Recuperar detalhes da entidade

Listar Entidades

GET /entities - Consultar entidades com filtros

Atualizar Entidade

PUT /entities/:id - Atualizar dados da entidade

Excluir Entidade

DELETE /entities/:id - Remover entidade

Importação em Massa

POST /entities/bulk - Importar múltiplas entidades

Melhores Práticas

Use IDs Externos

Sempre defina externalId com seu identificador interno para facilitar a reconciliação e atualizações

Tipos de Entidade Consistentes

Use valores de tipo de entidade consistentes em toda a sua organização (ex: “company” vs “corporate”)

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

Estruture os Dados da Entidade

Organize entityData com nomes de campos consistentes e objetos aninhados para dados complexos

Rastreie Atualizações

Use o timestamp updatedAt para detectar mudanças e sincronizar com seus sistemas

Operações em Massa

Use importação em massa para criar múltiplas entidades (>10) para melhorar o desempenho

Recursos Avançados

Análise Alimentada por IA

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

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 →

Relacionamentos de Entidades

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

{
  "sourceEntityId": "entity_1",
  "targetEntityId": "entity_2",
  "relationshipType": "owns",
  "strength": 0.85
}

Anexos de Documentos

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

POST /documents/entity/:entityId/upload

Saiba mais →

Fluxos de Trabalho de Exemplo

Onboarding KYB

Fluxo de trabalho completo de onboarding de empresas

Verificação KYC

Processo de verificação de clientes individuais

Monitoramento de Transações

Triagem de transações em tempo real

Monitoramento Contínuo

Configuração de monitoramento contínuo de entidades

Próximos Passos

Crie Sua Primeira Entidade

Siga o guia Criar Entidade para adicionar uma entidade

Configure o Mapeamento de Dados

Use Schemas Personalizados para importações estruturadas

Configure Regras

Aplique regras de risco através do painel para calcular pontuações de risco

Monitore e Aja

Configure webhooks para receber alertas quando as pontuações de risco mudarem

​O que são Entidades?

​Tipos de Entidades

Empresa

Pessoa

Transação

Personalizado

​Ciclo de Vida da Entidade

​Status da Entidade

​Padrão na criação

​Valores canônicos

​Fluxos de exemplo (incluindo matriz de risco)

​Bloqueio de operações

​Pontuação de Risco

​Estrutura de Dados da Entidade

​Campos Principais

​Dados Personalizados da Entidade

​Operações Comuns