Skip to main content

​
¿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

Empresa

Entidades corporativas para análisis KYB

Persona

Entidades individuales para análisis KYC

Transacción

Transacciones financieras para monitoreo

Personalizado

Cualquier tipo de entidad personalizada para tu negocio

​
Ciclo de Vida de una Entidad

1

Creación

La entidad se crea vía API con información básica y datos personalizados opcionales
2

Enriquecimiento

Se añaden datos adicionales mediante actualizaciones o integraciones
3

Análisis

El análisis de riesgo impulsado por IA se genera automáticamente
4

Evaluación de Reglas

Se aplican reglas de riesgo para calcular la puntuación de riesgo y generar alertas
5

Investigación

Las alertas activan investigaciones para revisión manual
6

Resolución

El estado de la entidad se actualiza según los resultados de la investigación

​
Estados de Entidad

Las entidades pueden tener diferentes estados a lo largo de su ciclo de vida:
EstadoDescripciónCaso de Uso
activeLa entidad está activa y siendo monitoreadaOperación normal
inactiveLa entidad ya no está activaCuentas cerradas
under_reviewLa entidad está siendo investigadaAlerta activada
approvedLa entidad pasó todas las verificacionesRiesgo bajo
rejectedLa entidad falló las verificaciones de cumplimientoRiesgo alto
suspendedEntidad temporalmente suspendidaInformación pendiente

​
Puntuación de Riesgo

Cada entidad tiene una puntuación de riesgo (0-100) calculada en base a:
Los modelos de aprendizaje automático analizan el comportamiento de la entidad, patrones y anomalías
Las reglas personalizadas evalúan condiciones específicas y asignan puntos de riesgo
Listas de sanciones, PEPs, resultados de revisión de medios adversos
Patrones de transacciones, actividad de la cuenta y cambios a lo largo del tiempo
Entidades conectadas y sus perfiles de riesgo
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

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

CampoTipoRequeridoDescripción
typestringSíTipo de entidad (company, person, transaction, custom)
namestringSíNombre de la entidad
externalIdstringNoTu identificador único para esta entidad
countrystringNoCódigo de país ISO (ej., “US”, “UK”)
entityDataobjectNoJSON flexible para campos personalizados
riskScorenumberNoPuntuación de riesgo 0-100 (calculada automáticamente)
statusenumNoEstado 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: 
{
  "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: 
{
  "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: 
{
  "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

Crear Entidad

POST /entities - Crear nueva entidad

Obtener Entidad

GET /entities/:id - Recuperar detalles de entidad

Listar Entidades

GET /entities - Consultar entidades con filtros

Actualizar Entidad

PUT /entities/:id - Actualizar datos de entidad

Eliminar Entidad

DELETE /entities/:id - Eliminar entidad

Importación Masiva

POST /entities/bulk - Importar múltiples entidades

​
Mejores Prácticas

Siempre establece externalId con tu identificador interno para una fácil reconciliación y actualizaciones
Usa valores de tipo de entidad consistentes en toda tu organización (ej., “company” vs “corporate”)
Siempre incluye códigos de país ISO para una evaluación de riesgo y verificaciones de cumplimiento adecuadas
Organiza entityData con nombres de campos consistentes y objetos anidados para datos complejos
Usa la marca de tiempo updatedAt para detectar cambios y sincronizar con tus sistemas
Usa importación masiva para crear múltiples entidades (>10) para mejorar el rendimiento

​
Funcionalidades Avanzadas

​
Análisis Impulsado por IA

Cada entidad puede tener análisis de riesgo generado por IA: 
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 →

​
Relaciones de Entidades

Conecta entidades para mostrar propiedad, transacciones u otras relaciones: 
{
  "sourceEntityId": "entity_1",
  "targetEntityId": "entity_2",
  "relationshipType": "owns",
  "strength": 0.85
}

​
Archivos Adjuntos de Documentos

Adjunta documentos (tarjetas de identidad, licencias, contratos) a entidades: 
POST /documents/entity/:entityId/upload
Más información →

​
Flujos de Trabajo de Ejemplo

Incorporación KYB

Flujo de trabajo completo de incorporación de empresas

Verificación KYC

Proceso de verificación de clientes individuales

Monitoreo de Transacciones

Revisión de transacciones en tiempo real

Monitoreo Continuo

Configuración de monitoreo continuo de entidades

​
Próximos Pasos

1

Crea Tu Primera Entidad

Sigue la guía Crear Entidad para añadir una entidad
2

Configurar Mapeo de Datos

Usa Esquemas Personalizados para importaciones estructuradas
3

Configurar Reglas

Aplica reglas de riesgo a través del panel de control para calcular puntuaciones de riesgo
4

Monitorear y Actuar

Configura webhooks para recibir alertas cuando cambien las puntuaciones de riesgo