Skip to main content

Integración de aplicaciones

Cómo integrar una aplicación con la plataforma​

Esta sección describe, de principio a fin, los pasos que debe seguir un equipo para integrar su aplicación con la plataforma regional de cumplimiento y auditoría.

La integración abarca tres grandes frentes:

  1. Definición funcional con el equipo de Seguridad.
  2. Alta y configuración del aplicativo en la plataforma.
  3. Integración técnica (SDK de auditoría, AGP y exposición de usuarios/roles).

1. Definir el alcance de auditoría con el equipo de Seguridad​

Antes de escribir una sola línea de código, es obligatorio alinear con el equipo de Seguridad:

  • Tipos de usuarios relevantes

    • ¿Qué perfiles deben ser auditados?
    • ¿Qué usuarios son realmente críticos (ej. administradores, gerentes, operaciones, etc.)?

  • Roles y permisos a considerar

    • Qué roles deben aparecer en los reportes de la plataforma.
    • Qué operaciones se consideran críticas (creación/eliminación de usuarios, cambios de permisos, operaciones financieras, etc.).

  • Eventos mínimos a registrar

    • Inicio/cierre de sesión.
    • Creación, modificación y desactivación de usuarios.
    • Asignación o revocación de roles/permisos.
    • Cualquier acción que Seguridad exija por normativa o políticas internas.

✅ Resultado esperado: documento o acuerdo claro con Seguridad donde se definen:

  • tipos de usuarios,
  • roles relevantes,
  • acciones/eventos que deben registrarse en la Plataforma.

2. Solicitar el alta del aplicativo en la plataforma​

Con el alcance definido, el siguiente paso es solicitar al equipo de la plataforma regional de compliance el alta del nuevo aplicativo.

La solicitud debería incluir como mínimo:

  • Nombre del aplicativo (ej. portal-ventas-x, backoffice-y).
  • Descripción funcional corta.
  • País(es) y unidades de negocio en los que aplica.
  • Ambientes a integrar (desarrollo, QA, staging, producción).
  • Punto(s) de contacto técnicos (nombre, email, equipo).
  • Resumen del alcance de auditoría acordado con Seguridad.

✅ Resultado esperado:
El equipo de plataforma crea el aplicativo, configura los artefactos necesarios (clientId, API key, tópicos, scopes, etc.) y devuelve al equipo del proyecto la confirmación de todos los cambios realizados.

3. Consumir la librería de auditoría de la Plataforma de Compliance​

Una vez creado el aplicativo en la plataforma, el siguiente paso es integrar la librería/SDK de auditoría.

📦 https://github.com/Cencosud-xlabs/omni-plugins/tree/main/packages/abm-logging-publisher

3.1. Instalar la librería​

Dependiendo de la tecnología, se agrega la dependencia al proyecto. Por ejemplo, en Node.js:

npm install npm install @Cencosud-xlabs/abm-logging-publisher @nestjs/common @team_seki/kafka-streamer-plugin zod

# o

yarn add @Cencosud-xlabs/abm-logging-publisher @nestjs/common @team_seki/kafka-streamer-plugin zod

3.2. Buenas prácticas​

  • No registrar datos sensibles (contraseñas, tokens, PII no autorizada).
  • Siempre enviar identificadores claros de usuario, rol, país y sistema.
  • Manejar correctamente errores/transientes al publicar eventos (reintentos, logs internos, etc.).

4. Integrar AGP (roles/permisos) en la aplicación​

Para que la Plataforma pueda ofrecer visibilidad sobre roles, permisos y asignaciones, la aplicación debe:

  1. Modelar roles y permisos de acuerdo a las pautas de Seguridad.
  2. Exponer funcionalidades para:
    • Asignar o revocar roles/permisos a usuarios.
    • Listar el catálogo de roles disponibles.
  3. Conectarse con AGP (o el módulo de gobierno de accesos que defina la organización), de modo que:
    • Las acciones de alta/baja/modificación de permisos queden trazadas.
    • La plataforma pueda correlacionar eventos de auditoría con el modelo de permisos real.

✅ Resultado esperado:
El aplicativo permite gestionar y consultar roles/permisos de forma standard, y esas acciones pueden ser auditadas por la plataforma.

5. Exponer endpoints de usuarios y roles para la Plataforma consuma​

La plataforma necesita consumir información de usuarios y roles para enriquecer los reportes. Para ello, la aplicación debe exponer endpoints (normalmente REST) con un formato acordado.

Ejemplo de endpoints (a modo de referencia):

  • POST /api/compliance/users
  • POST /api/compliance/roles

5.1. Ejemplo de respuesta de usuarios​

[
	{
		"id": "roberto.carrero@example.cl",
		"windowsAccount": "rfcalenz",
		"email": "roberto.carrero@example.cl",
		"name": "Roberto Carrero Quintana",
		"status": "Activo",
		"roles": [
			{
				"id": "6e13f4e7-fce3-4f3d-ae23-a1406b9c551f",
				"code": "6e13f4e7-fce3-4f3d-ae23-a1406b9c551f",
				"name": "Jefe de Ventas"
			}
		],
		"store": [
			{
				"id": "E871",
				"code": "E871",
				"name": "EASY SANTA AMALIA"
			}
		],
		"createdAt": "2025-12-27T00:20:30.689Z",
		"updatedAt": "2025-12-29T20:47:12.578Z"
	}
]

5.2. Ejemplo de respuesta de roles​

[
	{
		"id": "4b023352-5ef0-4f99-99a2-9ceb1cb9dfd2",
		"code": "4b023352-5ef0-4f99-99a2-9ceb1cb9dfd2",
		"name": "Operaciones",
		"flag": [
			{
				"id": "cl_sm",
				"code": "cl_sm",
				"name": "Supermercados"
			}
		],
		"status": "Activo",
		"comment": null,
		"scopes": [
			{
				"id": "checklist-item.write",
				"code": "checklist-item.write",
				"name": "checklist-item.write",
				"description": "Se usa para acceder a tareas de items de checklist individuales. Permite ver y contar tareas pendientes de items (tipo CHECKLIST-ITEM) generadas cuando un item recibe respuesta \"NO\", mostrando contadores agregados de tareas no resueltas.",
				"groupCode": "checklist",
				"groupName": "checklist"
			}
		],
		"createdAt": "2025-12-10T20:21:26.077Z",
		"updatedAt": "2025-12-10T20:21:26.077Z"
	}
]

⚠️ Importante:
El formato exacto se definirá junto al equipo de plataforma. Lo clave es:

  • tener identificadores estables
  • exponer sólo la información necesaria para auditoría.

6. Instrumentar los puntos de auditoría en el código​

Con el SDK instalado y configurado, se deben registrar eventos en los puntos críticos definidos junto a Seguridad.

Ejemplos típicos:

  • Login / logout.
  • Creación, modificación o bloqueo de usuarios.
  • Asignación o revocación de roles/permisos.
  • Acciones de alto impacto (aprobaciones, rechazos, cambios de configuración sensibles).

Ejemplo (pseudo-código):

await this.abmPublisher.registerUserEvents(
	{
		application: 'my-app',
		entityType: EntityType.USER,
		actionType: UserActionType.UserRegistration,
		data: {
			name: 'John',
			lastName: 'Doe',
			accountId: 'user123',
			email: 'john@example.com',
			executingUser: { email: 'admin@example.com', accountId: 'admin1' },
			role: [],
			store: [],
			flag: [],
		},
	},
	{}
);

7. Pruebas, validación y verificación de Seguridad​

Una vez integrada la auditoría, se deben realizar pruebas en conjunto:

1. Pruebas locales / entorno de desarrollo

  • Generar eventos básicos (login, cambios de rol, etc.).
  • Verificar que los eventos lleguen correctamente a la plataforma (Kafka / API).
  • Confirmar que los endpoints de usuarios/roles responden según lo esperado.

2. Pruebas en entorno integrado (staging / QA)

  • Ejecutar flujos completos de negocio.
  • Validar que la plataforma visualiza correctamente:
    • usuarios
    • roles
    • eventos generados por el aplicativo.

3. Verificación con el equipo de Seguridad

  • Seguridad revisa que:
    • se están registrando todos los eventos requeridos.
    • no se exponen datos sensibles.
    • el modelo de roles/permisos está alineado a las políticas definidas.

✅ Resultado esperado: El aplicativo queda formalmente validado por Seguridad y la plataforma regional, y puede pasar a producción respetando los lineamientos de auditoría y compliance.

8. Checklist de integración​

Antes de dar por finalizada la integración, asegúrate de cumplir con este checklist:

  • Alcance de auditoría alineado con el equipo de Seguridad.
  • Aplicativo creado en la plataforma (clientId, API keys, tópicos/configuración).
  • SDK/librería de auditoría instalado y configurado.
  • Puntos críticos del código instrumentados con eventos de auditoría.
  • Endpoints de usuarios y roles expuestos con el formato requerido.
  • Integración con AGP (roles/permisos) funcional.
  • Pruebas realizadas en desarrollo y en staging.
  • Validación final realizada y aprobada por Seguridad y por el equipo de plataforma.