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

# Descripción General de Entidades

> Gestiona empresas, individuos y transacciones en la plataforma de análisis de riesgo gu1. Consulta el esquema del request, códigos de respuesta y autenticación.

## ¿Qué son las Entidades?

Las entidades son los objetos principales en gu1 que representan los sujetos de tu análisis de riesgo. Una entidad puede ser una empresa, un individuo, una transacción o cualquier tipo personalizado relevante para tu negocio.

Cada entidad contiene:

* **Información de identidad** (nombre, ID externo, tipo)
* **Evaluación de riesgo** (puntuación de riesgo, estado)
* **Datos personalizados** (JSON flexible para tus campos específicos)
* **Relaciones** (conexiones con otras entidades)
* **Resultados de análisis** (insights generados por IA)
* **Línea de tiempo** (historial de cambios y eventos)

## Tipos de Entidades

<CardGroup cols={2}>
  <Card title="Empresa" icon="building">
    Entidades corporativas para análisis KYB
  </Card>

  <Card title="Persona" icon="user">
    Entidades individuales para análisis KYC
  </Card>

  <Card title="Transacción" icon="money-bill-transfer">
    Transacciones financieras para monitoreo
  </Card>

  <Card title="Personalizado" icon="shapes">
    Cualquier tipo de entidad personalizada para tu negocio
  </Card>
</CardGroup>

## Ciclo de Vida de una Entidad

<Steps>
  <Step title="Creación">
    La entidad se crea vía API con información básica y datos personalizados opcionales
  </Step>

  <Step title="Enriquecimiento">
    Se añaden datos adicionales mediante actualizaciones o integraciones
  </Step>

  <Step title="Análisis">
    El análisis de riesgo impulsado por IA se genera automáticamente
  </Step>

  <Step title="Evaluación de Reglas">
    Se aplican reglas de riesgo para calcular la puntuación de riesgo y generar alertas
  </Step>

  <Step title="Investigación">
    Las alertas activan investigaciones para revisión manual
  </Step>

  <Step title="Resolución">
    El estado de la entidad se actualiza según los resultados de la investigación
  </Step>
</Steps>

## Estados de Entidad

Las entidades pueden tener diferentes estados a lo largo de su ciclo de vida:

| Estado            | Descripción                                         | Caso de Uso           |
| ----------------- | --------------------------------------------------- | --------------------- |
| **active**        | La entidad está activa y siendo monitoreada         | Operación normal      |
| **inactive**      | La entidad ya no está activa                        | Cuentas cerradas      |
| **under\_review** | La entidad está siendo investigada                  | Alerta activada       |
| **approved**      | La entidad pasó todas las verificaciones            | Riesgo bajo           |
| **rejected**      | La entidad falló las verificaciones de cumplimiento | Riesgo alto           |
| **suspended**     | Entidad temporalmente suspendida                    | Información pendiente |

## Puntuación de Riesgo

Cada entidad tiene una puntuación de riesgo (0-100) calculada en base a:

<AccordionGroup>
  <Accordion icon="brain" title="Análisis de IA">
    Los modelos de aprendizaje automático analizan el comportamiento de la entidad, patrones y anomalías
  </Accordion>

  <Accordion icon="sliders" title="Puntuación Basada en Reglas">
    Las reglas personalizadas evalúan condiciones específicas y asignan puntos de riesgo
  </Accordion>

  <Accordion icon="shield-check" title="Verificaciones de Cumplimiento">
    Listas de sanciones, PEPs, resultados de revisión de medios adversos
  </Accordion>

  <Accordion icon="chart-line" title="Comportamiento Histórico">
    Patrones de transacciones, actividad de la cuenta y cambios a lo largo del tiempo
  </Accordion>

  <Accordion icon="link" title="Análisis de Relaciones">
    Entidades conectadas y sus perfiles de riesgo
  </Accordion>
</AccordionGroup>

**Rangos de Puntuación de Riesgo:**

* **0-25**: Riesgo bajo (verde)
* **26-50**: Riesgo medio (amarillo)
* **51-75**: Riesgo alto (naranja)
* **76-100**: Riesgo crítico (rojo)

## Estructura de Datos de Entidad

```json theme={null}
{
  "id": "a7c4c07f-a1f5-49d6-8c17-1577d0787a2e",
  "type": "company",
  "name": "Acme Corporation",
  "externalId": "TAX123456789",
  "country": "US",
  "riskScore": 35,
  "status": "active",
  "entityData": {
    "industry": "Technology",
    "annual_revenue": 5000000,
    "employees": 50,
    "incorporation_date": "2010-01-15",
    "beneficial_owners": [
      {
        "name": "John Doe",
        "ownership": 60,
        "isPEP": false
      }
    ],
    "compliance": {
      "kyb_completed": true,
      "sanctions_checked": true,
      "adverse_media_found": false
    }
  },
  "organizationId": "org_abc123",
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T14:30:00Z"
}
```

## Campos Principales

| Campo        | Tipo   | Requerido | Descripción                                            |
| ------------ | ------ | --------- | ------------------------------------------------------ |
| `type`       | string | Sí        | Tipo de entidad (company, person, transaction, custom) |
| `name`       | string | Sí        | Nombre de la entidad                                   |
| `externalId` | string | No        | Tu identificador único para esta entidad               |
| `country`    | string | No        | Código de país ISO (ej., "US", "UK")                   |
| `entityData` | object | No        | JSON flexible para campos personalizados               |
| `riskScore`  | number | No        | Puntuación de riesgo 0-100 (calculada automáticamente) |
| `status`     | enum   | No        | Estado de la entidad (predeterminado: "active")        |

## Datos Personalizados de Entidad

El campo `entityData` es un objeto JSON flexible donde puedes almacenar cualquier campo personalizado relevante para tu caso de uso:

**Ejemplo KYB:**

```json theme={null}
{
  "entityData": {
    "tax_id": "12-3456789",
    "industry": "Financial Services",
    "annual_revenue": 10000000,
    "employees": 150,
    "incorporation_date": "2015-03-20",
    "website": "https://example.com",
    "beneficial_owners": [...],
    "licenses": [...]
  }
}
```

**Ejemplo KYC:**

```json theme={null}
{
  "entityData": {
    "date_of_birth": "1985-06-15",
    "nationality": "US",
    "occupation": "Software Engineer",
    "annual_income": 120000,
    "identity_verified": true,
    "pep_status": false,
    "documents": [...]
  }
}
```

**Ejemplo de Transacción:**

```json theme={null}
{
  "entityData": {
    "amount": 50000,
    "currency": "USD",
    "sender_account": "ACC123",
    "receiver_account": "ACC456",
    "transaction_type": "wire_transfer",
    "purpose": "Business payment",
    "timestamp": "2025-10-03T10:30:00Z"
  }
}
```

## Operaciones Comunes

<CardGroup cols={2}>
  <Card title="Crear Entidad" icon="plus" href="/api-reference/entities/create">
    POST /entities - Crear nueva entidad
  </Card>

  <Card title="Obtener Entidad" icon="eye" href="/api-reference/entities/get">
    GET /entities/:id - Recuperar detalles de entidad
  </Card>

  <Card title="Listar Entidades" icon="list" href="/api-reference/entities/list">
    GET /entities - Consultar entidades con filtros
  </Card>

  <Card title="Actualizar Entidad" icon="pen" href="/api-reference/entities/update">
    PUT /entities/:id - Actualizar datos de entidad
  </Card>

  <Card title="Eliminar Entidad" icon="trash" href="/api-reference/entities/list">
    DELETE /entities/:id - Eliminar entidad
  </Card>

  <Card title="Importación Masiva" icon="layer-group" href="/en/api-reference/bulk-imports/import-entities">
    POST /entities/bulk - Importar múltiples entidades
  </Card>
</CardGroup>

## Mejores Prácticas

<AccordionGroup>
  <Accordion icon="key" title="Usar IDs Externos">
    Siempre establece `externalId` con tu identificador interno para una fácil reconciliación y actualizaciones
  </Accordion>

  <Accordion icon="tag" title="Tipos de Entidad Consistentes">
    Usa valores de tipo de entidad consistentes en toda tu organización (ej., "company" vs "corporate")
  </Accordion>

  <Accordion icon="globe" title="Establecer Códigos de País">
    Siempre incluye códigos de país ISO para una evaluación de riesgo y verificaciones de cumplimiento adecuadas
  </Accordion>

  <Accordion icon="database" title="Estructurar Datos de Entidad">
    Organiza `entityData` con nombres de campos consistentes y objetos anidados para datos complejos
  </Accordion>

  <Accordion icon="clock-rotate-left" title="Rastrear Actualizaciones">
    Usa la marca de tiempo `updatedAt` para detectar cambios y sincronizar con tus sistemas
  </Accordion>

  <Accordion icon="gauge" title="Operaciones Masivas">
    Usa importación masiva para crear múltiples entidades (>10) para mejorar el rendimiento
  </Accordion>
</AccordionGroup>

## Funcionalidades Avanzadas

### Análisis Impulsado por IA

Cada entidad puede tener análisis de riesgo generado por IA:

```bash theme={null}
POST /ai-analysis/entity/:entityId
```

Devuelve un análisis exhaustivo que incluye:

* Resumen ejecutivo
* Patrones de comportamiento
* Factores de riesgo identificados
* Recomendaciones
* Puntuación de confianza

[Más información →](/api-reference/data-ingestion/overview)

### Relaciones de Entidades

Conecta entidades para mostrar propiedad, transacciones u otras relaciones:

```json theme={null}
{
  "sourceEntityId": "entity_1",
  "targetEntityId": "entity_2",
  "relationshipType": "owns",
  "strength": 0.85
}
```

### Archivos Adjuntos de Documentos

Adjunta documentos (tarjetas de identidad, licencias, contratos) a entidades:

```bash theme={null}
POST /documents/entity/:entityId/upload
```

[Más información →](/es/api-reference/documents/upload)

## Flujos de Trabajo de Ejemplo

<CardGroup cols={2}>
  <Card title="Incorporación KYB" icon="building" href="/use-cases/kyb/workflow">
    Flujo de trabajo completo de incorporación de empresas
  </Card>

  <Card title="Verificación KYC" icon="id-card" href="/es/use-cases/kyc/flujo-completo">
    Proceso de verificación de clientes individuales
  </Card>

  <Card title="Monitoreo de Transacciones" icon="money-bill-transfer" href="/es/use-cases/transaction-monitoring/fraud-detection">
    Revisión de transacciones en tiempo real
  </Card>

  <Card title="Monitoreo Continuo" icon="chart-line" href="/quickstart">
    Configuración de monitoreo continuo de entidades
  </Card>
</CardGroup>

## Próximos Pasos

<Steps>
  <Step title="Crea Tu Primera Entidad">
    Sigue la [guía Crear Entidad](/api-reference/entities/create) para añadir una entidad
  </Step>

  <Step title="Configurar Mapeo de Datos">
    Usa [Esquemas Personalizados](/api-reference/data-ingestion/custom-schemas) para importaciones estructuradas
  </Step>

  <Step title="Configurar Reglas">
    Aplica reglas de riesgo a través del panel de control para calcular puntuaciones de riesgo
  </Step>

  <Step title="Monitorear y Actuar">
    Configura webhooks para recibir alertas cuando cambien las puntuaciones de riesgo
  </Step>
</Steps>