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

# Flujo Completo de Empresa (KYB)

> Guía de extremo a extremo para crear, enriquecer y analizar entidades de empresa con descubrimiento de accionistas — en el flujo KYB de gu1 para verificación.

## Descripción General

Esta guía cubre el flujo completo para la gestión de entidades de empresa (Know Your Business), desde la creación hasta el enriquecimiento, descubrimiento de accionistas y análisis de riesgo. El flujo admite la creación automática de accionistas y el enriquecimiento recursivo de toda la estructura de propiedad.

## Diagrama de Flujo

```mermaid theme={null}
graph TD
    A[Crear Empresa] --> B{Creación Automática?}
    B -->|Sí| C[POST /entities/automatic]
    B -->|No| D[POST /entities]

    C --> E[Enriquecimiento Básico]
    E --> F[Empresa Creada con Datos]
    F --> G[Enriquecimientos Adicionales]

    D --> H[Empresa Creada - Solo Info Básica]

    G --> I{Crear Accionistas?}
    H --> J{Necesita Enriquecimiento?}

    I -->|Sí| K[Descubrimiento de Accionistas]
    I -->|No| L[Asignación de Matriz de Riesgo]

    J -->|Sí| M[POST /entities/:id/analyze con enriquecimiento]
    J -->|No| N{Matriz de Riesgo Asignada?}

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

    P -->|Persona| Q[Crear Entidad de Persona]
    P -->|Empresa| R[Crear Entidad de Empresa - Recursivo]

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

    T --> U{Profundidad Máxima Alcanzada?}
    U -->|No| K
    U -->|Sí| L

    S --> L
    M --> N

    N -->|Sí| V[Análisis de Riesgo Automático]
    N -->|No| W[Análisis de Riesgo Manual]

    V --> X[Puntaje de Riesgo Calculado]
    W --> Y[POST /entities/:id/analyze]
    Y --> X

    X --> Z[Completo]
```

## Paso 1: Crear Entidad de Empresa

### Opción A: Creación Automática (Recomendado)

La creación automática maneja el enriquecimiento, descubrimiento de accionistas y análisis de riesgo en una sola operación, incluyendo la creación recursiva de accionistas.

**Endpoint**: `POST /entities/automatic`

**Request**:

```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"
}
```

**Lo que sucede automáticamente**:

1. **Enriquecimiento de Datos Básicos**: Ejecuta proveedores de la lista `basic` (registro de empresas, sanciones, etc.)
2. **Creación de Empresa**: Mapea datos normalizados a la estructura de entidad de empresa
3. **Enriquecimiento Adicional**: Ejecuta proveedores de la lista `additional`
4. **Descubrimiento de Accionistas**: Extrae accionistas de los datos de enriquecimiento
5. **Creación Recursiva de Accionistas**:
   * Crea entidad de persona para accionistas individuales
   * Crea entidad de empresa para accionistas corporativos
   * Enriquece cada accionista
   * Continúa recursivamente hasta `maxShareholderDepth`
6. **Asignación de Matriz de Riesgo**: Asigna la matriz de riesgo proporcionada (o la predeterminada)
7. **Análisis de Riesgo**: Ejecuta las reglas de la matriz de riesgo automáticamente (a menos que `skipRulesExecution: true`)

**Response**:

```json theme={null}
{
  "entity": {
    "id": "company-uuid",
    "organizationId": "uuid",
    "type": "company",
    "name": "Acme Corporation",
    "taxId": "87654321",
    "countryCode": "US",
    "riskScore": "62.00",
    "riskFactors": {
      "reasons": [
        "Adverse media found",
        "Shareholder in high-risk jurisdiction"
      ],
      "normalizedScore": 55,
      "originalScore": 62,
      "customLabel": {
        "name": "High Risk",
        "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"
    }
  ]
}
```

### Opción B: Creación Manual

Crea una entidad de empresa solo con información básica, luego enriquece y analiza por separado.

**Endpoint**: `POST /entities`

**Request**:

```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"
    }
  }
}
```

**Response**:

```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
      }
    }
  }
}
```

## Paso 2: Enriquecer y Analizar (Flujo Manual)

Si creaste la entidad manualmente, necesitas enriquecerla y ejecutar el análisis de riesgo.

**Endpoint**: `POST /entities/:entityId/analyze`

**Request**:

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

**Lo que sucede**:

1. **Enriquecimiento**: Ejecuta proveedores especificados para recopilar datos de la empresa
2. **Descubrimiento de Accionistas**: Identifica accionistas de los datos del proveedor (pero no los crea automáticamente)
3. **Análisis de Riesgo**: Ejecuta reglas de la matriz de riesgo en la empresa
4. **Actualización de Puntaje**: Actualiza el puntaje de riesgo y estado de la empresa

**Response**:

```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": "Company mentioned in 3 adverse media articles",
        "confidence": 0.88
      },
      {
        "type": "HIGH_RISK_JURISDICTION",
        "severity": "critical",
        "reason": "Shareholder based in high-risk jurisdiction",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "normalizedScore": 55,
      "originalScore": 62,
      "customLabel": {
        "name": "High Risk",
        "minScore": 50,
        "maxScore": 75,
        "color": "#ef4444"
      }
    }
  },
  "rulesTriggered": 5,
  "executionTimeMs": 2100
}
```

## Paso 3: Descubrimiento y Creación de Accionistas

### Creación Automática de Accionistas (vía /entities/automatic)

Al usar la creación automática con `createShareholders: true`, el sistema:

1. **Extrae Accionistas**: De los datos del proveedor de enriquecimiento (ej., registro de empresas, bases de datos de beneficiarios finales)
2. **Crea Entidades**: Para cada accionista (persona o empresa)
3. **Enriquece Accionistas**: Ejecuta enriquecimiento en cada entidad de accionista
4. **Procesamiento Recursivo**: Para accionistas de empresa, repite el proceso hasta `maxShareholderDepth`
5. **Vincula Relaciones**: Crea relaciones de propiedad en el grafo de entidades

**Ejemplo de Estructura de Datos de Accionistas**:

```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"
    }
  ]
}
```

### Creación Manual de Accionistas

Si necesitas crear accionistas manualmente:

**Paso 1**: Crea la entidad de accionista usando `POST /entities` o `POST /entities/automatic`

**Paso 2**: Vincula el accionista a la empresa matriz:

```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"
  }
}
```

## Paso 4: Proceso de Enriquecimiento (Específico de Empresa)

### Proveedores de Enriquecimiento de Empresa

Proveedores comunes para el enriquecimiento de empresas:

* **company\_registry\_us**: Datos de registro de empresa, directivos, accionistas
* **company\_registry\_uk**: Datos de UK Companies House
* **company\_registry\_eu**: Registros de empresas europeos
* **sanctions\_api**: Verificación de sanciones para empresas
* **adverse\_media**: Menciones en noticias y medios
* **financial\_records**: Estados financieros, calificaciones crediticias
* **beneficial\_ownership**: Datos de beneficiario final último (UBO)
* **legal\_filings**: Casos judiciales, procedimientos legales
* **esg\_ratings**: Calificaciones ambientales, sociales y de gobernanza

### Resultado de Enriquecimiento (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": "Company Settles Dispute",
          "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
}
```

## Paso 5: Análisis de Riesgo (Específico de Empresa)

### Ejemplos de Reglas de Riesgo de Empresa

Reglas de riesgo comunes para empresas:

1. **Verificación de Sanciones**: Verifica si la empresa o accionistas están en listas de sanciones
2. **Jurisdicción de Alto Riesgo**: Verifica si está incorporada u opera en países de alto riesgo
3. **Medios Adversos**: Cuenta artículos de noticias negativas
4. **Salud Financiera**: Evalúa calificación crediticia y ratios financieros
5. **Riesgo ESG**: Verifica puntajes ESG y controversias
6. **Estructura de Propiedad**: Analiza riesgo de accionistas (estructuras complejas, entidades offshore)
7. **Procedimientos Legales**: Cuenta demandas activas y acciones regulatorias
8. **Conexiones PEP**: Verifica si directores/accionistas son PEPs

### Análisis de Riesgo con Riesgo de Accionistas

El análisis de riesgo considera:

* **Riesgo Directo de Empresa**: Basado en los propios datos de la empresa
* **Riesgo de Accionistas**: Riesgo agregado de todos los accionistas
* **Complejidad de Propiedad**: Riesgo de estructuras de propiedad complejas u opacas

**Ejemplo 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": "Adverse Media Detection",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 20
          }
        ]
      },
      {
        "ruleId": "rule-uuid-2",
        "ruleName": "Shareholder High-Risk Jurisdiction",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 30
          },
          {
            "type": "create_alert",
            "result": {
              "alertId": "alert-uuid"
            }
          }
        ]
      },
      {
        "ruleId": "rule-uuid-3",
        "ruleName": "Financial Health Check",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 12
          }
        ]
      }
    ],
    "flags": [
      {
        "type": "ADVERSE_MEDIA",
        "severity": "warning",
        "reason": "3 adverse media articles found",
        "confidence": 0.88
      },
      {
        "type": "HIGH_RISK_JURISDICTION",
        "severity": "critical",
        "reason": "Shareholder 'Investment Holdings LLC' in high-risk jurisdiction",
        "confidence": 0.95
      }
    ]
  },
  "rulesTriggered": 5,
  "executionTimeMs": 2100
}
```

## Paso 6: Agregación de Riesgo de Accionistas

### Cómo el Riesgo de Accionistas Afecta el Riesgo de la Empresa

Las empresas pueden configurar reglas que evalúan el riesgo de los accionistas:

**Ejemplo de Regla**: "Alerta de Accionista de Alto Riesgo"

```json theme={null}
{
  "name": "High-Risk Shareholder Alert",
  "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": "Company has high-risk shareholder with significant ownership"
    }
  ]
}
```

### Consultar Empresa con Accionistas

**Endpoint**: `GET /entities/:companyId?include=shareholders`

**Response**:

```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"
        }
      }
    ]
  }
}
```

## Paso 7: Actualizar por ID Externo

Para empresas creadas a través de sistemas externos, puedes actualizar usando el ID externo:

**Endpoint**: `PATCH /entities/by-external-id/:externalId`

**Request**:

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

**Casos de Uso**:

* Sincronizar datos de empresa desde CRM
* Actualizar datos financieros desde sistema contable
* Actualizar estado desde registro de negocios

## Mejores Prácticas

1. **Usar Creación Automática con Accionistas**: Habilita `createShareholders: true` para construir automáticamente la estructura de propiedad completa.

2. **Establecer Profundidad Apropiada**: Usa `maxShareholderDepth: 3` para prevenir recursión excesiva mientras capturas capas importantes de propiedad.

3. **Selección de Proveedores**: Para empresas, prioriza:
   * Registro de empresas (indispensable)
   * Bases de datos de beneficiarios finales (para descubrimiento de UBO)
   * Verificación de sanciones
   * Medios adversos
   * Proveedores de datos financieros

4. **Configuración de Matriz de Riesgo**: Configura reglas específicas de empresa que evalúen:
   * Factores de riesgo directo de la empresa
   * Riesgo de accionistas (individual y agregado)
   * Complejidad de propiedad
   * Riesgo jurisdiccional

5. **Monitoreo de Accionistas**: Configura reglas para monitorear cambios de accionistas y activar re-análisis.

6. **Gestión de Costos**: La creación de accionistas con enriquecimiento puede ser costosa. Monitorea los costos de proveedores y establece límites de `maxCostCents`.

7. **Re-enriquecimiento Periódico**: Los datos de empresa cambian con el tiempo. Programa re-enriquecimiento periódico para empresas activas.

8. **Mapeo de ID Externo**: Siempre establece `externalId` al crear empresas desde sistemas externos para facilitar actualizaciones.

## Manejo de Errores

### Fallas en Creación de Accionistas

Si la creación de accionistas falla durante la creación automática:

* La entidad de empresa principal aún se crea
* Los datos parciales de accionistas pueden almacenarse
* Detalles de error en la respuesta

**Ejemplo**:

```json theme={null}
{
  "entity": {...},
  "shareholders": [
    {
      "name": "Jane Smith",
      "status": "created",
      "id": "uuid"
    },
    {
      "name": "Investment Holdings LLC",
      "status": "failed",
      "error": "Insufficient data to create entity"
    }
  ],
  "warnings": [
    "Failed to create 1 of 2 shareholders"
  ]
}
```

### Datos de Propiedad Incompletos

Si los proveedores de enriquecimiento no devuelven datos de accionistas:

```json theme={null}
{
  "enrichmentResult": {
    "success": true,
    "shareholders": [],
    "warnings": [
      "No shareholder data found from providers"
    ]
  }
}
```

**Solución**:

* Agregar accionistas manualmente usando `POST /entities` + `POST /entity-relationships`
* Probar proveedores adicionales de beneficiarios finales

### Límite de Profundidad Recursiva

Si la estructura de propiedad excede `maxShareholderDepth`:

```json theme={null}
{
  "shareholders": [...],
  "warnings": [
    "Maximum shareholder depth reached (3 levels). Deeper shareholders not created."
  ]
}
```

## Próximos Pasos

* [Configurar Matriz de Riesgo para Empresas](/es/api-reference/risk-matrix/list)
* [Reglas de Monitoreo de Accionistas](/es/use-cases/kyb/overview)
* [Análisis de Beneficiarios Finales](/es/use-cases/kyb/workflow)
* [Integraciones de Registros de Empresas](/es/api-reference/integrations/provider-codes)