Documentación del Sistema

Appearance

Configuracion de Gateway de Pagos del Portal ​

Modulo: Config / Admin Tipo: View Estado: Planificado Fecha: 2026-04-22

Descripcion ​

Vista en el modulo Config/Admin del ERP Bautista donde el operador configura, por sucursal, el gateway de pagos que utilizara el Portal de Clientes. Cada sucursal puede tener un gateway diferente o ninguno (deshabilita pagos online para esa sucursal).

Esta configuracion es el prerequisito tecnico para que el Portal de Clientes pueda procesar pagos online. Sin ella, POST /portal/pagos/iniciar retorna 422 GATEWAY_NOT_CONFIGURED.

Frontend ​

Vistas ​

  • Vista de configuracion de gateway: Formulario de configuracion por sucursal en el modulo Config/Admin del ERP.
    • Ruta: /config/portal/gateway (o donde viva la configuracion del portal en el ERP)
    • Acceso: solo operadores con permisos de configuracion

Interacciones del usuario ​

  1. El operador selecciona la sucursal a configurar (si el sistema maneja multiples sucursales visibles).
  2. Elige el gateway desde un selector: paypertic, mercadopago, o "Sin pagos online".
  3. Ingresa las credenciales segun el gateway seleccionado:
    • PayPerTIC: api_key + webhook_token (api_secret es opcional)
    • MercadoPago: api_key + api_secret + webhook_token
  4. Guarda la configuracion. El sistema confirma el guardado.
  5. Opcionalmente, puede limpiar la configuracion para deshabilitar pagos online.

Comportamiento del formulario ​

  • El campo api_secret se muestra u oculta segun el gateway seleccionado:
    • paypertic: campo oculto o marcado como opcional
    • mercadopago: campo obligatorio
  • Los campos de credenciales se muestran con mascara (tipo password). Al editar, el campo se limpia para forzar el reingreso del valor.
  • Si portal.gateway.nombre se deja en blanco o se selecciona "Sin pagos online", los demas campos se deshabilitan y la sucursal no permitira pagos online.

Permisos ​

PermisoDescripcionAcciones permitidas
CONFIG_PORTAL_VIEWVer configuracion del portalConsultar valores actuales
CONFIG_PORTAL_WRITEModificar configuracion del portalGuardar cambios de gateway

Backend ​

Persistencia ​

Las claves viven en la tabla data_config a nivel SUCURSAL (schema sucXXXX). Se usa el mecanismo existente de configuracion del sistema.

ClaveTipoDescripcion
portal.gateway.nombrestringIdentificador del gateway: paypertic, mercadopago, o vacio para deshabilitar
portal.gateway.api_keystringAPI key o Bearer token del gateway
portal.gateway.api_secretstringSecret adicional (requerido por MercadoPago, opcional para PayPerTIC)
portal.gateway.webhook_tokenstringToken Bearer que el gateway envia en sus webhooks para autenticar requests entrantes

Nivel de tabla: SUCURSAL — schema suc{sucursal_id}. Cada sucursal tiene su propia configuracion independiente.

Uso en el backend del portal ​

El modulo Modules/Portal/ lee estas claves en POST /portal/pagos/iniciar para:

  1. Determinar que gateway corresponde a la sucursal del usuario autenticado (via sucursal_id del JWT)
  2. Instanciar el adapter correcto via PaymentGatewayFactory
  3. Validar el webhook entrante en POST /portal/pagos/webhook comparando la firma con portal.gateway.webhook_token

Si portal.gateway.nombre esta vacio o null, POST /portal/pagos/iniciar retorna 422 GATEWAY_NOT_CONFIGURED sin intentar procesar el pago.

Reglas de negocio ​

  1. Gateway por sucursal: Cada sucursal configura su propio gateway de forma independiente. Una sucursal puede usar PayPerTIC mientras otra usa MercadoPago.
  2. Deshabilitar pagos: Si portal.gateway.nombre esta vacio o null, la sucursal no permite pagos online. El portal mostrara la opcion de pago deshabilitada para esa sucursal.
  3. api_secret obligatorio para MercadoPago: Si el gateway seleccionado es mercadopago, portal.gateway.api_secret es obligatorio. Para paypertic, es opcional.
  4. Credenciales enmascaradas: Las claves almacenadas son sensibles. No se retornan en texto plano desde la API de lectura — solo se indica si estan configuradas o no.

Casos de uso ​

Caso 1: Habilitar pagos online para una sucursal ​

Actor: Operador con permiso CONFIG_PORTAL_WRITE

Precondiciones:

  • La sucursal existe y no tiene gateway configurado (o tiene uno diferente)
  • El operador tiene las credenciales del gateway a mano

Flujo principal:

  1. El operador abre la vista de configuracion de gateway del portal
  2. Selecciona el gateway: paypertic o mercadopago
  3. Ingresa api_key, api_secret (si corresponde) y webhook_token
  4. Guarda la configuracion
  5. El sistema persiste los valores en data_config de la sucursal correspondiente

Postcondiciones:

  • portal.gateway.nombre tiene el valor del gateway elegido
  • Las credenciales estan almacenadas en data_config
  • El Portal de Clientes de esa sucursal puede procesar pagos online

Caso 2: Deshabilitar pagos online para una sucursal ​

Actor: Operador con permiso CONFIG_PORTAL_WRITE

Flujo principal:

  1. El operador abre la vista de configuracion
  2. Selecciona "Sin pagos online" o borra el valor del gateway
  3. Guarda la configuracion

Postcondiciones:

  • portal.gateway.nombre queda vacio o null
  • POST /portal/pagos/iniciar retorna 422 GATEWAY_NOT_CONFIGURED para esa sucursal
  • El Portal de Clientes no muestra la opcion de pago online

Consideraciones tecnicas ​

Seguridad ​

  • Las credenciales (api_key, api_secret, webhook_token) son sensibles. Deben almacenarse de forma segura en data_config.
  • El endpoint de lectura de configuracion NO retorna el valor actual de las credenciales en texto plano. Solo indica si estan configuradas (boolean o valor enmascarado tipo "****configured****").
  • Al editar, el campo de credencial se limpia en el frontend para forzar reingreso explicito.

Multi-tenancy ​

  • La configuracion vive en el schema de la sucursal (suc{sucursal_id}), siguiendo el patron multi-tenant del sistema.
  • Si el ERP maneja multiples sucursales por tenant, el operador debe configurar cada sucursal por separado.

Gateways soportados ​

GatewayValor en configapi_secret obligatorio
PayPerTICpayperticNo (opcional)
MercadoPagomercadopagoSi

Dependencias ​

Funcionalidades relacionadas ​

Modulos externos ​

  • PaymentGatewayFactory en Modules/Portal/Infrastructure/Adapters/
  • Tabla data_config a nivel sucursal