Skip to main content

​
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

1

Criação

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

Enriquecimento

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

Análise

Análise de risco alimentada por IA é gerada automaticamente
4

Avaliação de Regras

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

Investigação

Alertas acionam investigações para revisão manual
6

Resolução

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

​
Status da Entidade

Entidades podem ter diferentes status ao longo do seu ciclo de vida:
StatusDescriçãoCaso de Uso
activeEntidade está ativa e sendo monitoradaOperação normal
inactiveEntidade não está mais ativaContas encerradas
under_reviewEntidade está sendo investigadaAlerta acionado
approvedEntidade passou em todas as verificaçõesBaixo risco
rejectedEntidade falhou nas verificações de complianceAlto risco
suspendedEntidade temporariamente suspensaInformação pendente

​
Pontuação de Risco

Cada entidade tem uma pontuação de risco (0-100) calculada com base em:
Modelos de machine learning analisam comportamento, padrões e anomalias da entidade
Regras personalizadas avaliam condições específicas e atribuem pontos de risco
Listas de sanções, PEPs, resultados de triagem de mídia adversa
Padrões de transações, atividade da conta e mudanças ao longo do tempo
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

CampoTipoObrigatórioDescrição
typestringSimTipo de entidade (company, person, transaction, custom)
namestringSimNome da entidade
externalIdstringNãoSeu identificador único para esta entidade
countrystringNãoCódigo de país ISO (ex: “US”, “UK”)
entityDataobjectNãoJSON flexível para campos personalizados
riskScorenumberNãoPontuação de risco 0-100 (calculada automaticamente)
statusenumNãoStatus da entidade (padrão: “active”)

​
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

Sempre defina externalId com seu identificador interno para facilitar a reconciliação e atualizações
Use valores de tipo de entidade consistentes em toda a sua organização (ex: “company” vs “corporate”)
Sempre inclua códigos de país ISO para avaliação de risco adequada e verificações de compliance
Organize entityData com nomes de campos consistentes e objetos aninhados para dados complexos
Use o timestamp updatedAt para detectar mudanças e sincronizar com seus sistemas
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

1

Crie Sua Primeira Entidade

Siga o guia Criar Entidade para adicionar uma entidade
2

Configure o Mapeamento de Dados

Use Schemas Personalizados para importações estruturadas
3

Configure Regras

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

Monitore e Aja

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