Flujo Completo de Persona (KYC)

​

Descripción General

​

Automático vs Manual: ¿Cuál deberías usar?

• Necesitas recopilar datos de usuario incrementalmente en múltiples pasos
• Quieres mostrar a los usuarios un indicador de progreso entre etapas
• Estás depurando y quieres inspeccionar datos entre operaciones
• Tienes lógica de negocio personalizada entre creación de entidad y análisis de riesgo

​

Configuración de Matriz de Riesgo

​

¿Qué es una Matriz de Riesgo?

• Qué puntos de datos verificar (estado PEP, sanciones, medios adversos, etc.)
• Qué puntuación de riesgo asignar cuando se cumplen condiciones
• Si aprobar, rechazar o marcar entidades para revisión
• Etiquetas de riesgo personalizadas (Bajo/Medio/Alto) basadas en rangos de puntuación

​

Cómo Configurar tu Matriz de Riesgo

1. Inicia sesión en el Dashboard de gu1: https://app.gu1.ai
2. Navega a Matrices de Riesgo: Configuración → Matrices de Riesgo
3. Crea una Nueva Matriz: Clic en “Nueva Matriz de Riesgo”
4. Configura Reglas: Agrega reglas que coincidan con tus requisitos de cumplimiento
   • Ejemplo: “Si se detecta PEP → agregar 25 puntos a puntuación de riesgo”
   • Ejemplo: “Si hay coincidencia de sanciones → rechazar y crear alerta”
5. Establece Etiquetas Personalizadas: Define rangos de puntuación (ej: 0-25: Bajo, 26-50: Medio, 51-100: Alto)
6. Guarda y Copia ID: Guarda la matriz y copia el UUID - lo usarás en llamadas API

​

Usar Matriz de Riesgo en API

{
  "riskMatrixId": "uuid-of-risk-matrix"
}

• Navega a Configuración → Organización
• Establece “Matriz de Riesgo Predeterminada para Personas”
• Todas las entidades de persona usarán esta matriz a menos que se anule

​

Tutorial: Configurando tu Primera Matriz de Riesgo

• Referencia API de Matriz de Riesgo
• Onboarding de Personas con Matriz de Riesgo
• Onboarding de Empresas con Matriz de Riesgo

​

Diagrama de Flujo

​

Paso 1: Crear Entidad de Persona

​

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

{
  "entityType": "person",
  "data": {
    "taxId": "12345678",
    "name": "John Doe",
    "countryCode": "US"
  },
  "enrichmentOptions": {
    "basic": ["identity_verification", "sanctions", "pep"],
    "additional": ["adverse_media", "legal_records"],
    "createShareholders": true,  // ⚠️ Solo para entidades empresa (KYB), no personas (KYC)
    "maxShareholderDepth": 2     // ⚠️ Solo para entidades empresa (KYB), no personas (KYC)
  },
  "skipRulesExecution": false,
  "riskMatrixId": "uuid-of-risk-matrix"  // Opcional - ver "Configuración de Matriz de Riesgo" arriba
}

1. Enriquecimiento de Datos Básicos: Ejecuta proveedores de la lista basic
2. Creación de Entidad: Mapea datos normalizados a la estructura de entidad
3. Enriquecimiento Adicional: Ejecuta proveedores de la lista additional
4. Descubrimiento de Accionistas: Crea recursivamente entidades de accionistas (si está habilitado) - ⚠️ Solo empresas
5. Asignación de Matriz de Riesgo: Asigna la matriz de riesgo proporcionada (o la predeterminada)
6. Análisis de Riesgo: Ejecuta reglas de la matriz de riesgo automáticamente (a menos que skipRulesExecution: true)

{
  "entity": {
    "id": "uuid",
    "organizationId": "uuid",
    "type": "person",
    "name": "John Doe",
    "taxId": "12345678",
    "countryCode": "US",
    "riskScore": "45.00",
    "riskFactors": {
      "reasons": ["Coincidencia PEP encontrada", "Verificación de sanciones aprobada"],
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Riesgo Medio",
        "color": "#f59e0b"
      }
    },
    "metadata": {
      "enrichment": {
        "hasData": true,
        "executedProviders": ["world_check", "sanctions_api", "pep_database"],
        "lastExecutedAt": "2025-12-24T10:30:00Z"
      }
    }
  },
  "enrichmentResult": {
    "success": true,
    "providers": ["world_check", "sanctions_api", "pep_database"],
    "dataQuality": 85,
    "confidence": 90
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "riskScore": 45
  },
  "shareholders": [
    {
      "id": "shareholder-uuid",
      "name": "Company ABC",
      "ownershipPercentage": 25
    }
  ]
}

​

Opción B: Creación Manual

{
  "type": "person",
  "name": "John Doe",
  "taxId": "12345678",
  "countryCode": "US",
  "entityData": {
    "person": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-15",
      "nationality": "US"
    }
  }
}

{
  "entity": {
    "id": "uuid",
    "organizationId": "uuid",
    "type": "person",
    "name": "John Doe",
    "taxId": "12345678",
    "countryCode": "US",
    "status": "active",
    "riskScore": null,
    "metadata": {
      "enrichment": {
        "hasData": false
      }
    }
  }
}

​

Paso 2: Enriquecer y Analizar (Flujo Manual)

{
  "enrichIfNeeded": true,
  "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media"],
  "entityType": "person"
}

1. Enriquecimiento Opcional: Si enrichIfNeeded: true o se proporcionan providerCodes, ejecuta el enriquecimiento primero
2. Análisis de Riesgo: Ejecuta reglas de la matriz de riesgo en la entidad
3. Actualización de Puntuación: Actualiza la puntuación de riesgo y el estado de la entidad

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "uuid",
    "entityType": "person",
    "riskScore": 45,
    "overallConfidence": 0.9,
    "totalRules": 10,
    "successfulRules": 3,
    "flags": [
      {
        "type": "PEP",
        "severity": "warning",
        "reason": "Persona identificada como Persona Políticamente Expuesta",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Riesgo Medio",
        "minScore": 25,
        "maxScore": 50,
        "color": "#f59e0b"
      }
    }
  },
  "rulesTriggered": 3,
  "executionTimeMs": 1250
}

​

Paso 3: Proceso de Enriquecimiento (Análisis Profundo)

​

Cómo Funciona el Enriquecimiento

1. Selección de Proveedores:
   • Si se especifican providerCodes: usa esos proveedores específicos
   • De lo contrario: selecciona automáticamente según las suscripciones de la organización y el tipo de entidad
2. Validación de Saldo:
   • Calcula el costo total de todos los proveedores seleccionados
   • Verifica el saldo de créditos de la organización
   • Lanza InsufficientBalanceError si el saldo es insuficiente
3. Ejecución Paralela:
   • TODOS los proveedores se ejecutan concurrentemente (hasta 15 simultáneos)
   • Cada proveedor tiene timeout individual (predeterminado: 7.5s, judicial: 15s)
   • Las fallas en un proveedor no afectan a otros
   • Tiempo total de ejecución = proveedor más lento
4. Normalización de Datos:
   • Datos crudos del proveedor normalizados a formato estándar
   • Resolución de conflictos a nivel de campo (mayor confianza, más reciente, mayoría)
   • Fusión inteligente con datos de enriquecimiento existentes
   • Puntuaciones de calidad calculadas a partir de todos los resultados de proveedores
5. Almacenamiento de Datos:
   • Tabla normalized_enrichment: datos normalizados/mapeados
   • Tabla enrichment_data_current: instantánea de enriquecimiento actual
   • Tabla audit_enrichment: auditoría de ejecución individual de proveedores
   • entities.metadata.enrichment: caché de metadatos de ejecución
6. Deducción de Créditos:
   • El saldo se deduce solo DESPUÉS de una ejecución exitosa
   • Costos: varían según el proveedor (ej., WorldCheck: $0.50, Sanctions:$0.25)

​

Cómo Funciona la Gestión de Créditos

1. Pre-validación: Antes de que comience el enriquecimiento, el sistema verifica si tienes saldo suficiente
2. Ejecución: Los proveedores se ejecutan en paralelo (solo se cobra por ejecuciones exitosas)
3. Deducción: Los créditos se deducen DESPUÉS de la finalización exitosa (no por adelantado)
4. Proveedores fallidos: Sin cargo si un proveedor falla o agota el tiempo

• global_gueno_validation_kyc: $2.00 por verificación
• world_check: $0.50 por verificación
• sanctions_api: $0.25 por screening
• pep_database: $0.25 por verificación
• adverse_media: $0.30 por búsqueda
• legal_records: $0.40 por búsqueda

GET /api/billing/balance

GET /api/billing/transactions

• Navega a Dashboard → Facturación → Créditos
• Compra paquetes de créditos o configura recarga automática

{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}

​

Estructura del Resultado de Enriquecimiento

{
  "success": true,
  "entityId": "uuid",
  "normalized": {
    "entityType": "person",
    "normalized": {
      "fullName": "John Doe",
      "dateOfBirth": "1980-01-15",
      "nationality": "US",
      "isPep": true,
      "sanctionsMatch": false,
      "adverseMedia": [
        {
          "title": "Investigación Comercial",
          "date": "2023-05-10",
          "source": "Financial Times"
        }
      ]
    },
    "providers": ["world_check", "sanctions_api", "adverse_media"],
    "dataQuality": 85,
    "confidence": 90,
    "completeness": 78
  },
  "providers": ["world_check", "sanctions_api", "adverse_media"],
  "totalCostCents": 100,
  "executionTimeMs": 3500,
  "cacheHit": false,
  "metadata": {
    "providersAttempted": 3,
    "providersSucceeded": 3,
    "providersFailed": 0,
    "dataQuality": 85,
    "confidence": 90
  }
}

​

Paso 4: Análisis de Riesgo (Análisis Profundo)

​

Cómo Funciona el Análisis de Riesgo

1. Selección de Estrategia:
   • Usa la matriz de riesgo asignada a la entidad
   • La matriz de riesgo define qué reglas aplican y la estrategia de evaluación
2. Carga de Datos:
   • Carga la entidad con datos de enriquecimiento
   • Carga la entidad con validación KYC (si existe)
   • Prepara el contexto de ejecución
3. Validación de Cobertura (Solo Persona/Compañía):
   • Extrae todos los campos requeridos por las condiciones de las reglas
   • Valida que los proveedores ejecutados cubran todos los campos de enriquecimiento requeridos
   • Valida que exista validación KYC si se requieren campos KYC
   • Retorna error con campos faltantes y proveedores recomendados si está incompleto
4. Ejecución de Reglas:
   • Filtra reglas por evento disparador (ej., “enrichment_completed”, “manual_evaluation”)
   • Ejecuta reglas en paralelo usando UniversalRulesEngine
   • Cada regla evalúa condiciones y ejecuta acciones si coincide
5. Cálculo de Puntuación:
   • Acumula puntuaciones de las reglas que coinciden
   • Aplica estrategia de evaluación (score_based o confidence_based)
   • Normaliza la puntuación si hay etiquetas personalizadas configuradas
   • Calcula etiqueta personalizada basada en el rango de puntuación
6. Actualizaciones de Estado:
   • Actualiza la puntuación de riesgo y los factores de riesgo de la entidad
   • Actualiza el estado de la entidad si las reglas desencadenaron un cambio de estado
   • Envía notificación ENTITY_STATUS_CHANGED
7. Registro de Auditoría:
   • Crea registro de evaluación
   • Registra evento de ejecución
   • Crea auditoría de análisis de riesgo con detalles completos de ejecución
   • Registra alertas creadas por acciones de reglas
8. Consolidación de Alertas:
   • Después de un retraso de 5 segundos, consolida alertas relacionadas
   • Crea o actualiza investigaciones
   • Envía notificaciones apropiadas

​

Estructura del Resultado de Análisis de Riesgo

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "uuid",
    "entityType": "person",
    "riskScore": 45,
    "overallConfidence": 0.9,
    "totalRules": 10,
    "successfulRules": 3,
    "failedRules": 0,
    "rulesExecuted": [
      {
        "ruleId": "rule-uuid",
        "ruleName": "Detección PEP",
        "executed": true,
        "conditionsMet": true,
        "confidence": 0.95,
        "executionTime": 50,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 25
          },
          {
            "type": "create_alert",
            "result": {
              "alertId": "alert-uuid"
            }
          }
        ]
      }
    ],
    "flags": [
      {
        "type": "PEP",
        "severity": "warning",
        "reason": "Persona identificada como Persona Políticamente Expuesta",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "strategyType": "score_based",
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Riesgo Medio",
        "minScore": 25,
        "maxScore": 50,
        "color": "#f59e0b",
        "severity": "medium"
      },
      "displayRange": "25-50"
    }
  },
  "rulesTriggered": 3,
  "executionTimeMs": 1250,
  "auditId": "audit-uuid"
}

​

Paso 5: Validación KYC (Opcional)

​

Crear Validación KYC

{
  "entityId": "uuid",
  "provider": "persona",
  "templateId": "tmpl_ABC123",
  "requiredFields": ["government_id", "selfie"],
  "callbackUrl": "https://your-app.com/webhooks/kyc"
}

{
  "validation": {
    "id": "kyc-uuid",
    "entityId": "entity-uuid",
    "provider": "persona",
    "status": "pending",
    "validationUrl": "https://kyc-provider.com/start?token=abc123",
    "expiresAt": "2025-12-31T23:59:59Z"
  }
}

​

Usuario Completa KYC

1. Envía al usuario a validationUrl
2. El usuario completa el flujo KYC (carga documentos, toma selfie, etc.)
3. El proveedor KYC envía webhook a tu callbackUrl

​

Webhook: Actualización de Estado KYC

{
  "event": "kyc.completed",
  "validationId": "kyc-uuid",
  "entityId": "entity-uuid",
  "status": "approved",
  "data": {
    "documentVerified": true,
    "livenessCheck": true,
    "faceMatch": 98.5,
    "documentType": "passport",
    "documentNumber": "AB1234567",
    "verifiedAt": "2025-12-24T15:30:00Z"
  }
}

​

Re-ejecutar Análisis de Riesgo Después del KYC

{
  "enrichIfNeeded": false,
  "entityType": "person"
}

​

Paso 6: Monitorear y Gestionar

​

Consultar Estado de Entidad

• Puntuación de riesgo actual (normalizada y original)
• Factores de riesgo y banderas
• Estado de enriquecimiento y proveedores utilizados
• Estado de validación KYC
• Timestamp de última evaluación de riesgo

​

Ver Historial de Análisis de Riesgo

• Todas las ejecuciones de análisis de riesgo
• Reglas coincidentes en cada ejecución
• Cambios de puntuación a lo largo del tiempo
• Datos de enriquecimiento utilizados

​

Ver Alertas e Investigaciones

• Alertas consolidadas relacionadas con la entidad
• Estado y prioridad de la investigación
• Analistas asignados y notas de resolución

​

Mejores Prácticas

1. Usar Creación Automática: Para la mayoría de los casos, usa POST /entities/automatic para manejar enriquecimiento y análisis de riesgo en una operación.
2. Gestión de Saldo: Siempre asegura suficientes créditos antes del enriquecimiento. Monitorea el saldo usando GET /billing/balance.
3. Selección de Proveedores: Usa providerCodes específicos cuando sepas qué datos necesitas. La selección automática puede incluir proveedores innecesarios.
4. Asignación de Matriz de Riesgo: Siempre asigna una matriz de riesgo al crear entidades. Sin una matriz de riesgo, el análisis de riesgo no se ejecutará para entidades de persona/compañía.
5. Tiempo del KYC: Inicia la validación KYC temprano en el flujo de incorporación. Algunas reglas pueden requerir datos de KYC.
6. Validación de Cobertura: Si el análisis de riesgo falla debido a cobertura incompleta, verifica los metadata.missingFields y ejecuta los proveedores recomendados.
7. Seguridad de Webhooks: Siempre valida las firmas de webhooks de los proveedores KYC para prevenir falsificación.
8. Monitoreo: Configura alertas para entidades de alto riesgo y enriquecimientos fallidos.

​

Manejo de Errores

​

Errores Comunes

{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}

{
  "success": false,
  "error": "Incomplete data coverage",
  "warnings": [
    "Field 'sanctions.matches' requires provider: world_check or sanctions_api",
    "Field 'kyc.documentVerified' requires KYC validation"
  ],
  "metadata": {
    "missingFields": [...],
    "recommendedProviders": ["world_check", "sanctions_api"]
  }
}

{
  "success": true,
  "executed": false,
  "error": "No risk matrix assigned to person entity. Please assign a Risk Matrix to enable rule execution."
}

​

Próximos Pasos

• Configurar Reglas de Matriz de Riesgo
• Configurar Webhooks
• Gestionar Integraciones de Proveedores
• Monitorear Uso de Créditos