Appearance
Generacion de Cupon de Pago PDF
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 generacion del cupon de pago PDF. Para el proceso completo (generacion, validacion y cobro cross-schema), consultar el documento de referencia.
Descripcion
Problema que resuelve
En el modulo de membresias, la empresa factura periodicamente a clientes por sus servicios de membresia. Cada periodo genera una unica factura por cliente (o por titular de grupo familiar). Antes de esta funcionalidad, el cliente no disponia de un comprobante fisico que identificara su deuda del periodo con un mecanismo de pago rapido, lo que obligaba al cajero a buscar manualmente al cliente y su factura pendiente en cada operacion de cobro.
Solucion
Se implementa la generacion de un documento PDF denominado "Cupon de Pago" que contiene toda la informacion de la deuda de un periodo especifico junto con un codigo de barras escaneable. Este cupon permite al cliente presentarse en cualquier punto de cobro y agilizar el proceso de pago mediante el escaneo automatico del codigo.
Valor de negocio
- Experiencia del cliente mejorada: El cliente recibe un documento claro con su deuda y un mecanismo simple de pago
- Agilidad operativa: Reduce significativamente el tiempo de atencion en caja al eliminar la busqueda manual
- Reduccion de errores: La identificacion automatica mediante codigo de barras elimina errores de carga manual
- Proceso estandarizado: Uniformiza el proceso de cobro de membresias en toda la organizacion
- Flexibilidad: El cupon puede usarse en cualquier sucursal habilitada
Frontend (Perspectiva de Usuario)
Vistas
Vista de generacion de cupon
- Formulario de generacion con seleccion de cliente y periodo
- El usuario indica el cliente (ordcon_id) y el periodo (anio, mes)
- El sistema obtiene la factura del periodo correspondiente
- El resultado es un documento PDF descargable/imprimible
Interacciones del usuario
Generacion individual de cupon
- El usuario accede a la funcionalidad de generacion de cupones dentro del modulo de membresias
- Selecciona o busca al cliente (o grupo familiar)
- Indica el periodo especifico (anio y mes)
- El sistema verifica que exista deuda pendiente para ese periodo
- El sistema genera el documento PDF con el cupon de pago
- El usuario puede descargar o imprimir el PDF
Permisos
| Permiso | Descripcion | Acciones permitidas |
|---|---|---|
| Generacion de cupones de pago | Permite generar cupones para clientes | Generar cupon individual, descargar PDF |
Estados de UI
- Inicial: Formulario vacio esperando seleccion de cliente y periodo
- Cargando: Mientras se consulta la deuda del cliente y se genera el PDF
- Exito: Cupon generado, PDF disponible para descarga o impresion
- Error - Sin deuda: Se informa que el cliente no tiene deuda pendiente para el periodo seleccionado
- Error - Datos incompletos: Se solicitan los datos faltantes (cliente o periodo)
Backend (Perspectiva de Datos de Negocio)
Entidades de negocio involucradas
Cupon de Pago El cupon es un documento generado que representa la deuda de un periodo especifico.
| Dato de negocio | Descripcion |
|---|---|
| Cliente | Referencia al cliente titular (ordcon_id) |
| Periodo | Anio y mes al que corresponde la deuda |
| Factura del periodo | La factura pendiente del periodo especificado |
| Monto pendiente | Importe de la factura del periodo (destacado en el documento) |
| Codigo de barras | Codigo ITF de 19 digitos que identifica univocamente la deuda |
Factura de membresia La factura generada por el proceso de facturacion periodica del modulo de membresias.
Cliente / Grupo familiar El cliente titular a quien se emite el cupon. Si es grupo familiar, siempre se emite al titular del grupo.
Relaciones de negocio
- Un cupon de pago corresponde a exactamente UN periodo y UNA factura
- Un cliente puede tener multiples cupones (uno por cada periodo facturado)
- Si el cliente pertenece a un grupo familiar, el cupon se emite al titular del grupo
- La factura referenciada debe estar pendiente de pago al momento de generar el cupon
Validaciones de negocio
| Validacion | Descripcion | Comportamiento si no cumple |
|---|---|---|
| Cliente existente | El cliente indicado debe existir en el sistema | Error: Cliente no encontrado |
| Deuda del periodo pendiente | Debe existir una factura pendiente para el periodo seleccionado | Mensaje: No hay deuda pendiente para este periodo |
| Periodo valido | El periodo debe corresponder a un anio y mes validos | Error: Periodo invalido |
Contenido del Cupon de Pago
El documento PDF generado debe contener la siguiente informacion:
Encabezado
- Titulo del documento: "CUPON DE PAGO"
- Fecha de emision del cupon
Datos del cliente
- Nombre completo o razon social
- Numero de identificacion (DNI/CUIT)
- Si es grupo familiar: indicar "GRUPO FAMILIAR - TITULAR: [nombre]"
Detalle de la deuda
- Periodo: mes y anio
- Comprobante: tipo y numero de factura
- Fecha de emision de la factura
- Importe a pagar: monto pendiente (destacado visualmente)
Codigo de barras
- Codigo de barras ITF visible y escaneable (formato SVG)
- Numero del codigo en formato legible debajo del codigo de barras
Informacion adicional
- Instrucciones de pago
- Puntos de cobro disponibles
Formato del Codigo de Barras
Especificacion
El codigo de barras utiliza el formato Interleaved 2 of 5 (ITF), un formato numerico compacto ampliamente soportado por lectores estandar de codigo de barras.
Estructura
El codigo consta de 19 digitos con la siguiente composicion:
| Campo | Longitud | Descripcion | Ejemplo |
|---|---|---|---|
| Sucursal | 4 digitos | Codigo de sucursal | 0001 |
| Cliente | 8 digitos | Identificador del cliente titular | 00056789 |
| Periodo | 6 digitos | Periodo facturado en formato AAAAMM | 202501 |
| Digito verificador | 1 digito | Verificacion de integridad (modulo 10) | 8 |
Ejemplo de codigo completo: 0001000567892025018
Caracteristicas clave del formato
- No contiene valores economicos: El codigo solo identifica la factura; el monto se obtiene siempre de la base de datos al momento del cobro
- Combinacion unica: La combinacion Sucursal + Cliente + Periodo identifica univocamente una deuda
- Reimpresion segura: El mismo codigo siempre identifica la misma factura/periodo, permitiendo reimprimir sin cambios
Algoritmo del digito verificador
Se utiliza el metodo Modulo 10 con ponderacion 3-1:
- Se toman los 18 digitos (Sucursal + Cliente + Periodo), de derecha a izquierda
- Se multiplica cada digito alternando pesos 3 y 1 (empezando por 3)
- Se suman todos los productos
- Se calcula: DV = (10 - (suma % 10)) % 10
Este algoritmo detecta el 100% de errores de un solo digito y la gran mayoria de errores de transposicion.
Reglas de Negocio
RN-001: Generacion de cupon por cliente titular y periodo
Descripcion: Cada cupon corresponde a un periodo especifico y por lo tanto a una unica factura. Si el cliente pertenece a un grupo familiar, el cupon se emite a nombre del titular del grupo.
Condicion: El usuario solicita generar un cupon para un cliente y periodo determinado.
Accion:
- Identificar al titular si es grupo familiar
- Obtener la factura del periodo especificado
- Emitir cupon a nombre del titular con la factura del periodo
RN-002: Cupon estatico al momento de generacion
Descripcion: El cupon refleja la deuda existente al momento de su generacion. No se actualiza automaticamente si la factura es cancelada posteriormente.
Condicion: Se genera un cupon de pago.
Accion:
- Capturar la factura del periodo al momento de generacion
- Si posteriormente la factura es cancelada, el cupon queda desactualizado
- La validacion del estado real de la factura se realiza al momento del escaneo/cobro, no al generar el cupon
RN-003: Un cupon, una factura, un periodo
Descripcion: Cada cupon representa exactamente una factura de un periodo. No se consolidan multiples facturas ni multiples periodos en un mismo cupon.
Condicion: Siempre que se genera un cupon.
Accion:
- Generar un cupon por cada combinacion unica de cliente + periodo
- Si un cliente tiene multiples periodos pendientes, se genera un cupon separado por cada periodo
RN-004: Codigo de barras sin valores monetarios
Descripcion: El codigo de barras solo contiene informacion de identificacion (sucursal, cliente, periodo), nunca contiene el monto a pagar. Esto previene alteraciones de montos y permite ajustes de precio sin regenerar cupones.
Condicion: Siempre que se genera o escanea un codigo de barras.
Accion:
- Codificar solo: sucursal, cliente, periodo y digito verificador
- El monto real se obtiene siempre de la base de datos al momento del cobro
Casos de Uso
CU-001: Generacion individual de cupon de pago
Actor: Usuario de Membresias / Administrador
Objetivo: Generar un cupon de pago para un cliente especifico y un periodo determinado
Precondiciones:
- Usuario autenticado con permiso de generacion de cupones
- El cliente existe en el sistema
- Existe una factura pendiente para el periodo seleccionado
Flujo principal:
- El usuario accede a la funcionalidad de generacion de cupones
- El usuario selecciona o busca al cliente
- El usuario indica el periodo (anio y mes)
- El sistema verifica que exista una factura pendiente del periodo para el cliente
- El sistema genera el codigo de barras ITF de 19 digitos con los datos del cupon
- El sistema genera el documento PDF con el formato establecido (datos del cliente, detalle de deuda, codigo de barras en SVG, monto pendiente destacado, instrucciones de pago)
- El usuario descarga o imprime el PDF
Postcondiciones:
- Se genera un cupon de pago PDF con todos los datos requeridos
- El cupon tiene un codigo de barras unico y valido
- El cupon esta listo para entrega al cliente
Flujos alternativos:
- Sin deuda del periodo: Si el cliente no tiene factura pendiente del periodo, el sistema informa y no genera cupon
- Grupo familiar: Si el cliente es parte de un grupo, el cupon se genera para el titular con la factura del periodo del grupo
- Datos incompletos: Si falta el cliente o el periodo, el sistema solicita completar la informacion
CU-002: Generacion masiva de cupones por periodo
Actor: Usuario de Membresias / Administrador
Objetivo: Generar cupones de pago para todos los clientes con deuda pendiente de un periodo especifico
Precondiciones:
- Usuario autenticado con permiso de generacion de cupones
- Existen clientes con deuda pendiente en el periodo seleccionado
Flujo principal:
- El usuario accede a la funcionalidad de generacion masiva de cupones
- El usuario indica el periodo especifico (anio y mes)
- El sistema identifica todos los clientes con factura pendiente de ese periodo
- El sistema muestra la lista de clientes que tendran cupon generado
- El usuario confirma la generacion
- El sistema genera un cupon por cada cliente con deuda del periodo
- El usuario puede descargar los cupones individuales o en un archivo consolidado
Postcondiciones:
- Se genera un cupon de pago por cada cliente con deuda pendiente del periodo
- Cada cupon tiene un codigo de barras unico
- Los cupones estan listos para distribucion a clientes
Flujos alternativos:
- Sin clientes con deuda: Si no hay clientes con deuda del periodo, el sistema informa
- Grupos familiares: Para cada grupo, se genera un unico cupon a nombre del titular
Consideraciones
Seguridad
- Solo usuarios con permiso especifico pueden generar cupones
- El cupon contiene datos identificatorios del cliente que deben ser protegidos
- El codigo de barras incluye digito verificador para prevenir modificaciones manuales
- Al no contener el monto en el codigo, se previene la alteracion de valores economicos
Auditoria
| Operacion | Informacion a capturar |
|---|---|
| Generacion de cupon | Usuario que genero, fecha, cliente, periodo, factura incluida, monto |
| Generacion masiva | Usuario que genero, fecha, periodo, cantidad de cupones generados |
Rendimiento
- Generacion individual: Respuesta esperada en menos de 5 segundos
- Generacion masiva: Hasta 500 cupones por ejecucion; puede requerir procesamiento en cola para volumenes altos
- Formato PDF: La generacion del documento con codigo de barras SVG debe ser eficiente para no demorar la operacion
Dependencias
Funcionalidades relacionadas
- Facturacion de Membresias: Genera las facturas que se incluyen en los cupones. Sin facturacion previa, no hay deuda para generar cupones
- Grupos Familiares: Logica de consolidacion de deuda por grupo y determinacion del titular
- Validacion de Cupon (Escaneo): cupon-validacion-process.md - El cupon generado aqui es consumido por el proceso de validacion al momento del cobro
- Cobro Cross-Schema: cobro-cross-schema-process.md - El cupon permite el cobro en sucursales diferentes a la emisora
Servicios externos
- Servicio de generacion de PDF: Servicio encargado de convertir el template del cupon en documento PDF
- Lectores de codigo de barras: Hardware compatible con ITF para escaneo en puntos de cobro (minimo 203 DPI para impresion)
Criterios de Aceptacion
- [x] AC-001: El usuario puede generar un cupon de pago para un cliente individual con deuda pendiente de un periodo especifico
- [x] AC-002: El cupon muestra todos los datos requeridos: datos del cliente, periodo, factura del periodo, monto pendiente (destacado), codigo de barras, instrucciones de pago
- [x] AC-003: Para grupos familiares, el cupon se emite a nombre del titular con la factura del periodo del grupo
- [x] AC-004: El codigo de barras es de tipo ITF con 19 digitos y sigue la estructura: Sucursal (4) + Cliente (8) + Periodo (6) + DV (1)
- [x] AC-005: El digito verificador se calcula con algoritmo modulo 10 ponderacion 3-1
- [x] AC-006: El codigo de barras NO contiene valores economicos (el monto se obtiene de la base de datos al cobrar)
- [x] AC-007: El cupon se genera en formato PDF con codigo de barras en SVG
- [x] AC-008: Si el cliente no tiene deuda pendiente del periodo, el sistema informa y no genera cupon
- [x] AC-009: El cupon puede reimprimirse sin cambiar el codigo (mismo codigo siempre identifica la misma factura/periodo)
Notas Adicionales
Relacion con el documento de proceso integral
Este documento cubre especificamente la funcionalidad de generacion del cupon de pago (Componente 1 del proceso integral). Para el proceso completo, incluyendo validacion por escaneo y cobro cross-schema, consultar el documento de proceso integral.
Template del cupon
El cupon utiliza un template HTML con Bootstrap para su maquetacion, que luego se convierte a PDF. El formato incluye:
- Encabezado con titulo "CUPON DE PAGO" y fecha de emision
- Seccion de datos del cliente
- Detalle de la deuda del periodo con monto destacado
- Codigo de barras en formato SVG con numero legible debajo
- Seccion de instrucciones de pago
Codigo de barras ITF
Se eligio el formato Interleaved 2 of 5 (ITF) por las siguientes razones de negocio:
- Exclusivamente numerico (adecuado para el formato de 19 digitos)
- Muy compacto, ocupa poco espacio en el documento (aproximadamente 4-5 cm de ancho por 1 cm de alto)
- Ampliamente soportado por lectores estandar de codigo de barras
- Alta densidad de informacion
Historial de Cambios
| Fecha | Version | Autor | Descripcion |
|---|---|---|---|
| 2026-01-27 | 1.0 | Sistema | Creacion del documento - Funcionalidad YA IMPLEMENTADA en produccion |