> ## 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 Persona (KYC)

> Guía completa para crear, enriquecer y analizar entidades de persona con validación KYC — en la API KYC de gu1 para flujos de verificación de identidad.

## Descripción General

Esta guía cubre el flujo completo para la gestión de entidades de persona, desde la creación hasta el enriquecimiento, validación KYC y análisis de riesgo. El flujo está diseñado para ser flexible, soportando tanto procesos automáticos como manuales en cada etapa.

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

<Note>
  **Respuesta Rápida**: Usa **Automático** para la mayoría de casos. Maneja todo en una llamada API y es más rápido de integrar.
</Note>

| Característica                    | Creación Automática                                 | Creación Manual                                                     |
| --------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
| **Llamadas API Requeridas**       | 1 llamada (`POST /entities/automatic`)              | 2-3 llamadas (`POST /entities`, luego `POST /entities/:id/analyze`) |
| **Enriquecimiento**               | Automático - se ejecuta en segundo plano            | Manual - lo activas por separado                                    |
| **Análisis de Riesgo**            | Automático - se ejecuta después del enriquecimiento | Manual - lo activas por separado                                    |
| **Descubrimiento de Accionistas** | Opcional - configurable en la solicitud             | No disponible                                                       |
| **Complejidad de Integración**    | Simple - proceso de un paso                         | Complejo - orquestar múltiples pasos                                |
| **Deducción de Créditos**         | Automática                                          | Automática (por operación)                                          |
| **Usar Cuando**                   | Flujos de onboarding estándar                       | Necesitas control granular del timing                               |
| **Mejor Para**                    | Apps de producción, procesamiento batch             | Testing, debugging, flujos personalizados                           |

**Cuándo usar Creación Manual:**

* 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

<Warning>
  **¿Quién Define la Matriz de Riesgo?** Configuras las reglas de tu matriz de riesgo en el dashboard de gu1 antes de usar la API.
</Warning>

### ¿Qué es una Matriz de Riesgo?

Una **Matriz de Riesgo** es una colección de reglas que definen cómo se califican las entidades por riesgo. Piénsalo como tu manual de cumplimiento - determina:

* 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](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

**Opción 1: Especificar en solicitud API** (recomendado para configuraciones multi-tenant):

```json theme={null}
{
  "riskMatrixId": "uuid-of-risk-matrix"
}
```

**Opción 2: Establecer predeterminado de organización** en el dashboard:

* 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

Para un tutorial detallado, consulta nuestras guías:

* [Referencia API de Matriz de Riesgo](/en/api-reference/risk-matrix/execute-risk-matrix)
* [Onboarding de Personas con Matriz de Riesgo](/en/use-cases/onboarding/person-automatic-with-risk-matrix)
* [Onboarding de Empresas con Matriz de Riesgo](/en/use-cases/onboarding/company-automatic-with-risk-matrix)

## Diagrama de Flujo

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

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

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

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

    I -->|Sí| K[Creación Recursiva 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 --> L
    M --> N

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

    O --> Q[Puntuación de Riesgo Calculada]
    P --> R[POST /entities/:id/analyze]
    R --> Q

    Q --> S{¿Necesita KYC?}
    S -->|Sí| T[POST /kyc-validations]
    S -->|No| U[Completo]

    T --> V[Usuario Completa KYC]
    V --> W[Webhook: Actualización de Estado KYC]
    W --> X[Re-ejecutar Análisis de Riesgo]
    X --> U
```

## Paso 1: Crear Entidad de Persona

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

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

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

**Solicitud**:

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

**Lo que sucede automáticamente**:

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

<Info>
  **Nota sobre Accionistas (createShareholders)**: Esta característica solo es aplicable para **entidades empresa (KYB)**, no entidades persona (KYC).

  Cuando verificas una **empresa**, puedes habilitar `createShareholders: true` para descubrir y crear automáticamente entidades para todos los beneficiarios finales y accionistas corporativos.

  Para **entidades persona (KYC)**, este campo se ignora ya que los individuos no tienen accionistas. Si estás implementando verificación de personas (KYC), puedes omitir este campo completamente.
</Info>

**Respuesta**:

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

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

**Endpoint**: `POST /entities`

**Solicitud**:

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

**Respuesta**:

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

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

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

**Solicitud**:

```json theme={null}
{
  "enrichIfNeeded": true,
  "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media"],
  "entityType": "person"
}
```

<Accordion title="Códigos de Proveedor Disponibles para KYC">
  **Códigos de Proveedor Estándar** (más utilizados):

  * `global_gueno_validation_kyc` - **Recomendado para KYC completo** - Verificación integral de identidad incluyendo documento + liveness + face match
  * `world_check` - Screening PEP y sanciones (Refinitiv WorldCheck)
  * `sanctions_api` - Screening de listas globales de sanciones
  * `pep_database` - Detección de Personas Políticamente Expuestas
  * `adverse_media` - Monitoreo de noticias negativas y medios
  * `legal_records` - Registros judiciales y procedimientos legales
  * `identity_verification` - Validación básica de identidad

  **Cómo Elegir Códigos de Proveedor:**

  1. **Para Verificación KYC Completa** (documento + selfie + face match):
     ```json theme={null}
     "providerCodes": ["global_gueno_validation_kyc"]
     ```

  2. **Solo Screening AML** (sin carga de documentos):
     ```json theme={null}
     "providerCodes": ["world_check", "sanctions_api", "pep_database"]
     ```

  3. **Para Debida Diligencia Reforzada**:
     ```json theme={null}
     "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media", "legal_records"]
     ```

  **Nota**: Los proveedores disponibles dependen de las suscripciones de tu organización. Contacta soporte si necesitas acceso a proveedores específicos.
</Accordion>

**Lo que sucede**:

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

**Respuesta**:

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

El servicio **EnrichmentOrchestrator** maneja todas las operaciones de 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

<Warning>
  **Importante**: Los créditos se deducen del saldo de tu organización cuando los proveedores de enriquecimiento se ejecutan exitosamente.
</Warning>

**Flujo de Deducció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

**Costos Típicos** (varía según el plan de suscripción):

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

**Consulta tu Saldo:**

```bash theme={null}
GET /api/billing/balance
```

**Monitorea Uso de Créditos:**

```bash theme={null}
GET /api/billing/transactions
```

**Agrega Créditos:**

* Navega a [Dashboard → Facturación → Créditos](https://app.gu1.ai/billing/credits)
* Compra paquetes de créditos o configura recarga automática

**Error de Saldo Insuficiente:**

```json theme={null}
{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}
```

**Solución**: Agrega créditos a tu cuenta antes de ejecutar operaciones de enriquecimiento.

Para precios detallados y gestión de créditos, consulta tu [Dashboard → Facturación → Créditos](https://app.gu1.ai/billing/credits).

### Estructura del Resultado de Enriquecimiento

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

El servicio **RulesExecutionService** maneja todas las operaciones de 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

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

Si las reglas de tu matriz de riesgo requieren campos de validación KYC (como `kyc.documentVerified`, `kyc.livenessCheck`), necesitas crear una validación KYC.

### Crear Validación KYC

**Endpoint**: `POST /kyc-validations`

**Solicitud**:

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

**Respuesta**:

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

Cuando el KYC se completa, tu webhook recibe:

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

Una vez que el KYC se completa, re-ejecuta el análisis de riesgo para evaluar reglas dependientes del KYC:

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

**Solicitud**:

```json theme={null}
{
  "enrichIfNeeded": false,
  "entityType": "person"
}
```

Ahora las reglas que verifican campos `kyc.*` se evaluarán correctamente y se calculará la puntuación de riesgo final de la entidad.

## Paso 6: Monitorear y Gestionar

### Consultar Estado de Entidad

**Endpoint**: `GET /entities/:entityId`

**La respuesta incluye**:

* 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

**Endpoint**: `GET /risk-analysis-audits?entityId=:entityId`

**Retorna**:

* 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

**Endpoint**: `GET /investigations?entityId=:entityId`

**Retorna**:

* 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

**Saldo Insuficiente**:

```json theme={null}
{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}
```

**Solución**: Agrega créditos a la cuenta de facturación de la organización.

**Cobertura Incompleta**:

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

**Solución**: Ejecuta los proveedores recomendados o crea validación KYC, luego re-analiza.

**Sin Matriz de Riesgo**:

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

**Solución**: Asigna una matriz de riesgo a la entidad usando `PATCH /entities/:id`.

## Próximos Pasos

* [Configurar Reglas de Matriz de Riesgo](/es/api-reference/risk-matrix/list)
* [Configurar Webhooks](/es/use-cases/kyc/webhook-integration)
* [Gestionar Integraciones de Proveedores](/es/api-reference/integrations/provider-codes)
* Monitorear Uso de Créditos en tu [Dashboard → Facturación](https://app.gu1.ai/billing/credits)