Descripción General de Entidades

¿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

Creación

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

Enriquecimiento

Se añaden datos adicionales mediante actualizaciones o integraciones

Análisis

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

Evaluación de Reglas

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

Investigación

Las alertas activan investigaciones para revisión manual

Resolución

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

Estados de Entidad

Las entidades persona y empresa usan el enum Postgres entity_status. No hay un grafo de transiciones obligatorio: después de crear, una etiqueta de matriz de riesgo, una acción de regla (updateEntityStatus), una automatización o un PATCH manual pueden llevar la entidad a cualquier estado permitido (salvo que changeStatusManual esté bloqueado).

Default al crear

Si omitís status en la creación (manual o automática), Gu1 asigna under_review.
Podés enviar otro valor explícitamente, por ejemplo status: "not_started". Ese valor reemplaza el default, salvo que después una matriz/regla/automatización lo cambie otra vez.

Valores canónicos

Estado	Significado	Uso típico
`not_started`	Creada, revisión/análisis aún no iniciado	Equivalente opt-in al `NOT_STARTED` de V2. Enviarlo en create si no querés el default `under_review`.
`under_review`	En revisión / análisis en curso	Default al crear. También cuando reglas o etiquetas piden seguimiento manual.
`pending_verification`	Esperando completar KYC/KYB	Verificación de identidad o empresa aún pendiente (docs/biometría). Distinto de `under_review` (análisis de compliance activo).
`awaiting_information`	Esperando datos del cliente	Se pidió información al cliente (típicamente documentos de onboarding por correo) y todavía no terminó de cargarlos. Distinto de `pending_verification` (KYC/KYB de identidad). El agente de onboarding lo setea al enviar el pedido y restaura el estado anterior al cargar.
`active`	Verificada y operativa (“aprobada”)	Cliente puede operar tras onboarding/revisión exitosa.
`inactive`	Cerrada o inactiva	Fin de relación o larga inactividad; solo consultas históricas.
`suspended`	Suspensión temporal	Operaciones bloqueadas hasta resolver; reversible.
`blocked`	Bloqueo permanente de alto riesgo	Riesgo confirmado / sanciones / orden judicial; operaciones bloqueadas.
`rejected`	Onboarding denegado	Falló KYC/KYB o política; sin operaciones. Preferí `blocked` si ya hubo actividad.
`expired`	Datos/documentos vencidos	Hay que refrescar documentación.
`deleted`	Baja lógica	Auditoría/archivo; no es un paso normal de onboarding.

No existe el estado approved. En producto, “aprobado” es active. pending_verification es un estado de ciclo de vida soportado (esperando completar KYC/KYB); awaiting_information es espera de datos pedidos al cliente (por ejemplo documentos de onboarding por correo), no captura de identidad. Ambos son distintos de not_started (análisis no iniciado) y de under_review (revisión de compliance en curso). Etiquetas legacy V2: NOT_STARTED → not_started, IN_PROGRESS → under_review, APPROVED → active, DENIED → rejected.

Flujos de ejemplo (incluida la matriz de riesgo)

No hay un estado intermedio obligatorio entre la creación y la aprobación/denegación. Depende de tus etiquetas de matriz y reglas:

Crear con not_started → la matriz/reglas no cambian el status → sigue en not_started hasta que algo lo actualice.
Crear con not_started → banda de score o regla pone under_review → hace falta análisis manual antes de active / rejected / etc.
Crear con not_started → matriz/regla pone active directo → aprobado sin pasar por under_review.
Crear con not_started → matriz/regla pone rejected o blocked directo → denegado/bloqueado sin estado intermedio de revisión.
Crear con default under_review → luego matriz/manual a active o rejected.

Configurá el binding score→status en las etiquetas de la matriz y/o acciones updateEntityStatus para alinear con vuestro flujo V2.

Guard de operaciones

Solo blocked, suspended y rejected bloquean operaciones de entidad por defecto. not_started, under_review, pending_verification y awaiting_information no bloquean del mismo modo.

Puntuación de Riesgo

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

Análisis de IA

Los modelos de aprendizaje automático analizan el comportamiento de la entidad, patrones y anomalías

Puntuación Basada en Reglas

Las reglas personalizadas evalúan condiciones específicas y asignan puntos de riesgo

Verificaciones de Cumplimiento

Listas de sanciones, PEPs, resultados de revisión de medios adversos

Comportamiento Histórico

Patrones de transacciones, actividad de la cuenta y cambios a lo largo del tiempo

Análisis de Relaciones

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

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: `"under_review"`)

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

Usar IDs Externos

Siempre establece externalId con tu identificador interno para una fácil reconciliación y actualizaciones

Tipos de Entidad Consistentes

Usa valores de tipo de entidad consistentes en toda tu organización (ej., “company” vs “corporate”)

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

Estructurar Datos de Entidad

Organiza entityData con nombres de campos consistentes y objetos anidados para datos complejos

Rastrear Actualizaciones

Usa la marca de tiempo updatedAt para detectar cambios y sincronizar con tus sistemas

Operaciones Masivas

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

Crea Tu Primera Entidad

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

Configurar Mapeo de Datos

Usa Esquemas Personalizados para importaciones estructuradas

Configurar Reglas

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

Monitorear y Actuar

Configura webhooks para recibir alertas cuando cambien las puntuaciones de riesgo

​¿Qué son las Entidades?

​Tipos de Entidades

Empresa

Persona

Transacción

Personalizado

​Ciclo de Vida de una Entidad

​Estados de Entidad

​Default al crear

​Valores canónicos

​Flujos de ejemplo (incluida la matriz de riesgo)

​Guard de operaciones

​Puntuación de Riesgo

​Estructura de Datos de Entidad

​Campos Principales

​Datos Personalizados de Entidad

​Operaciones Comunes