Tarjetas - Documentacion Tecnica Frontend

Modulo: ventas Feature: Tarjetas (tipos de tarjeta para facturacion) Fecha: 2026-02-09

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

Documento de Negocio

Arquitectura: Legacy (Vanilla JS + PHP)

Este recurso esta implementado enteramente con la arquitectura legacy del sistema: PHP server-side rendering para la vista, vanilla JavaScript con jQuery para la logica del cliente, y el patron proxy (backend PHP intermedio) para comunicacion con la API REST.

No existe migracion a React/TypeScript para este recurso.

Componentes Implementados

Vista Principal: tarjetas.php

Ubicacion: public/view/mod-ventas/tarjetas.phpURL: ?loc=mvtProposito: Pagina completa que muestra el listado de tarjetas con operaciones CRUD.

Estructura HTML:

Breadcrumb: Home > Ventas > Tarjetas
Boton de alta: "Nva. Tarjeta | Alt+A" (id: btn_alta)
Tabla DataTables (id: table_view)
Carga del sidebar de ventas
Activacion del item de menu "Bases > Clientes" en el sidebar (nota: activa idMainSideBarClientes en lugar de un id propio para tarjetas)

Dependencias externas cargadas:

jQuery + jQuery UI (autocompletado)
DataTables con plugins (responsive, buttons, BS4)
Bootstrap 4
AdminLTE
pdfmake, jszip (para exportaciones PDF/Excel)

Script Principal: tarjetas.js

Ubicacion: public/js/view/mod-ventas/tarjetas.jsTipo: ES Module Proposito: Logica de la vista principal (inicializacion de tabla, eventos CRUD).

Dependencias importadas:

Modulo	Proposito
`getActionButtonsColumnConfig`	Configuracion de botones de accion en columnas de tabla
`createFormTarjeta`	Funcion que crea el formulario modal de tarjeta
`ApiRequest`	Clase para comunicacion con el backend (patron legacy)
`LANG_TABLE`	Traduccion al espanol para DataTables
`eliminarFila`	Utilidad para eliminar fila de DataTable
`refrescarFila`	Utilidad para actualizar fila de DataTable

Configuracion de DataTable:

Columna	Campo	Visible	Render
Codigo	`id`	No (oculto)	-
Nombre	`nombre`	Si	Sanitizado via `getHTML()`
Acciones	-	Si	Botones delete + edit

Botones de exportacion: ['excel', 'pdf']

Flujo de inicializacion:

Se inicializa la tabla DataTables con columnas configuradas.
Se muestra popup de carga.
Se realiza request.get('mod-ventas/tarjetas').
Se agregan las filas a la tabla.
Se cierra el popup de carga.

Eventos:

Click en btn_alta: Abre createFormTarjeta() y agrega la fila retornada a la tabla.
Click en edit (por fila): Abre createFormTarjeta({ updateData }) y refresca la fila.
Click en delete (por fila): Muestra confirmacion, ejecuta request.delete('mod-ventas/tarjetas', { id }), elimina la fila.

Ubicacion: public/js/components/forms/ventas/tarjeta.jsTipo: ES Module (export default) Proposito: Crea dinamicamente un formulario modal (Bootstrap) para alta/edicion de tarjeta.

Firma:

javascript

async function createFormTarjeta({ updateData = {}, onSubmitCallback = null })

Parametros:

Parametro	Tipo	Descripcion
`updateData`	`object`	Datos para precargar en edicion (`{ id, nombre, cuenta }`)
`updateData.id`	`number`	ID de la tarjeta (solo en edicion)
`updateData.nombre`	`string`	Nombre de la tarjeta
`updateData.cuenta`	`?number`	Numero de cuenta contable
`onSubmitCallback`	`function(object)`	Callback ejecutado al guardar exitosamente

Flujo:

Carga HTML del formulario via getContentFile() desde php/components/mod-venta/forms/tarjeta.
Inserta el modal en el DOM.
Configura eventos de apertura/cierre del modal.
Si es edicion, precarga nombre y resuelve la cuenta contable via request.get('mod-contabilidad/cuenta', { numero }).
Configura autocompletado en el campo cuenta (si existe, es decir, si la empresa tiene modulo Tesoreria):
- Endpoint: mod-contabilidad/cuenta con parametros { filter, saldo_propio: true, scope: 'min' }
- Formato: {numero} | {nombre}
- Seleccion: almacena data.numero en tarjeta.cuenta
Al submit:
- Si tarjeta.id existe (edicion): request.put('mod-ventas/tarjetas', tarjeta)
- Si no (alta): request.post('mod-ventas/tarjetas', tarjeta)
- Ejecuta onSubmitCallback con el objeto tarjeta
- Cierra el modal

Estado local (objeto tarjeta):

javascript

{
    id: null,       // ID (asignado en edicion o tras crear)
    nombre: null,   // Nombre de la tarjeta
    cuenta: null    // Numero de cuenta contable
}

Template del Formulario: tarjeta.php

Ubicacion: public/php/components/mod-venta/forms/tarjeta.phpTipo: PHP template (cargado via AJAX por tarjeta.js) Proposito: HTML del formulario modal, con logica condicional para mostrar campo de cuenta.

Campos del formulario:

Campo	ID	Tipo HTML	Requerido	Condicion de visibilidad
Nombre	`inputNombre`	text	Si (`required`)	Siempre visible
Cuenta	`inputCuenta`	text (autocompletado)	Si (`required`, cuando visible)	Solo si la empresa tiene modulo Tesoreria habilitado

Logica PHP condicional:

php

$modulos = json_decode($_SESSION["SD_PERMISO_SISTEMA"], true);
$hasTesoreria = (bool)$modulos[Modulo::TESORERIA->value];

Si $hasTesoreria es true, se renderiza el campo de cuenta con su label y badge informativo ("Busqueda por Codigo o nombre"). Si es false, el campo no se renderiza en absoluto.

Botones:

Cancelar (cierra el modal)
Aceptar (submit del formulario)

Proxy Backend: tarjetas.php

Ubicacion: public/php/backend/mod-ventas/tarjetas.phpTipo: Proxy PHP (patron legacy) Proposito: Redirigir peticiones del frontend legacy hacia la API REST del backend.

Metodos HTTP soportados:

Metodo	Comportamiento
GET	Reenvio a `mod-ventas/tarjetas[/{id}]`
POST	Reenvio del body JSON a `mod-ventas/tarjetas`
PUT	Reenvio con extraccion del `id` del body para la URL
DELETE	Reenvio con extraccion del `id` del body para la URL

Patron: Utiliza la clase Request del frontend para comunicarse con el backend Slim. Valida sesion ($_SESSION['SD_USER']), parsea respuesta JSON, y retorna solo el campo data de la respuesta.

Integracion con Facturacion

El recurso tarjetas se integra con el formulario de facturacion:

Archivos involucrados:

js/view/mod-ventas/facturacion/form-header.js: Contiene la logica de seleccion de tarjeta.
js/view/mod-ventas/facturacion/comprobante.js: El objeto comprobante incluye propiedad tarjeta.
js/view/mod-ventas/facturacion/index.js: Verifica si el comprobante tiene tarjeta.

Flujo en facturacion:

Al seleccionar una condicion de venta que tiene es_tarjeta = true, se muestra el select de tarjetas.
Si las tarjetas no estan cargadas en el Map local, se obtienen via request.get('mod-ventas/tarjetas').
Si no hay tarjetas registradas, se muestra error "Debe cargar al menos un tipo de tarjeta para continuar".
Las tarjetas se cachean en un Map local para evitar requests repetidos.
Al seleccionar una tarjeta, se asigna su ID al campo comprobante.tarjeta.
Si se edita un comprobante que ya tenia tarjeta, se preselecciona la tarjeta en el select.

Estado y Flujo de Datos

Vista (tarjetas.php)
  |
  v
tarjetas.js (inicializacion)
  |-- GET mod-ventas/tarjetas --> proxy PHP --> API REST
  |     |
  |     v
  |   DataTable (tabla renderizada)
  |
  |-- Click "Nva. Tarjeta" / "Editar"
  |     |
  |     v
  |   createFormTarjeta (tarjeta.js)
  |     |-- Carga HTML (tarjeta.php via AJAX)
  |     |-- Si edicion: GET mod-contabilidad/cuenta (resolucion de cuenta)
  |     |-- Submit: POST o PUT mod-ventas/tarjetas
  |     |-- Callback: agrega/refresca fila en DataTable
  |
  |-- Click "Eliminar"
        |
        v
      Confirmacion --> DELETE mod-ventas/tarjetas --> elimina fila

Comunicacion con Backend

Endpoints consumidos

Endpoint	Metodo	Proposito	Desde
`mod-ventas/tarjetas`	GET	Listar tarjetas	tarjetas.js, form-header.js (facturacion)
`mod-ventas/tarjetas`	POST	Crear tarjeta	tarjeta.js (formulario)
`mod-ventas/tarjetas`	PUT	Actualizar tarjeta	tarjeta.js (formulario)
`mod-ventas/tarjetas`	DELETE	Eliminar tarjeta	tarjetas.js (vista)
`mod-contabilidad/cuenta`	GET	Buscar cuenta por numero	tarjeta.js (resolucion en edicion)
`mod-contabilidad/cuenta`	GET	Autocompletado de cuentas	tarjeta.js (campo cuenta)

Patron de comunicacion: Todas las peticiones pasan por el proxy PHP public/php/backend/mod-ventas/tarjetas.php, excepto las de contabilidad que usan su propio proxy.

Routing y Navegacion

URL	Vista	Descripcion
`?loc=mvt`	`view/mod-ventas/tarjetas.php`	Listado de tarjetas

Sidebar: El item aparece bajo "Bases" en el sidebar de ventas, condicionado al permiso VENTAS_BASES_TARJETAS.

Breadcrumb: Home > Ventas > Tarjetas

Validaciones del Formulario

Validacion HTML nativa

Campo	Atributo	Efecto
Nombre	`required`	No permite submit sin valor
Nombre	`max="100"`	Limita a 100 caracteres (atributo `max` en input text, no `maxlength` - esto podria no funcionar como esperado)
Cuenta	`required`	No permite submit sin valor (solo cuando el campo esta visible, es decir, con Tesoreria habilitado)

Validacion JavaScript

Validacion	Ubicacion	Comportamiento
Formulario valido	`isValidForm(form)`	Verifica validez HTML5 antes de submit
Nombre trim	`inputNombre blur`	Si el valor trimmeado esta vacio, se asigna `null`

Nota: No existe validacion Zod ni esquema de validacion TypeScript. Este recurso utiliza el patron legacy de validacion HTML nativa + metodo utilitario isValidForm.

Preguntas Tecnicas Pendientes

Hay aspectos tecnicos que requieren validacion. Ver: Preguntas sobre Tarjetas

Referencias

NOTA IMPORTANTE: Esta documentacion fue generada automaticamente analizando el codigo implementado. Validar cambios futuros contra este baseline.

Fase 1 Mvp

Fase 2 Sse

Fase 3 Production

Joins

Retenciones

Ganancias

Catalogos

Extensiones

Presupuestos

Recursos Principales

Relaciones

Catalogos Base

Cupon Pago

Facturacion

Gestion Miembros

Grupos Familiares

Soporte Tecnico

Architecture

Backend

Api

Database

Migrations

Middleware

Security

Services

Deployment

Development

Testing

Frontend

Integrations

Payment Gateways

Retenciones

Tarjetas - Documentacion Tecnica Frontend ​

Documento de Negocio ​

Arquitectura: Legacy (Vanilla JS + PHP) ​

Componentes Implementados ​

Vista Principal: tarjetas.php ​

Script Principal: tarjetas.js ​

Formulario Modal: tarjeta.js ​

Template del Formulario: tarjeta.php ​

Proxy Backend: tarjetas.php ​

Integracion con Facturacion ​

Estado y Flujo de Datos ​

Comunicacion con Backend ​

Endpoints consumidos ​

Routing y Navegacion ​

Validaciones del Formulario ​

Validacion HTML nativa ​

Validacion JavaScript ​

Preguntas Tecnicas Pendientes ​

Referencias ​