Documentación del Sistema

Appearance

Tarjetas - Resource ​

Modulo: ventas Tipo: Resource Estado: Implementado Fecha: 2026-02-09

DOCUMENTACION RETROSPECTIVA - Generada a partir de codigo implementado el 2026-02-09

Descripcion ​

Las tarjetas representan los distintos tipos de tarjetas de credito/debito aceptadas por la empresa como medio de pago en el proceso de facturacion. Cada tarjeta puede asociarse opcionalmente a una cuenta contable del plan de cuentas, lo que permite que al facturar con condicion de venta "Tarjeta", el sistema genere automaticamente el movimiento de caja correspondiente contra dicha cuenta.

Este recurso forma parte de las "Bases" del modulo de ventas y es prerequisito para poder emitir comprobantes con condicion de venta tipo Tarjeta (codigo 3).

Frontend (Perspectiva de Usuario) ​

Vistas ​

  • Listado de tarjetas: Tabla con todas las tarjetas registradas en el sistema, con columnas de nombre y acciones (editar/eliminar). Accesible desde el sidebar de ventas bajo "Bases > Tarjetas".
  • Formulario de alta/modificacion: Modal que permite crear una nueva tarjeta o modificar una existente.

Interacciones del usuario ​

  • Listar tarjetas: Al acceder a la vista, se cargan automaticamente todas las tarjetas activas.
  • Crear nueva tarjeta: Mediante el boton "Nva. Tarjeta" (con atajo Alt+A) se abre el formulario modal en modo alta.
  • Editar tarjeta: Desde la tabla, mediante el boton de edicion en cada fila, se abre el formulario modal precargado con los datos existentes.
  • Eliminar tarjeta: Desde la tabla, mediante el boton de eliminacion, se solicita confirmacion antes de eliminar (soft delete).
  • Exportar datos: La tabla permite exportar a Excel y PDF mediante botones integrados.

Permisos ​

  • VENTAS_BASES_TARJETAS: Permiso requerido para acceder al listado, alta y modificacion de tarjetas. Sin este permiso, el item no aparece en el sidebar.

Estados de UI ​

  • Carga inicial: Se muestra un indicador de carga ("Cargando datos") mientras se obtienen las tarjetas del servidor.
  • Guardando: Se muestra indicador "Registrando cambios" durante el envio del formulario.
  • Eliminando: Se muestra indicador "Eliminando" durante la eliminacion.
  • Error: Se muestran mensajes de error en modal cuando ocurre un fallo en la operacion.
  • Confirmacion de eliminacion: Se solicita confirmacion al usuario antes de eliminar una tarjeta.

Backend (Perspectiva de Datos de Negocio) ​

Entidades de negocio ​

Tarjeta: Representa un tipo de tarjeta aceptada como medio de pago.

Datos necesarios ​

  • Nombre (obligatorio): Denominacion de la tarjeta (ej: "Visa", "Mastercard", "American Express"). Maximo 100 caracteres.
  • Cuenta contable (condicional): Numero de cuenta del plan de cuentas asociada a la tarjeta. Obligatoria si la empresa tiene habilitado el modulo de Tesoreria; opcional en caso contrario.

Relaciones de negocio ​

  • Una tarjeta puede estar asociada a una cuenta del plan de cuentas de contabilidad.
  • Una tarjeta puede ser referenciada por multiples comprobantes de venta (facturas, notas de credito, notas de debito) cuando la condicion de venta es "Tarjeta".
  • La condicion de venta "Tarjeta" (codigo 3) activa la seleccion obligatoria de una tarjeta en el formulario de facturacion.

Validaciones de negocio ​

  • El nombre es obligatorio y no puede superar los 100 caracteres.
  • La cuenta contable es nullable a nivel de validacion estructural, pero si la empresa tiene habilitado el modulo de Tesoreria, la cuenta se vuelve obligatoria y debe existir en el plan de cuentas.
  • La eliminacion es logica (soft delete): el registro se marca como eliminado pero no se borra fisicamente.

Reglas de negocio ​

  • Regla 1: Obligatoriedad condicional de cuenta contable

    • Condicion: La empresa tiene habilitado el modulo de Tesoreria (configuracion del sistema PermisosEmpresa).
    • Accion: Al crear o modificar una tarjeta, el campo cuenta se vuelve obligatorio. Se valida que la cuenta seleccionada exista en el plan de cuentas.

  • Regla 2: Integracion con facturacion

    • Condicion: Se emite un comprobante de venta con condicion de venta "Tarjeta" (codigo 3).
    • Accion: El sistema exige seleccionar una tarjeta registrada. Al procesar el comprobante, se genera un movimiento de caja adicional contra la cuenta contable de la tarjeta seleccionada.

  • Regla 3: Eliminacion logica

    • Condicion: Se solicita eliminar una tarjeta.
    • Accion: El registro no se elimina fisicamente sino que se marca con fecha de eliminacion. Las tarjetas eliminadas no aparecen en listados ni en selectores de facturacion.

  • Regla 4: Requisito previo para facturacion con tarjeta

    • Condicion: No existen tarjetas registradas en el sistema.
    • Accion: Al intentar seleccionar condicion de venta "Tarjeta" en facturacion, se muestra un error indicando que debe cargar al menos un tipo de tarjeta para continuar.

Casos de uso ​

Caso 1: Crear una nueva tarjeta ​

Actor: Usuario con permiso VENTAS_BASES_TARJETAS

Precondiciones:

  • El usuario debe estar autenticado y tener el permiso correspondiente.
  • Si la empresa tiene modulo de Tesoreria, deben existir cuentas en el plan de cuentas.

Flujo principal:

  1. El usuario accede al listado de tarjetas desde el sidebar de ventas.
  2. Presiona el boton "Nva. Tarjeta" o utiliza el atajo Alt+A.
  3. Se abre el formulario modal con el titulo "Nueva Tarjeta".
  4. El usuario ingresa el nombre de la tarjeta (obligatorio).
  5. Si la empresa tiene modulo de Tesoreria, el usuario busca y selecciona una cuenta contable mediante un campo de autocompletado (busqueda por codigo o nombre de cuenta, filtrado por cuentas con saldo propio).
  6. El usuario presiona "Aceptar".
  7. El sistema valida los datos y crea la tarjeta.
  8. La nueva tarjeta aparece en la tabla del listado.

Postcondiciones:

  • La tarjeta queda registrada y disponible para su uso en el proceso de facturacion.

Flujos alternativos:

  • Error de validacion: Si falta el nombre o la cuenta (cuando es obligatoria), el formulario no se envia (validacion HTML nativa con required).
  • Cuenta inexistente: Si la cuenta proporcionada no existe en el plan de cuentas, se muestra un error.

Caso 2: Modificar una tarjeta existente ​

Actor: Usuario con permiso VENTAS_BASES_TARJETAS

Precondiciones:

  • Debe existir al menos una tarjeta registrada.

Flujo principal:

  1. El usuario accede al listado de tarjetas.
  2. Presiona el boton de edicion en la fila de la tarjeta deseada.
  3. Se abre el formulario modal con el titulo "Modificacion de tarjeta: {id}" y los datos precargados.
  4. Si la tarjeta tiene cuenta contable asociada, se resuelve y muestra el nombre de la cuenta.
  5. El usuario modifica los campos deseados.
  6. El usuario presiona "Aceptar".
  7. El sistema actualiza la tarjeta.
  8. La fila de la tabla se refresca con los datos actualizados.

Postcondiciones:

  • Los datos de la tarjeta quedan actualizados.

Caso 3: Eliminar una tarjeta ​

Actor: Usuario con permiso VENTAS_BASES_TARJETAS

Precondiciones:

  • Debe existir al menos una tarjeta registrada.

Flujo principal:

  1. El usuario presiona el boton de eliminacion en la fila de la tarjeta deseada.
  2. El sistema muestra un dialogo de confirmacion.
  3. El usuario confirma la eliminacion.
  4. El sistema realiza una eliminacion logica (soft delete).
  5. La fila desaparece de la tabla.

Postcondiciones:

  • La tarjeta queda marcada como eliminada y ya no aparece en listados ni selectores.

Consideraciones ​

Seguridad ​

  • El acceso al recurso esta protegido por el permiso VENTAS_BASES_TARJETAS.
  • Solo los usuarios autenticados con JWT valido pueden acceder a los endpoints.

Auditoria ​

Nota (2026-02-09): No implementado en recursos legacy. Se agregará en refactorización futura a 5-layer DDD.

Rendimiento ​

  • Se espera un volumen bajo de registros (tipicamente menos de 50 tipos de tarjeta por empresa).
  • El listado carga todas las tarjetas de una vez sin paginacion.

Dependencias ​

Funcionalidades relacionadas ​

  • Condicion de Venta: La condicion de venta tipo "Tarjeta" (codigo 3) depende de este recurso para funcionar.
  • Facturacion: Los comprobantes de venta (facturas, notas de credito, notas de debito) referencian tarjetas cuando la condicion de venta es "Tarjeta".
  • Movimientos de Caja (Tesoreria): Al facturar con tarjeta, se genera un movimiento de caja adicional contra la cuenta contable de la tarjeta.
  • Plan de Cuentas (Contabilidad): Las tarjetas se vinculan a cuentas del plan de cuentas para la generacion de asientos contables.

Servicios externos ​

  • No se requieren servicios externos.

Criterios de aceptacion ​

  • [x] AC-001: El usuario puede listar todas las tarjetas activas del sistema.
  • [x] AC-002: El usuario puede crear una nueva tarjeta proporcionando nombre y opcionalmente una cuenta contable.
  • [x] AC-003: Si la empresa tiene modulo de Tesoreria habilitado, la cuenta contable es obligatoria al crear/modificar tarjetas.
  • [x] AC-004: El usuario puede modificar el nombre y la cuenta de una tarjeta existente.
  • [x] AC-005: El usuario puede eliminar una tarjeta mediante eliminacion logica.
  • [x] AC-006: Las tarjetas eliminadas no aparecen en el listado.
  • [x] AC-007: El listado permite exportar a Excel y PDF.
  • [x] AC-008: Al facturar con condicion de venta "Tarjeta", el sistema requiere seleccionar una tarjeta registrada.
  • [x] AC-009: Al facturar con tarjeta, se genera un movimiento de caja contra la cuenta contable de la tarjeta.

Preguntas Pendientes ​

Hay preguntas sobre esta funcionalidad que requieren validacion. Ver: Preguntas sobre Tarjetas

Referencias Tecnicas ​

NOTA IMPORTANTE: Esta documentacion fue generada automaticamente analizando el codigo implementado. Se recomienda validar con stakeholders de negocio para confirmar que refleja fielmente los requisitos originales.