> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxo Completo de Empresa (KYB)

> Guia completo para criar, enriquecer e analisar entidades de empresa com descoberta de acionistas — no fluxo KYB da gu1 para verificação empresarial.

## 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

```mermaid theme={null}
graph TD
    A[Criar Empresa] --> B{Criação Automática?}
    B -->|Sim| C[POST /entities/automatic]
    B -->|Não| D[POST /entities]

    C --> E[Enriquecimento Básico]
    E --> F[Empresa Criada com Dados]
    F --> G[Enriquecimentos Adicionais]

    D --> H[Empresa Criada - Apenas Informações Básicas]

    G --> I{Criar Acionistas?}
    H --> J{Precisa de Enriquecimento?}

    I -->|Sim| K[Descoberta de Acionistas]
    I -->|Não| L[Atribuição de Matriz de Risco]

    J -->|Sim| M[POST /entities/:id/analyze com enriquecimento]
    J -->|Não| N{Matriz de Risco Atribuída?}

    K --> O[Para Cada Acionista]
    O --> P{Tipo de Acionista}

    P -->|Pessoa| Q[Criar Entidade Pessoa]
    P -->|Empresa| R[Criar Entidade Empresa - Recursivo]

    Q --> S[Enriquecer Pessoa]
    R --> T[Enriquecer Empresa]

    T --> U{Profundidade Máxima Atingida?}
    U -->|Não| K
    U -->|Sim| L

    S --> L
    M --> N

    N -->|Sim| V[Análise de Risco Automática]
    N -->|Não| W[Análise de Risco Manual]

    V --> X[Pontuação de Risco Calculada]
    W --> Y[POST /entities/:id/analyze]
    Y --> X

    X --> Z[Completo]
```

## 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**:

```json theme={null}
{
  "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**:

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

**Resposta**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "enrichIfNeeded": true,
  "providerCodes": [
    "company_registry_us",
    "sanctions_api",
    "adverse_media",
    "financial_records",
    "beneficial_ownership"
  ],
  "entityType": "company"
}
```

**O que acontece**:

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

**Resposta**:

```json theme={null}
{
  "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:

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

**Exemplo de Estrutura de Dados de Acionistas**:

```json theme={null}
{
  "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:

```json theme={null}
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)

```json theme={null}
{
  "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:

1. **Triagem de Sanções**: Verificar se empresa ou acionistas estão em listas de sanções
2. **Jurisdição de Alto Risco**: Verificar se incorporada ou operando em países de alto risco
3. **Mídia Adversa**: Contar artigos de notícias negativas
4. **Saúde Financeira**: Avaliar classificação de crédito e índices financeiros
5. **Risco ESG**: Verificar pontuações ESG e controvérsias
6. **Estrutura de Propriedade**: Analisar risco de acionistas (estruturas complexas, entidades offshore)
7. **Processos Legais**: Contar ações judiciais ativas e ações regulatórias
8. **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**:

```json theme={null}
{
  "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"

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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

1. **Use Criação Automática com Acionistas**: Habilite `createShareholders: true` para construir a estrutura de propriedade completa automaticamente.

2. **Defina Profundidade Apropriada**: Use `maxShareholderDepth: 3` para evitar recursão excessiva enquanto captura camadas importantes de propriedade.

3. **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

4. **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

5. **Monitoramento de Acionistas**: Configure regras para monitorar mudanças de acionistas e acionar reanálise.

6. **Gerenciamento de Custos**: Criação de acionistas com enriquecimento pode ser custosa. Monitore custos de provedores e defina limites `maxCostCents`.

7. **Reenriquecimento Periódico**: Dados de empresas mudam ao longo do tempo. Agende reenriquecimento periódico para empresas ativas.

8. **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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`:

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

## Próximos Passos

* [Configurar Matriz de Risco para Empresas](/pt/api-reference/risk-matrix/list)
* [Regras de Monitoramento de Acionistas](/pt/use-cases/kyb/overview)
* [Análise de Propriedade Beneficiária](/pt/use-cases/kyb/workflow)
* [Integrações de Registros de Empresas](/pt/api-reference/integrations/provider-codes)