El problema
La facturación electrónica en Costa Rica no es opcional: la norma DGT-R-48-2016 del Ministerio de Hacienda obliga a todo contribuyente a emitir comprobantes electrónicos firmados digitalmente y enviarlos a la plataforma de Hacienda en tiempo real. La mayoría de las soluciones POS disponibles en el mercado son genéricas o de origen extranjero, con integraciones locales deficientes y costos de licencia prohibitivos para negocios medianos. El objetivo era construir una suite completa, desde la caja hasta la API, adaptada desde el inicio a la normativa costarricense.
La solución
POS Tree Codes es una suite híbrida de tres capas. La aplicación principal es un cliente de escritorio en Java 21 Swing pensado para el punto de venta principal: maneja ventas, cierres de caja, gestión de inventario y emisión de facturas electrónicas con firma digital. Para puntos de venta adicionales —meseros, bodegas, puntos móviles— existe un WebPOS en PHP, más liviano, que consume la misma API REST. El núcleo del sistema es una API REST en Spring Boot 3.5 que centraliza la lógica de negocio, la comunicación con la DGT y la persistencia en MySQL 8.
Arquitectura
La base de datos tiene 57 tablas que cubren desde el catálogo de productos y las tablas de precios diferenciados hasta el historial de documentos electrónicos y los logs de comunicación con Hacienda. El módulo de facturación electrónica implementa la generación del XML según el esquema XSD oficial, la firma con certificado digital (PKCS#12) y el envío asíncrono a la API de la DGT con reintentos automáticos ante fallos de conectividad. El cliente Swing tiene más de 250 clases Java organizadas en capas (presentación, servicio, repositorio) y se distribuye como un ejecutable nativo con instalador para Windows. La autenticación entre el WebPOS y la API usa JWT con rotación de tokens, mientras que el cliente desktop mantiene una sesión persistente cifrada localmente.
Forma del sistema
El proyecto tenía que comportarse como un solo producto sobre tres superficies muy distintas:
- un POS desktop para el flujo principal de caja
- un WebPOS más ligero para puntos de venta auxiliares
- una API REST central que concentra reglas de negocio e integración fiscal
Esa separación fue intencional. La caja principal necesitaba velocidad, atajos de teclado y continuidad local. Los puntos secundarios necesitaban un acceso más liviano desde el navegador. La API se convirtió en el núcleo operativo compartido para que precios, inventario y facturación no se desviaran entre clientes.
Por qué esto era más que una función de facturación
La facturación electrónica suena como un requisito de cumplimiento, pero en la práctica toca casi todo el sistema:
- la venta no puede cerrarse sin datos fiscales válidos
- el XML tiene que respetar el esquema oficial con precisión
- las firmas deben ser válidas y trazables
- un fallo de conectividad no puede bloquear al negocio de forma permanente
Eso significa que el módulo fiscal no es un agregado. Define el estándar de confiabilidad de todo el producto.
Resultado
El resultado final es una suite aterrizada a la operación local, no adaptada desde una plantilla extranjera genérica. La app desktop resuelve el flujo pesado del día a día, el WebPOS extiende el sistema a estaciones adicionales y el backend convierte el cumplimiento costarricense en un proceso repetible en lugar de un ritual manual frágil.
Lo valioso del proyecto no es solo que emite facturas. Es que conecta ventas, inventario, autenticación y comunicación fiscal dentro de un sistema coherente sobre el cual un negocio realmente puede operar.
