Banners

Requisitos previos de acceso

• Permiso (módulo): viewBanners O manageBanners (basta con uno de los módulos para ver la pantalla). Las acciones de crear, editar y eliminar requieren específicamente manageBanners (botones protegidos por *appHasPermission="'manageBanners'").
• Licencia/Feature: Ninguna.
• Contenedor del menú: GENERAL → grupo Comunicación (ícono campaign) → Banners.

Qué es / cuándo usar

Pantalla para administrar los banners de la pantalla de inicio (/home) del Midas-Web: campañas promocionales, mensajes contextuales y tarjetas de onboarding. El cliente configura todo (texto, imagen, vigencia, orden, CTA) sin depender de un deploy. Los banners se persisten en el CustomerProfileService (CPM) y se sirven a la app ya filtrados por vigencia y ordenados. Úselo para ejecutar campañas, mostrar avisos y guiar a nuevos usuarios de forma autónoma.

Requisitos previos

• Permiso: viewBanners o manageBanners registrado para el rol. El permiso en Axia es doble — enum CPM en el backend (manageBanners/viewBanners) y módulo dinámico en la BD; ambos deben existir para que la acción aparezca y funcione. Las mutaciones (crear/editar/eliminar/activar) requieren manageBanners.
• Licencia/Feature: ninguna.
• Dependencias de otras pantallas: la carga de imágenes usa la API de archivos (POST /api/v1/files, almacenamiento de imágenes). No es necesario que exista ninguna otra pantalla previamente.

Paso a paso

1. Acceda al menú Comunicación → Banners.
2. La tabla lista los banners ordenados por orden de visualización (display_order). Use el filtro Tipo para restringir a PROMOTIONAL, CONTEXTUAL, ONBOARDING o Todos.
3. Haga clic en Agregar (requiere manageBanners) para abrir el formulario.
4. Elija el Tipo — el formulario muestra/oculta campos según el tipo.
5. Complete textos, imágenes (para promocional), CTA, vigencia y flags.
6. Haga clic en Guardar.
7. En la tabla, use el toggle de estado para activar/desactivar, el ícono de gráfico para ver métricas de clics, el lápiz para editar y el basurero para eliminar.

Campos

Listado

Columna	Qué muestra	Origen del dato
Nombre (name)	Nombre interno del banner	banner.name
Tipo (type)	PROMOTIONAL / CONTEXTUAL / ONBOARDING (chip de color)	banner.type
Título (title)	Título mostrado (o —)	banner.title
Período (period)	Vigencia inicio → fin (dd/MM/yy)	start_date / end_date
Orden (order)	Posición de visualización	display_order
Estado (status)	Toggle activo/inactivo	is_active
Acciones	Métricas / Editar / Eliminar	—

Formulario (modal)

Campo	Qué es	¿Obligatorio?	Efecto en el sistema/backend
Nombre (name)	Identificación interna del banner	Sí	Validado al enviar; utilizado para identificar/eliminar.
Tipo (type)	PROMOTIONAL, CONTEXTUAL o ONBOARDING	Sí	Define el componente que se renderiza en la app: carrusel imagen+CTA (promocional), alerta con ícono (contextual), tarjeta descartable (onboarding). Controla qué campos aparecen en el formulario.
Orden de visualización (display_order)	Posición relativa en la home	No (default 0)	Los banners se ordenan por display_order ascendente, en la tabla y en la app.
Título (title)	Texto principal	No	Mostrado en el banner.
Ícono (icon_name)	Nombre del ícono Material (ej.: warning, info, verified)	No	Solo aparece para CONTEXTUAL/ONBOARDING; define el ícono de la alerta/tarjeta.
Subtítulo (subtitle)	Texto secundario	No	Mostrado debajo del título.
Imagen principal (image_url)	Imagen del banner	No	Solo aparece para PROMOTIONAL. Carga (≤ 5 MB) vía API de archivos; guarda la URL retornada, no el binario.
Imagen responsiva (image_url_responsive)	Versión mobile de la imagen	No	Solo PROMOTIONAL; mismo flujo de carga, usada en pantallas más pequeñas.
Etiqueta del CTA (cta_label)	Texto del botón de acción	No	Define el botón; sin etiqueta, no hay CTA visible.
Ruta interna (cta_internal_route)	Destino interno (ej.: /wallet, /exchange)	No	Navegación interna en la app al hacer clic en el CTA.
URL externa (cta_external_url)	Enlace externo (https://...)	No	Alternativa a la ruta interna; abre URL externa.
Abrir en nueva pestaña (cta_new_tab)	Flag del CTA externo	No	Si está marcado, el enlace externo se abre en nueva pestaña.
Fecha inicio (start_date)	Inicio de la vigencia	No	Define cuándo el banner comienza a mostrarse. Validado: el inicio no puede ser mayor que el fin.
Fecha fin (end_date)	Fin de la vigencia	No	Define cuándo el banner deja de mostrarse.
Activo (is_active)	Activa/desactiva el banner	No (default activado)	Un banner inactivo no se sirve a la app independientemente de la vigencia.
Descartable (is_dismissable)	Permite al usuario cerrar el banner	No	Típicamente para ONBOARDING; el descarte se recuerda en el localStorage del usuario.
Tenant (tenant_id)	Restringe el banner a un tenant	No	Opcional; utilizado en entornos multi-tenant para segmentar la visualización.
Color de fondo (background_color)	Color de fondo (ej.: #1f2937)	No	Personalización visual del banner.
Color del texto (text_color)	Color del texto (ej.: #ffffff)	No	Personalización visual.
Grupo legado (legacy_group)	Compatibilidad con el sistema antiguo (bankingBanners, eniatoBanners, midasWebBanners, crowdfundingBanners, digitalBankingBanners, exchangeBanners, …)	No	Hace que la capa de compatibilidad también sirva este banner a los getters del sistema antiguo para esa pantalla objetivo. Deje vacío para banners exclusivos de la nueva home.

Acciones y modales

• Agregar / Editar: abre el BannerFormDialog. Al guardar, valida (nombre y tipo obligatorios; inicio ≤ fin) y llama a create o update. En caso de error, muestra el mensaje del backend.
• Toggle de estado: alterna is_active directamente en la tabla (update con el payload invertido).
• Eliminar: solicita confirmación (¿Eliminar el banner "<nombre>"?) y elimina vía delete.
• Métricas: abre un resumen con total de clics y fecha del último clic (metrics). El tracking registra solo clics (sin impresiones).
• Carga de imagen: selección de archivo en el cliente; rechaza archivos mayores a 5 MB; al concluir, guarda la URL en el campo correspondiente.
• Step-up / MFA: no hay re-autenticación por defecto en esta pantalla.

Reglas de negocio / consideraciones

Atención

• Imagen (PROMOTIONAL): límite de 5 MB por archivo; el banner guarda solo la URL (S3/MinIO), no el binario. Proporcione la imagen principal y la responsiva para una buena visualización en mobile.
• Vigencia: start_date no puede ser mayor que end_date (bloqueado en la validación). Un banner inactivo (is_active = false) no aparece aunque esté dentro de la vigencia.
• El ícono solo tiene sentido en CONTEXTUAL/ONBOARDING; en PROMOTIONAL el campo ni siquiera aparece. En cambio, las imágenes solo aparecen en PROMOTIONAL.
• CTA: si completa la ruta interna y la URL externa, priorice un destino claro; "abrir en nueva pestaña" solo aplica al enlace externo.
• Grupo legado cambia el alcance: completarlo hace que el banner también sea entregado por los getters del sistema antiguo de esa pantalla objetivo. Use con intención.
• Métricas: solo se rastrean clics; no hay conteo de impresiones.

• La eliminación es definitiva: remover el banner borra el registro; prefiera desactivar (toggle) si solo desea quitarlo de la visualización manteniendo el historial.

Ejemplos

Escenario 1 — Campaña promocional con carrusel y CTA interno

1. Agregar → Tipo PROMOTIONAL.
2. Nombre: campanha-cartao-junho; Orden: 1.
3. Cargue la imagen principal (≤ 5 MB) y la imagen responsiva.
4. CTA: etiqueta Quiero mi tarjeta, ruta interna /wallet.
5. Vigencia: inicio hoy, fin el último día del mes; Activo marcado.
6. Guardar. El banner aparece en la parte superior del carrusel de la home (orden 1) mientras esté dentro de la vigencia. Los clics en el CTA se contabilizan en Métricas.

Escenario 2 — Aviso contextual (alerta con ícono)

1. Agregar → Tipo CONTEXTUAL.
2. Nombre: aviso-manutencao; Ícono: warning.
3. Título: Mantenimiento programado; Subtítulo: El sábado, de 2h a 5h, algunos servicios no estarán disponibles.
4. Colores opcionales: fondo #1f2937, texto #ffffff.
5. Vigencia corta (solo los días del aviso); Activo.
6. Guardar. La app muestra una alerta con el ícono warning; el administrador escribe el texto (no hay condición automática — es visualización manual durante la vigencia).

Escenario 3 — Tarjeta de onboarding descartable

1. Agregar → Tipo ONBOARDING.
2. Nombre: onboarding-kyc; Ícono: verified.
3. Título: Completa tu verificación; CTA ruta interna /account/kyc.
4. Marque Descartable para que el usuario pueda cerrar la tarjeta (el descarte queda en su localStorage).
5. Guardar. Los nuevos usuarios ven la tarjeta hasta que completen la acción o la descarten.

Escenario 4 — Reutilizar en el sistema legado (grupo legado)

Para que un banner también aparezca donde la app aún lee del sistema antiguo (ej.: pantalla de banking), defina el Grupo legado como bankingBanners (o crowdfundingBanners, exchangeBanners, etc.). La capa de compatibilidad pasa a servir este banner también vía getter legado de ese grupo, en el formato antiguo { name, url, link }. Deje vacío cuando el banner sea exclusivo de la nueva home.

Pantallas relacionadas

• Envío de e-mail
• Acción en masa (visión general)