Flujo Completo de Empresa (KYB)

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

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:

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

Enriquecimiento de Datos Básicos: Ejecuta proveedores de la lista basic (registro de empresas, sanciones, etc.)
Creación de Empresa: Mapea datos normalizados a la estructura de entidad de empresa
Enriquecimiento Adicional: Ejecuta proveedores de la lista additional
Descubrimiento de Accionistas: Extrae accionistas de los datos de enriquecimiento
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
Asignación de Matriz de Riesgo: Asigna la matriz de riesgo proporcionada (o la predeterminada)
Análisis de Riesgo: Ejecuta las reglas de la matriz de riesgo automáticamente (a menos que skipRulesExecution: true)

Response:

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

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

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

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

Lo que sucede:

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

Response:

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

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

Ejemplo de Estructura de Datos de Accionistas:

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

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)

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

Verificación de Sanciones: Verifica si la empresa o accionistas están en listas de sanciones
Jurisdicción de Alto Riesgo: Verifica si está incorporada u opera en países de alto riesgo
Medios Adversos: Cuenta artículos de noticias negativas
Salud Financiera: Evalúa calificación crediticia y ratios financieros
Riesgo ESG: Verifica puntajes ESG y controversias
Estructura de Propiedad: Analiza riesgo de accionistas (estructuras complejas, entidades offshore)
Procedimientos Legales: Cuenta demandas activas y acciones regulatorias
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:

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

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

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

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

Usar Creación Automática con Accionistas: Habilita createShareholders: true para construir automáticamente la estructura de propiedad completa.
Establecer Profundidad Apropiada: Usa maxShareholderDepth: 3 para prevenir recursión excesiva mientras capturas capas importantes de propiedad.
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
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
Monitoreo de Accionistas: Configura reglas para monitorear cambios de accionistas y activar re-análisis.
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.
Re-enriquecimiento Periódico: Los datos de empresa cambian con el tiempo. Programa re-enriquecimiento periódico para empresas activas.
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:

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

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

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

Comenzando

Casos de Uso

Webhooks

Persona

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

​Descripción General

​Diagrama de Flujo

​Paso 1: Crear Entidad de Empresa

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

​Opción B: Creación Manual

​Paso 2: Enriquecer y Analizar (Flujo Manual)

​Paso 3: Descubrimiento y Creación de Accionistas

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

​Creación Manual de Accionistas

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

​Proveedores de Enriquecimiento de Empresa

​Resultado de Enriquecimiento (Empresa)

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

​Ejemplos de Reglas de Riesgo de Empresa

​Análisis de Riesgo con Riesgo de Accionistas

​Paso 6: Agregación de Riesgo de Accionistas

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

​Consultar Empresa con Accionistas

​Paso 7: Actualizar por ID Externo

​Mejores Prácticas

​Manejo de Errores

​Fallas en Creación de Accionistas

​Datos de Propiedad Incompletos

​Límite de Profundidad Recursiva

​Próximos Pasos

Descripción General

Diagrama de Flujo

Paso 1: Crear Entidad de Empresa

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

Opción B: Creación Manual

Paso 2: Enriquecer y Analizar (Flujo Manual)

Paso 3: Descubrimiento y Creación de Accionistas

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

Creación Manual de Accionistas

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

Proveedores de Enriquecimiento de Empresa

Resultado de Enriquecimiento (Empresa)

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

Ejemplos de Reglas de Riesgo de Empresa

Análisis de Riesgo con Riesgo de Accionistas

Paso 6: Agregación de Riesgo de Accionistas

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

Consultar Empresa con Accionistas

Paso 7: Actualizar por ID Externo

Mejores Prácticas

Manejo de Errores

Fallas en Creación de Accionistas

Datos de Propiedad Incompletos

Límite de Profundidad Recursiva

Próximos Pasos