Appearance
Validacion de Cupon de Pago (Escaneo)
Modulo: Membresias / CtaCte Tipo: Process Estado: Implementado Fecha: 2026-01-27 Fecha de Implementacion: 2026-01-27
Documento de referencia integral: Cupon de Pago - Proceso Integral
Este documento describe la funcionalidad especifica de validacion y decodificacion del codigo de barras del cupon de pago. Para el proceso completo (generacion, validacion y cobro cross-schema), consultar el documento de referencia.
Descripcion
Problema que resuelve
El proceso de cobro de membresias requiere que el cajero identifique manualmente al cliente, localice la factura pendiente del periodo y cargue los datos en el recibo. Este proceso es lento, propenso a errores y aumenta el tiempo de atencion al cliente.
Solucion
Se implementa un mecanismo de validacion y decodificacion de codigos de barras que, al escanear el cupon de pago del cliente, decodifica automaticamente la informacion contenida (sucursal, cliente, periodo), verifica la integridad del codigo, busca la factura correspondiente en la base de datos, y precarga todos los datos necesarios en el formulario de recibo.
Valor de negocio
- Agilidad en el cobro: Reduce significativamente el tiempo de atencion al cliente mediante el escaneo automatico
- Reduccion de errores: La precarga automatica elimina errores de identificacion de cliente o factura
- Experiencia del cliente mejorada: Atencion mas rapida y sin necesidad de proporcionar datos adicionales
- Seguridad: El digito verificador detecta codigos alterados o corrompidos antes de procesar el cobro
- Flexibilidad operativa: Permite tanto el escaneo con lector como el ingreso manual del codigo
Frontend (Perspectiva de Usuario)
Vistas
Vista de carga de recibo (CtaCte) - Integracion con escaneo
- Campo o area dedicada para la lectura del codigo de barras del cupon
- Indicador visual que muestra el resultado de la validacion (exito, error, advertencia)
- Formulario de recibo con campos precargados automaticamente tras un escaneo exitoso
Interacciones del usuario
Cobro con cupon escaneado
- El cajero accede a la vista de carga de recibo
- El cajero activa el modo escaneo de codigo de barras (o posiciona el cursor en el campo de lectura)
- El cajero escanea el codigo de barras del cupon presentado por el cliente (o ingresa el codigo manualmente)
- El sistema decodifica el codigo y realiza las validaciones
- Si la validacion es exitosa, el sistema precarga automaticamente: cliente, factura del periodo, monto
- El cajero verifica la informacion precargada
- El cajero selecciona la forma de pago
- El cajero confirma el recibo
Permisos
| Permiso | Descripcion | Acciones permitidas |
|---|---|---|
| Cobro de recibos | Permiso existente de carga de recibos en CtaCte | Escanear cupon, ver datos precargados, confirmar recibo |
| Cobro cross-schema | Permite cobrar deuda de otra sucursal | Requerido cuando el cupon pertenece a un schema diferente (ver Cobro Cross-Schema) |
Estados de UI
- Esperando escaneo: Campo activo para lectura del codigo de barras
- Procesando: Decodificando codigo y consultando datos en la base de datos
- Precargado exitosamente: Datos del recibo listos, esperando verificacion y confirmacion del usuario
- Advertencia - Cupon vencido: Cupon con fecha de vencimiento pasada; se permite continuar con confirmacion del usuario
- Error - Codigo invalido: Codigo con longitud incorrecta, caracteres no numericos, o digito verificador incorrecto
- Error - Factura ya cancelada: La factura del cupon ya fue pagada; se muestra informacion del pago anterior
- Error - Cliente no encontrado: El identificador de cliente del codigo no existe en el sistema
- Error - Sin permisos cross-schema: El cupon pertenece a otra sucursal y el usuario no tiene permiso de cobro cross-schema
Backend (Perspectiva de Datos de Negocio)
Proceso de Validacion
Al recibir un codigo de barras escaneado, el sistema realiza las siguientes validaciones en orden:
Paso 1: Validacion de formato
- Verificar que el codigo tenga exactamente 19 digitos
- Verificar que contenga solo caracteres numericos (0-9)
Paso 2: Decodificacion de campos
- Extraer sucursal (posiciones 1-4)
- Extraer identificador de cliente (posiciones 5-12)
- Extraer periodo en formato AAAAMM (posiciones 13-18)
- Extraer digito verificador (posicion 19)
Paso 3: Verificacion de integridad
- Recalcular el digito verificador de los primeros 18 digitos usando el algoritmo modulo 10 con ponderacion 3-1
- Comparar el digito calculado con el extraido del codigo
- Si no coinciden, rechazar el codigo como invalido o corrupto
Paso 4: Validacion de negocio
- Verificar que la sucursal (schema) existe en el sistema
- Verificar que el cliente existe y esta activo en la sucursal indicada
- Buscar la factura del periodo especificado para el cliente
- Verificar que la factura esta pendiente de pago (no cancelada)
Paso 5: Obtencion de datos para precarga
- Obtener monto real de la factura desde la base de datos (nunca del codigo)
- Determinar si es cobro local o cross-schema (comparando sucursal del cupon con sucursal del cajero)
- Preparar datos para precarga del recibo
Entidades de negocio involucradas
Codigo de barras decodificado Informacion extraida del codigo de barras escaneado.
| Dato de negocio | Descripcion |
|---|---|
| Sucursal | Codigo de sucursal donde esta la deuda (4 digitos) |
| Cliente | Identificador del cliente titular (8 digitos) |
| Periodo | Periodo de la deuda en formato AAAAMM (6 digitos) |
| Digito verificador | Digito de control de integridad (1 digito) |
Resultado de validacion Datos retornados tras una validacion exitosa para precarga del recibo.
| Dato de negocio | Descripcion |
|---|---|
| Cliente | Datos completos del cliente (nombre, identificacion) |
| Factura del periodo | Referencia a la factura pendiente del periodo |
| Monto a cobrar | Importe real de la factura obtenido de la base de datos |
| Indicador cross-schema | Si la deuda pertenece a una sucursal diferente a la del cajero |
| Sucursal de origen | En caso cross-schema, la sucursal donde esta la deuda |
Precarga de datos en el recibo
Al validar exitosamente un codigo de barras, el sistema precarga automaticamente los siguientes datos en el formulario de recibo:
| Campo del recibo | Comportamiento |
|---|---|
| Cliente | Seleccionado automaticamente |
| Factura a cancelar | La factura del periodo marcada para cancelacion |
| Monto | Monto real de la factura obtenido de la base de datos |
| Fecha del recibo | Fecha actual (editable por el usuario) |
| Forma de pago | Pendiente de seleccion por el usuario |
| Observaciones | Vacio (editable por el usuario) |
Validaciones de negocio
| Validacion | Descripcion | Comportamiento si no cumple |
|---|---|---|
| Longitud del codigo | Exactamente 19 digitos | Error: Codigo invalido |
| Solo numeros | El codigo debe contener exclusivamente digitos 0-9 | Error: Codigo invalido |
| Digito verificador correcto | DV recalculado debe coincidir con el del codigo | Error: Codigo de barras invalido o corrupto |
| Sucursal existente | El codigo de sucursal debe corresponder a un schema existente | Error: Sucursal no encontrada |
| Cliente existente y activo | El cliente debe existir en la sucursal indicada | Error: Cliente no existe en el sistema |
| Factura del periodo existente | Debe existir una factura para el periodo indicado | Error: Factura no encontrada para el periodo |
| Factura pendiente de pago | La factura no debe estar cancelada | Error: Factura ya cancelada el [fecha] con recibo [numero] |
| Permisos cross-schema | Si la deuda es de otra sucursal, el usuario debe tener permiso | Error: No tiene permisos para cobrar de otra sucursal |
Reglas de Negocio
RN-001: Verificacion de factura al momento del cobro
Descripcion: Al escanear un cupon, el sistema debe verificar el estado actual de la factura del periodo en la base de datos. El cupon puede ser antiguo o desactualizado, por lo que el estado real de la factura tiene prioridad sobre lo reflejado en el cupon impreso.
Condicion: El usuario escanea un cupon de pago.
Accion:
- Verificar el estado actual de la factura del periodo
- Si esta pendiente: precargar normalmente
- Si ya fue cancelada: mostrar mensaje informativo con fecha y numero de recibo del pago anterior
- No permitir procesar el cupon si la factura ya fue cancelada
RN-002: Advertencia por cupon vencido
Descripcion: Si un cupon tiene fecha de vencimiento y esta ha pasado, el sistema advierte al usuario pero no bloquea la operacion. El cajero decide si procede con el cobro.
Condicion: El usuario escanea un cupon con fecha de vencimiento pasada.
Accion:
- Mostrar advertencia: "Este cupon tiene fecha de vencimiento [fecha]. Desea continuar?"
- Permitir al usuario decidir si procede con el cobro
- No bloquear la operacion
RN-003: Monto real desde la base de datos
Descripcion: El monto a cobrar se obtiene siempre de la base de datos al momento del escaneo, nunca del codigo de barras. Esto garantiza que se cobre el monto correcto incluso si hubo ajustes de precio posteriores a la emision del cupon.
Condicion: Siempre que se valida un cupon.
Accion:
- Ignorar cualquier monto impreso en el cupon
- Obtener el monto real de la factura desde la base de datos
- Precargar el monto obtenido de la base de datos en el recibo
RN-004: Ingreso manual del codigo
Descripcion: Si el codigo de barras no puede ser escaneado (daño, mala impresion), el sistema permite el ingreso manual del numero del codigo. Las mismas validaciones se aplican al codigo ingresado manualmente.
Condicion: El codigo de barras no puede ser leido por el lector.
Accion:
- Permitir al usuario ingresar los 19 digitos del codigo manualmente
- Aplicar las mismas validaciones que para un codigo escaneado
- Precargar datos de la misma manera si la validacion es exitosa
RN-005: Deteccion automatica de cobro cross-schema
Descripcion: Al decodificar el codigo de barras, el sistema compara la sucursal del cupon con la sucursal actual del cajero. Si son diferentes, el cobro se identifica automaticamente como cross-schema y se aplican las reglas y permisos correspondientes.
Condicion: La sucursal codificada en el cupon es diferente a la sucursal donde opera el cajero.
Accion:
- Detectar automaticamente que se trata de un cobro cross-schema
- Verificar que el usuario tiene permiso de cobro cross-schema
- Si tiene permiso: precargar datos indicando "COBRO CROSS-SCHEMA: Deuda de sucursal [nombre]"
- Si no tiene permiso: mostrar error y no permitir el cobro
Casos de Uso
CU-001: Validacion exitosa de cupon en sucursal local
Actor: Cajero / Usuario de Tesoreria
Objetivo: Escanear el codigo de barras de un cupon de pago y precargar automaticamente los datos en el recibo
Precondiciones:
- Usuario autenticado con permiso de carga de recibos
- Cliente presente con cupon de pago impreso
- Lector de codigo de barras disponible (o capacidad de ingreso manual)
Flujo principal:
- El cajero accede a la vista de carga de recibo
- El cajero escanea el codigo de barras del cupon
- El sistema decodifica los 19 digitos del codigo
- El sistema verifica el digito verificador (modulo 10 ponderacion 3-1)
- El sistema identifica la sucursal, cliente y periodo
- El sistema confirma que la sucursal del cupon coincide con la sucursal actual (cobro local)
- El sistema busca la factura del periodo y verifica que esta pendiente
- El sistema obtiene el monto real de la base de datos
- El sistema precarga: cliente seleccionado, factura del periodo marcada para cancelacion, monto de la factura
- El cajero verifica los datos precargados, selecciona forma de pago y confirma
Postcondiciones:
- El formulario de recibo queda precargado con todos los datos del cupon
- El cajero solo debe seleccionar forma de pago y confirmar
Flujos alternativos:
- Codigo ilegible: El cajero ingresa manualmente los 19 digitos del codigo
- DV invalido: El sistema rechaza el codigo e informa que es invalido o esta corrupto
- Factura ya cancelada: El sistema informa que la factura fue pagada previamente con fecha y numero de recibo
- Cupon vencido: El sistema muestra advertencia, el cajero decide si continua
CU-002: Validacion de cupon con deteccion cross-schema
Actor: Cajero / Usuario de Tesoreria
Objetivo: Escanear un cupon cuya deuda pertenece a una sucursal diferente
Precondiciones:
- Usuario autenticado con permiso de carga de recibos
- Cliente presente con cupon de pago de otra sucursal
Flujo principal:
- El cajero escanea el codigo de barras del cupon
- El sistema decodifica y valida el formato y digito verificador
- El sistema detecta que la sucursal del cupon es diferente a la sucursal actual del cajero
- El sistema verifica que el usuario tiene permiso de cobro cross-schema
- El sistema busca la factura en la sucursal de origen (schema del cupon)
- El sistema verifica que la factura esta pendiente y obtiene el monto real
- El sistema precarga los datos indicando: "COBRO CROSS-SCHEMA: Deuda de sucursal [nombre]"
- El cajero verifica los datos y procede con el flujo de cobro cross-schema
Postcondiciones:
- El formulario de recibo queda precargado con datos del cupon y la indicacion de cross-schema
- El sistema esta preparado para ejecutar la transaccion distribuida al confirmar
Flujos alternativos:
- Sin permiso cross-schema: El sistema informa que el usuario no tiene permisos para cobrar deuda de otra sucursal; sugiere que el cliente acuda a la sucursal correspondiente
- Sucursal no accesible: El sistema informa que no se puede acceder al schema de la sucursal indicada
CU-003: Manejo de errores en escaneo
Actor: Cajero / Usuario de Tesoreria
Objetivo: Gestionar los distintos escenarios de error al escanear un cupon
Precondiciones:
- Usuario autenticado con permiso de carga de recibos
- Cliente presenta cupon de pago con algun problema
Flujo principal (codigo corrupto):
- El cajero escanea el codigo de barras
- El sistema detecta que el digito verificador no coincide
- El sistema muestra: "Codigo de barras invalido o corrupto"
- El cajero solicita al cliente otro cupon o procede al cobro manual
Flujo alternativo (factura ya pagada):
- El cajero escanea el codigo de barras
- El sistema decodifica y valida correctamente el formato
- El sistema busca la factura y encuentra que ya fue cancelada
- El sistema muestra: "La factura del cupon ya fue cancelada el [fecha] con recibo [numero]"
- El cajero informa al cliente que su deuda ya fue pagada
Flujo alternativo (cliente no encontrado):
- El cajero escanea el codigo de barras
- El sistema decodifica y valida el formato
- El sistema no encuentra al cliente en la sucursal indicada
- El sistema muestra: "Cliente no existe en el sistema"
- El cajero verifica manualmente la situacion del cliente
Postcondiciones:
- El sistema muestra mensajes claros y especificos segun el tipo de error
- El cajero puede decidir como proceder en cada caso
- Los intentos fallidos quedan registrados en auditoria
Consideraciones
Seguridad
- El digito verificador (modulo 10 ponderacion 3-1) previene modificaciones manuales del codigo
- Al no contener montos en el codigo, se previene la alteracion de valores economicos
- Se valida el permiso de cobro cross-schema antes de permitir operaciones entre sucursales
- Los intentos de uso de cupones invalidos deben quedar registrados
Auditoria
| Operacion | Informacion a capturar |
|---|---|
| Escaneo exitoso | Usuario, fecha/hora, codigo escaneado, cliente identificado, factura precargada |
| Escaneo con error | Usuario, fecha/hora, codigo escaneado, tipo de error |
| Deteccion cross-schema | Usuario, fecha/hora, sucursal origen vs sucursal destino, resultado de verificacion de permisos |
| Intento con cupon vencido | Usuario, fecha/hora, decision del cajero (continuo o cancelo) |
Rendimiento
- Validacion y precarga: Respuesta esperada en menos de 3 segundos desde el escaneo
- Consulta cross-schema: Puede requerir hasta 5 segundos por acceso a schema externo
- La validacion del cupon debe ser rapida para no demorar la atencion al cliente
Dependencias
Funcionalidades relacionadas
- Generacion de Cupon de Pago: cupon-generacion-process.md - Genera los cupones que este proceso valida y decodifica
- Cobro Cross-Schema: cobro-cross-schema-process.md - Cuando la validacion detecta un cobro entre sucursales, se delega al proceso cross-schema
- Carga de Recibos (CtaCte): Vista existente que se integra con el escaneo de cupones para precarga automatica
- Facturacion de Membresias: Genera las facturas que se consultan al validar el cupon
Servicios externos
- Lectores de codigo de barras: Hardware compatible con ITF para escaneo en puntos de cobro
- Sistema multi-tenant: Acceso a schemas de diferentes sucursales para validacion de datos
Criterios de Aceptacion
- [x] AC-001: Al escanear un codigo de barras valido, el sistema decodifica correctamente: sucursal (4 digitos), cliente (8 digitos), periodo (6 digitos), digito verificador (1 digito)
- [x] AC-002: El sistema verifica el digito verificador usando algoritmo modulo 10 con ponderacion 3-1
- [x] AC-003: Si el DV no coincide, el sistema rechaza el codigo con mensaje "Codigo de barras invalido o corrupto"
- [x] AC-004: El sistema busca la factura del periodo en la base de datos del schema correspondiente
- [x] AC-005: Si la factura esta pendiente, el sistema precarga automaticamente: cliente, factura del periodo, monto real de la base de datos
- [x] AC-006: Si la factura ya fue cancelada, el sistema informa con fecha y numero de recibo del pago anterior
- [x] AC-007: Si el cupon esta vencido, el sistema muestra advertencia pero permite continuar
- [x] AC-008: El sistema detecta automaticamente cuando el cupon pertenece a otra sucursal (cross-schema)
- [x] AC-009: Si el usuario no tiene permiso de cobro cross-schema, el sistema rechaza la operacion
- [x] AC-010: El usuario puede ingresar manualmente los 19 digitos del codigo si el lector no puede escanearlo
- [x] AC-011: Los datos retornados permiten precargar el recibo con toda la informacion necesaria para el cobro
Notas Adicionales
Manejo de errores detallado
| Error | Causa | Accion del sistema |
|---|---|---|
| Codigo ilegible | Codigo danado o mal impreso | Permitir ingreso manual del codigo |
| Checksum invalido | Codigo modificado o corrupto | Rechazar y solicitar verificacion |
| Cliente no encontrado | ID de cliente no existe | Error: "Cliente no existe en el sistema" |
| Factura no encontrada | No hay factura del periodo | Error: "Factura no encontrada para el periodo" |
| Factura ya cancelada | La factura ya fue pagada | Error: "Factura ya cancelada el [fecha] con recibo [numero]" |
| Schema no accesible | Usuario sin permiso cross-schema | Error: "No tiene permisos para cobrar de otra sucursal" |
Relacion con el documento de proceso integral
Este documento cubre especificamente la funcionalidad de validacion del cupon de pago (Componente 2 del proceso integral). Para el proceso completo, consultar el documento de proceso integral.
Historial de Cambios
| Fecha | Version | Autor | Descripcion |
|---|---|---|---|
| 2026-01-27 | 1.0 | Sistema | Creacion del documento - Funcionalidad YA IMPLEMENTADA en produccion |