TicoConta

01

Contexto

Sistema que desarrollo para el negocio de mi padre, con el objetivo de reducir la carga administrativa y facilitar el trabajo diario. Factura electrónicamente según la normativa de Costa Rica (nombre de trabajo: TicoConta) e incluye módulos de cubicación de madera y digitalización de facturas en papel.

Responsabilidades

• Diseño y arquitectura del sistema: monolito modular con un contrato de importaciones entre módulos
• Desarrollo frontend: aplicación web instalable con React, TypeScript y Vite
• Desarrollo backend: API en FastAPI con cálculo fiscal determinista y firma de comprobantes
• Modelado y gestión de datos en PostgreSQL 16 con migraciones Alembic
• Diseño e implementación de APIs, incluida la integración con la API pública de Hacienda
• Integración entre la interfaz, la API, la base de datos y los servicios externos
• Diseño de interfaces y experiencia de usuario para operar desde el móvil
• Pruebas, validaciones y mantenimiento técnico con pytest, Vitest y Playwright

02

Problema

Pasar de una evidencia de venta a una factura electrónica válida, y dejar de depender de cuadernos y facturas en papel para el control del negocio.

03

Solución

Una API modular que calcula impuestos de forma determinista, genera los comprobantes en XML y los firma, y una aplicación web instalable para operar desde el móvil. Los módulos de cubicación y digitalización proponen datos que una persona revisa antes de confirmarlos.

Implementado

• Multiempresa con roles configurables y auditoría encadenada
• Catálogos oficiales (CABYS) y calculadora fiscal determinista
• XML de factura, tiquete y notas de crédito y débito validado contra los esquemas oficiales v4.4
• Firma XAdES-EPES y almacenamiento inmutable con verificación SHA-256
• Cubicación de madera con aritmética exacta y revisión humana obligatoria
• Digitalización de facturas por proyecto, con revisión, detección de duplicados, comprobación aritmética contra el total escrito y resumen en PDF
• Conector con Hacienda para enviar comprobantes y consultar su estado, probado contra un simulador local
• Integración funcional con la API pública de Hacienda: consulta de los datos del contribuyente al configurar la empresa, implementada y comprobada

Planificado, en curso

• Sistema de contabilidad (próxima etapa)
• Módulo de inventario (en desarrollo, todavía no confirmado en el repositorio)

04

Arquitectura

Monolito modular en FastAPI sobre PostgreSQL 16 en Docker, con migraciones Alembic, y una interfaz en React, TypeScript y Vite. Un contrato de importaciones impide que los módulos de IA dependan de los fiscales.

05

Tecnologías

• Python
• FastAPI
• PostgreSQL
• Alembic
• Docker
• OpenAI API
• React
• TypeScript
• Vite
• Tailwind CSS
• pytest
• Vitest
• Playwright
• Cloudflare Tunnel

06

Decisiones técnicas

• Barrera técnica anti-producción: nada se envía a Hacienda sin una autorización explícita.
• Aritmética exacta con decimales; el servidor siempre recalcula y el navegador nunca envía importes calculados.
• Lo que lee la IA queda pendiente de revisión humana y nunca reemplaza el total escrito.
• Escaneo de secretos en cada commit y archivos sensibles fuera del repositorio.

07

Resultados verificables

• Según el informe de cierre de la etapa 2 (29 de septiembre de 2026): 556 pruebas de backend en verde y 94 % de cobertura. No se volvieron a ejecutar en esta revisión.

Límites conocidos

• Consultar los datos públicos de Hacienda no es emitir facturas: el envío de comprobantes y la recepción de su aceptación oficial solo se han probado contra un simulador local.
• En el repositorio, el envío de comprobantes a producción de Hacienda está bloqueado por código hasta autorizarlo expresamente.
• Los datos del repositorio son ficticios.

08

Capturas y evidencias

Interfaz en escritorio y móvil

Abrir a tamaño completo ((se abre en una pestaña nueva))

Abrir a tamaño completo ((se abre en una pestaña nueva))

Galería de pantallas

• Abrir a tamaño completo ((se abre en una pestaña nueva))

• Abrir a tamaño completo ((se abre en una pestaña nueva))

• Abrir a tamaño completo ((se abre en una pestaña nueva))

• Abrir a tamaño completo ((se abre en una pestaña nueva))

• Abrir a tamaño completo ((se abre en una pestaña nueva))

Capturas reales del entorno de demostración de TicoConta, con un contribuyente ficticio. No se emitió nada ante Hacienda y el correo de la cuenta aparece difuminado.

Cerrar

Documentación y pruebas

• Informe de cierre parcial de la etapa 2, bitácoras y registro de decisiones de arquitectura.