Fluxo Completo de Empresa (KYB)

Visão Geral

Este guia cobre o fluxo completo para gerenciamento de entidades de empresa (Know Your Business), desde a criação até o enriquecimento, descoberta de acionistas e análise de risco. O fluxo suporta criação automática de acionistas e enriquecimento recursivo de toda a estrutura de propriedade.

Diagrama do Fluxo

Passo 1: Criar Entidade Empresa

Opção A: Criação Automática (Recomendado)

A criação automática lida com enriquecimento, descoberta de acionistas e análise de risco em uma única operação, incluindo criação recursiva de acionistas. Endpoint: POST /entities/automatic Requisição:

{
  "entityType": "company",
  "data": {
    "taxId": "87654321",
    "name": "Acme Corporation",
    "countryCode": "US"
  },
  "enrichmentOptions": {
    "basic": ["company_registry", "sanctions", "adverse_media"],
    "additional": ["financial_records", "legal_filings", "esg_ratings"],
    "createShareholders": true,
    "maxShareholderDepth": 3
  },
  "skipRulesExecution": false,
  "riskMatrixId": "uuid-of-risk-matrix"
}

O que acontece automaticamente:

Enriquecimento de Dados Básicos: Executa provedores da lista basic (registro de empresas, sanções, etc.)
Criação da Empresa: Mapeia dados normalizados para a estrutura de entidade empresa
Enriquecimento Adicional: Executa provedores da lista additional
Descoberta de Acionistas: Extrai acionistas dos dados de enriquecimento
Criação Recursiva de Acionistas:
- Cria entidade pessoa para acionistas individuais
- Cria entidade empresa para acionistas corporativos
- Enriquece cada acionista
- Continua recursivamente até maxShareholderDepth
Atribuição de Matriz de Risco: Atribui a matriz de risco fornecida (ou padrão)
Análise de Risco: Executa regras da matriz de risco automaticamente (a menos que skipRulesExecution: true)

Resposta:

{
  "entity": {
    "id": "company-uuid",
    "organizationId": "uuid",
    "type": "company",
    "name": "Acme Corporation",
    "taxId": "87654321",
    "countryCode": "US",
    "riskScore": "62.00",
    "riskFactors": {
      "reasons": [
        "Mídia adversa encontrada",
        "Acionista em jurisdição de alto risco"
      ],
      "normalizedScore": 55,
      "originalScore": 62,
      "customLabel": {
        "name": "Alto Risco",
        "color": "#ef4444"
      }
    },
    "metadata": {
      "enrichment": {
        "hasData": true,
        "executedProviders": [
          "company_registry_us",
          "sanctions_api",
          "adverse_media",
          "financial_records"
        ],
        "lastExecutedAt": "2025-12-24T10:30:00Z"
      }
    }
  },
  "enrichmentResult": {
    "success": true,
    "providers": [
      "company_registry_us",
      "sanctions_api",
      "adverse_media",
      "financial_records"
    ],
    "dataQuality": 88,
    "confidence": 92
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 5,
    "riskScore": 62
  },
  "shareholders": [
    {
      "id": "person-shareholder-uuid",
      "type": "person",
      "name": "Jane Smith",
      "ownershipPercentage": 35,
      "riskScore": "25.00",
      "enriched": true
    },
    {
      "id": "company-shareholder-uuid",
      "type": "company",
      "name": "Investment Holdings LLC",
      "ownershipPercentage": 40,
      "riskScore": "48.00",
      "enriched": true,
      "shareholders": [
        {
          "id": "nested-person-uuid",
          "type": "person",
          "name": "John Doe",
          "ownershipPercentage": 100,
          "riskScore": "15.00"
        }
      ]
    },
    {
      "id": "person-shareholder-2-uuid",
      "type": "person",
      "name": "Bob Johnson",
      "ownershipPercentage": 25,
      "riskScore": "18.00"
    }
  ]
}

Opção B: Criação Manual

Crie uma entidade empresa com apenas informações básicas, depois enriqueça e analise separadamente. Endpoint: POST /entities Requisição:

{
  "type": "company",
  "name": "Acme Corporation",
  "taxId": "87654321",
  "countryCode": "US",
  "entityData": {
    "company": {
      "legalName": "Acme Corporation Inc.",
      "registrationNumber": "REG123456",
      "incorporationDate": "2010-05-15",
      "industry": "Technology",
      "website": "https://acme-corp.example"
    }
  }
}

Resposta:

{
  "entity": {
    "id": "company-uuid",
    "organizationId": "uuid",
    "type": "company",
    "name": "Acme Corporation",
    "taxId": "87654321",
    "countryCode": "US",
    "status": "active",
    "riskScore": null,
    "metadata": {
      "enrichment": {
        "hasData": false
      }
    }
  }
}

Passo 2: Enriquecer e Analisar (Fluxo Manual)

Se você criou a entidade manualmente, você precisa enriquecê-la e executar a análise de risco. Endpoint: POST /entities/:entityId/analyze Requisição:

{
  "enrichIfNeeded": true,
  "providerCodes": [
    "company_registry_us",
    "sanctions_api",
    "adverse_media",
    "financial_records",
    "beneficial_ownership"
  ],
  "entityType": "company"
}

O que acontece:

Enriquecimento: Executa provedores especificados para coletar dados da empresa
Descoberta de Acionistas: Identifica acionistas dos dados do provedor (mas não cria automaticamente)
Análise de Risco: Executa regras da matriz de risco na empresa
Atualização de Pontuação: Atualiza pontuação de risco e status da empresa

Resposta:

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "company-uuid",
    "entityType": "company",
    "riskScore": 62,
    "overallConfidence": 0.92,
    "totalRules": 15,
    "successfulRules": 5,
    "flags": [
      {
        "type": "ADVERSE_MEDIA",
        "severity": "warning",
        "reason": "Empresa mencionada em 3 artigos de mídia adversa",
        "confidence": 0.88
      },
      {
        "type": "HIGH_RISK_JURISDICTION",
        "severity": "critical",
        "reason": "Acionista sediado em jurisdição de alto risco",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "normalizedScore": 55,
      "originalScore": 62,
      "customLabel": {
        "name": "Alto Risco",
        "minScore": 50,
        "maxScore": 75,
        "color": "#ef4444"
      }
    }
  },
  "rulesTriggered": 5,
  "executionTimeMs": 2100
}

Passo 3: Descoberta e Criação de Acionistas

Criação Automática de Acionistas (via /entities/automatic)

Ao usar criação automática com createShareholders: true, o sistema:

Extrai Acionistas: Dos dados do provedor de enriquecimento (por exemplo, registro de empresas, bancos de dados de propriedade beneficiária)
Cria Entidades: Para cada acionista (pessoa ou empresa)
Enriquece Acionistas: Executa enriquecimento em cada entidade acionista
Processamento Recursivo: Para acionistas empresas, repete o processo até maxShareholderDepth
Vincula Relacionamentos: Cria relacionamentos de propriedade no grafo de entidades

Exemplo de Estrutura de Dados de Acionistas:

{
  "shareholders": [
    {
      "name": "Jane Smith",
      "type": "person",
      "ownershipPercentage": 35,
      "position": "CEO",
      "taxId": "11111111"
    },
    {
      "name": "Investment Holdings LLC",
      "type": "company",
      "ownershipPercentage": 40,
      "taxId": "22222222",
      "countryCode": "US"
    }
  ]
}

Criação Manual de Acionistas

Se você precisa criar acionistas manualmente: Passo 1: Crie a entidade acionista usando POST /entities ou POST /entities/automatic Passo 2: Vincule o acionista à empresa mãe:

POST /entity-relationships
{
  "fromEntityId": "shareholder-uuid",
  "toEntityId": "company-uuid",
  "relationshipType": "SHAREHOLDER_OF",
  "metadata": {
    "ownershipPercentage": 35,
    "position": "Board Member",
    "since": "2020-01-01"
  }
}

Passo 4: Processo de Enriquecimento (Específico para Empresas)

Provedores de Enriquecimento de Empresa

Provedores comuns para enriquecimento de empresa:

company_registry_us: Dados de registro de empresas, executivos, acionistas
company_registry_uk: Dados da Companies House do Reino Unido
company_registry_eu: Registros de empresas europeus
sanctions_api: Triagem de sanções para empresas
adverse_media: Menções em notícias e mídia
financial_records: Demonstrações financeiras, classificações de crédito
beneficial_ownership: Dados de propriedade beneficiária final (UBO)
legal_filings: Processos judiciais, procedimentos legais
esg_ratings: Classificações ambientais, sociais e de governança

Resultado do Enriquecimento (Empresa)

{
  "success": true,
  "entityId": "company-uuid",
  "normalized": {
    "entityType": "company",
    "normalized": {
      "legalName": "Acme Corporation Inc.",
      "tradingNames": ["Acme", "Acme Corp"],
      "registrationNumber": "REG123456",
      "incorporationDate": "2010-05-15",
      "status": "active",
      "industry": "Technology",
      "employees": 150,
      "revenue": 25000000,
      "directors": [
        {
          "name": "Jane Smith",
          "position": "CEO",
          "appointedDate": "2015-03-10"
        }
      ],
      "shareholders": [
        {
          "name": "Jane Smith",
          "ownershipPercentage": 35,
          "type": "person"
        },
        {
          "name": "Investment Holdings LLC",
          "ownershipPercentage": 40,
          "type": "company",
          "countryCode": "US"
        }
      ],
      "sanctionsMatch": false,
      "adverseMedia": [
        {
          "title": "Empresa Resolve Disputa",
          "date": "2023-08-20",
          "source": "Business Journal",
          "sentiment": "negative"
        }
      ],
      "creditRating": "BBB",
      "esgScore": 72
    },
    "providers": [
      "company_registry_us",
      "sanctions_api",
      "adverse_media",
      "financial_records",
      "esg_ratings"
    ],
    "dataQuality": 88,
    "confidence": 92,
    "completeness": 85
  },
  "providers": [
    "company_registry_us",
    "sanctions_api",
    "adverse_media",
    "financial_records",
    "esg_ratings"
  ],
  "totalCostCents": 250,
  "executionTimeMs": 5200,
  "cacheHit": false
}

Passo 5: Análise de Risco (Específica para Empresas)

Exemplos de Regras de Risco para Empresas

Regras de risco comuns para empresas:

Triagem de Sanções: Verificar se empresa ou acionistas estão em listas de sanções
Jurisdição de Alto Risco: Verificar se incorporada ou operando em países de alto risco
Mídia Adversa: Contar artigos de notícias negativas
Saúde Financeira: Avaliar classificação de crédito e índices financeiros
Risco ESG: Verificar pontuações ESG e controvérsias
Estrutura de Propriedade: Analisar risco de acionistas (estruturas complexas, entidades offshore)
Processos Legais: Contar ações judiciais ativas e ações regulatórias
Conexões PEP: Verificar se diretores/acionistas são PEPs

Análise de Risco com Risco de Acionistas

A análise de risco considera:

Risco Direto da Empresa: Baseado nos próprios dados da empresa
Risco de Acionistas: Risco agregado de todos os acionistas
Complexidade de Propriedade: Risco de estruturas de propriedade complexas ou opacas

Exemplo de Resultado:

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "company-uuid",
    "entityType": "company",
    "riskScore": 62,
    "overallConfidence": 0.92,
    "rulesExecuted": [
      {
        "ruleId": "rule-uuid-1",
        "ruleName": "Detecção de Mídia Adversa",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 20
          }
        ]
      },
      {
        "ruleId": "rule-uuid-2",
        "ruleName": "Acionista em Jurisdição de Alto Risco",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 30
          },
          {
            "type": "create_alert",
            "result": {
              "alertId": "alert-uuid"
            }
          }
        ]
      },
      {
        "ruleId": "rule-uuid-3",
        "ruleName": "Verificação de Saúde Financeira",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 12
          }
        ]
      }
    ],
    "flags": [
      {
        "type": "ADVERSE_MEDIA",
        "severity": "warning",
        "reason": "3 artigos de mídia adversa encontrados",
        "confidence": 0.88
      },
      {
        "type": "HIGH_RISK_JURISDICTION",
        "severity": "critical",
        "reason": "Acionista 'Investment Holdings LLC' em jurisdição de alto risco",
        "confidence": 0.95
      }
    ]
  },
  "rulesTriggered": 5,
  "executionTimeMs": 2100
}

Passo 6: Agregação de Risco de Acionistas

Como o Risco de Acionistas Afeta o Risco da Empresa

As empresas podem configurar regras que avaliam o risco de acionistas: Exemplo de Regra: “Alerta de Acionista de Alto Risco”

{
  "name": "Alerta de Acionista de Alto Risco",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "shareholders.riskScore",
        "operator": "greater_than",
        "value": 70
      },
      {
        "field": "shareholders.ownershipPercentage",
        "operator": "greater_than",
        "value": 10
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 40
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Empresa tem acionista de alto risco com propriedade significativa"
    }
  ]
}

Consultando Empresa com Acionistas

Endpoint: GET /entities/:companyId?include=shareholders Resposta:

{
  "entity": {
    "id": "company-uuid",
    "type": "company",
    "name": "Acme Corporation",
    "riskScore": "62.00",
    "shareholders": [
      {
        "id": "shareholder-1-uuid",
        "type": "person",
        "name": "Jane Smith",
        "ownershipPercentage": 35,
        "riskScore": "25.00",
        "relationshipMetadata": {
          "position": "CEO",
          "since": "2015-03-10"
        }
      },
      {
        "id": "shareholder-2-uuid",
        "type": "company",
        "name": "Investment Holdings LLC",
        "ownershipPercentage": 40,
        "riskScore": "78.00",
        "countryCode": "KY",
        "relationshipMetadata": {
          "since": "2018-06-01"
        }
      }
    ]
  }
}

Passo 7: Atualizar por ID Externo

Para empresas criadas via sistemas externos, você pode atualizar usando ID externo: Endpoint: PATCH /entities/by-external-id/:externalId Requisição:

{
  "entityData": {
    "company": {
      "revenue": 30000000,
      "employees": 200,
      "status": "active"
    }
  },
  "metadata": {
    "lastUpdated": "2025-12-24T10:00:00Z",
    "source": "CRM"
  }
}

Casos de Uso:

Sincronizar dados da empresa do CRM
Atualizar dados financeiros do sistema de contabilidade
Atualizar status do registro empresarial

Melhores Práticas

Use Criação Automática com Acionistas: Habilite createShareholders: true para construir a estrutura de propriedade completa automaticamente.
Defina Profundidade Apropriada: Use maxShareholderDepth: 3 para evitar recursão excessiva enquanto captura camadas importantes de propriedade.
Seleção de Provedores: Para empresas, priorize:
- Registro de empresas (obrigatório)
- Bancos de dados de propriedade beneficiária (para descoberta de UBO)
- Triagem de sanções
- Mídia adversa
- Provedores de dados financeiros
Configuração de Matriz de Risco: Configure regras específicas para empresas que avaliem:
- Fatores de risco diretos da empresa
- Risco de acionistas (individual e agregado)
- Complexidade de propriedade
- Risco jurisdicional
Monitoramento de Acionistas: Configure regras para monitorar mudanças de acionistas e acionar reanálise.
Gerenciamento de Custos: Criação de acionistas com enriquecimento pode ser custosa. Monitore custos de provedores e defina limites maxCostCents.
Reenriquecimento Periódico: Dados de empresas mudam ao longo do tempo. Agende reenriquecimento periódico para empresas ativas.
Mapeamento de ID Externo: Sempre defina externalId ao criar empresas de sistemas externos para atualizações fáceis.

Tratamento de Erros

Falhas na Criação de Acionistas

Se a criação de acionistas falhar durante a criação automática:

A entidade empresa principal ainda é criada
Dados parciais de acionistas podem ser armazenados
Detalhes do erro na resposta

Exemplo:

{
  "entity": {...},
  "shareholders": [
    {
      "name": "Jane Smith",
      "status": "created",
      "id": "uuid"
    },
    {
      "name": "Investment Holdings LLC",
      "status": "failed",
      "error": "Dados insuficientes para criar entidade"
    }
  ],
  "warnings": [
    "Falha ao criar 1 de 2 acionistas"
  ]
}

Dados de Propriedade Incompletos

Se os provedores de enriquecimento não retornarem dados de acionistas:

{
  "enrichmentResult": {
    "success": true,
    "shareholders": [],
    "warnings": [
      "Nenhum dado de acionista encontrado dos provedores"
    ]
  }
}

Solução:

Adicionar acionistas manualmente usando POST /entities + POST /entity-relationships
Tentar provedores adicionais de propriedade beneficiária

Limite de Profundidade Recursiva

Se a estrutura de propriedade exceder maxShareholderDepth:

{
  "shareholders": [...],
  "warnings": [
    "Profundidade máxima de acionistas atingida (3 níveis). Acionistas mais profundos não foram criados."
  ]
}

​Visão Geral

​Diagrama do Fluxo

​Passo 1: Criar Entidade Empresa

​Opção A: Criação Automática (Recomendado)

​Opção B: Criação Manual

​Passo 2: Enriquecer e Analisar (Fluxo Manual)

​Passo 3: Descoberta e Criação de Acionistas

​Criação Automática de Acionistas (via /entities/automatic)

​Criação Manual de Acionistas

​Passo 4: Processo de Enriquecimento (Específico para Empresas)

​Provedores de Enriquecimento de Empresa

​Resultado do Enriquecimento (Empresa)

​Passo 5: Análise de Risco (Específica para Empresas)

​Exemplos de Regras de Risco para Empresas

​Análise de Risco com Risco de Acionistas

​Passo 6: Agregação de Risco de Acionistas

​Como o Risco de Acionistas Afeta o Risco da Empresa

​Consultando Empresa com Acionistas

​Passo 7: Atualizar por ID Externo

​Melhores Práticas

​Tratamento de Erros

​Falhas na Criação de Acionistas

​Dados de Propriedade Incompletos

​Limite de Profundidade Recursiva

​Próximos Passos

Visão Geral

Diagrama do Fluxo

Passo 1: Criar Entidade Empresa

Opção A: Criação Automática (Recomendado)

Opção B: Criação Manual

Passo 2: Enriquecer e Analisar (Fluxo Manual)

Passo 3: Descoberta e Criação de Acionistas

Criação Automática de Acionistas (via /entities/automatic)

Criação Manual de Acionistas

Passo 4: Processo de Enriquecimento (Específico para Empresas)

Provedores de Enriquecimento de Empresa

Resultado do Enriquecimento (Empresa)

Passo 5: Análise de Risco (Específica para Empresas)

Exemplos de Regras de Risco para Empresas

Análise de Risco com Risco de Acionistas

Passo 6: Agregação de Risco de Acionistas

Como o Risco de Acionistas Afeta o Risco da Empresa

Consultando Empresa com Acionistas

Passo 7: Atualizar por ID Externo

Melhores Práticas

Tratamento de Erros

Falhas na Criação de Acionistas

Dados de Propriedade Incompletos

Limite de Profundidade Recursiva

Próximos Passos