Arquitectura y Conceptos de la API

Esta sección describe los conceptos fundamentales de la arquitectura de Kuenta y cómo se reflejan en su API. Comprender estos principios es clave para una integración exitosa.

Conceptos Fundamentales

El diseño de Kuenta se centra en un conjunto de conceptos clave que permiten modelar interacciones complejas del mundo real de manera flexible.

Entidades: El Corazón del Sistema

El núcleo de Kuenta es la Entidad. Una entidad representa a cualquier actor dentro del ecosistema.

• Tipos de Entidades: La plataforma distingue entre:

  • Personas Naturales: Individuos.
  • Personas Jurídicas: Empresas u organizaciones.

• Dualidad de Roles: Una característica clave de Kuenta es que cualquier entidad, ya sea natural o jurídica, puede actuar simultáneamente como:

  • Proveedor: Ofrece productos, servicios o crédito.
  • Cliente: Solicita productos, servicios o crédito. Esta flexibilidad se extiende a otros procesos como la firma de documentos o la solicitud de validaciones.

• Organizaciones: Cualquier entidad puede convertirse en una "organización" al ser gestionada por múltiples usuarios. Esto permite el trabajo colaborativo dentro de una misma empresa o incluso para una persona natural que delegue tareas.

Usuarios y Acceso: ¿Quién Hace Qué?

Los Usuarios son quienes realizan acciones en la plataforma en nombre de las entidades.

• Roles y Permisos: El acceso se gestiona a través de roles. A cada usuario dentro de una organización se le asigna un rol (ej. "Administrador", "Analista") que define con precisión qué acciones puede realizar.

• Contexto Dinámico: Un mismo usuario puede pertenecer a múltiples organizaciones (entidades) y tener un rol diferente en cada una. La plataforma permite al usuario cambiar de "contexto" fácilmente. Al seleccionar un rol (por ejemplo, "administrador de la Empresa X"), la interfaz se adapta dinámicamente, mostrando solo las opciones y datos permitidos para ese rol.

  Nota de API: El token de autenticación (JWT) del usuario define el contexto actual de la entidad y los permisos. Endpoints como GET /profile/permissions permiten a la aplicación cliente consultar y adaptar la interfaz según los privilegios del rol activo.

• Administración de Entidades:

  • Una "persona natural" es administrada por defecto por el usuario que la creó.
  • Si un usuario crea una "entidad jurídica", se convierte automáticamente en su administrador, manteniendo su acceso a su entidad personal.

  Nota de API: Esto se refleja en los endpoints GET /profile y PUT /profile, que operan sobre el perfil del usuario autenticado sin necesidad de un ID de entidad en la URL.

Perfiles de Datos: Privacidad y Colaboración

Kuenta gestiona la información de las entidades a través de un sistema de perfiles que garantiza la privacidad y el control.

• Perfil Personal (Maestro):

  • Es la fuente de verdad única para la información de una entidad.
  • Solo es accesible y modificable por la propia entidad. Ningún tercero puede verlo directamente.

• Perfiles Compartidos:

  • Para colaborar, una entidad comparte una "vista" de sus datos con otra a través de un perfil compartido.
  • Este perfil es una copia segura y controlada de ciertos datos del perfil maestro.
  • Se pueden crear múltiples perfiles compartidos, cada uno personalizado para una relación específica. Por ejemplo, la información compartida con un banco puede ser diferente a la compartida con un proveedor.

  Nota de API: Los perfiles compartidos se gestionan a través de los recursos de "Terceros" (en la API, a menudo llamados debtors, creditors, etc.). Por ejemplo, GET /debtor/{debtorid}/profile permite a una entidad acceder al perfil compartido de uno de sus deudores.

Seguridad y Trazabilidad

La seguridad y la auditoría son pilares fundamentales en la arquitectura de Kuenta.

Control de Acceso Avanzado

• Asistencia Remota Segura (TOTP): La plataforma permite que un tercero (como un asesor) asista a un cliente de forma temporal y segura. El flujo utiliza un código de un solo uso (TOTP) que el cliente comparte explícitamente, otorgando al asesor permisos limitados por un tiempo definido para actuar en su nombre.

Ciclo de Vida y Auditoría de Datos

Kuenta está diseñado bajo el principio de "nunca perder información".

• Versionado de Perfiles: Cada cambio en un perfil de entidad, por mínimo que sea, crea una nueva versión inmutable. La versión anterior se archiva. Esto garantiza una trazabilidad completa y la capacidad de auditar la historia de los datos de cualquier entidad.

• Gestión de Relaciones: Cuando una relación comercial termina, la relación y el perfil compartido asociado se eliminan. Sin embargo, las entidades y sus perfiles maestros permanecen intactos, preservando su historial de datos independiente.

• Pista de Auditoría (Logs): Toda interacción relevante en la plataforma genera un registro de auditoría. Este log detalla qué usuario realizó la acción, sobre qué entidad, y cuándo, proporcionando una trazabilidad completa para fines de seguridad y cumplimiento.

Personalización y Flexibilidad

• Marca Blanca: Kuenta es una plataforma multi-tenant. Cada organización puede configurar una "marca blanca", personalizando la apariencia y el comportamiento de la aplicación para sus usuarios y clientes, manteniendo una experiencia de marca consistente.

  Nota de API: La personalización se gestiona a través de endpoints de configuración a nivel de organización, como GET /organization/config y POST /organization/{entityid}/config/{configid}/profile-field, que permiten definir campos de perfil personalizados para cada "marca blanca".