Sistema de punto de venta para terminal (TUI) construido con Bun, Ink, Zustand y Drizzle ORM.
- Gestión de ventas y tickets - Venta rápida con código de barras
- Inventario - Productos con códigos de barras, categorías, unidades
- Facturación CFDI - Integración con FacturAPI para generar facturas
- Sistema de clientes - Registro de clientes con RFC para facturación
- Puntos de fidelidad - Sistema de puntos escalable para clientes
- Impresión térmica - Tickets con banner desde imagen
- Reportes de ventas - Reportes diarios y por período
- Autenticación - Login con PIN y roles (admin/cashier)
- Configuración TUI - Menú interactivo para todas las configuraciones
- Bun (última versión)
- Node.js 22+
- Docker y Docker Compose (opcional)
- Impresora térmica (opcional)
# Instalar dependencias npm install # Inicializar base de datos bun run seed
Si prefieres usar Docker, el proyecto ya está configurado para ejecutarse en contenedores:
# Construir la imagen docker-compose build # Iniciar modo interactivo (Punto de Venta) docker-compose up app
Important
Para interactuar con la interfaz TUI (terminal) dentro de Docker, es necesario que el servicio tenga tty: true y stdin_open: true (ya configurado en docker-compose.yml).
El sistema usa SQLite como motor de base de datos (archivo pos.db), gestionado con Drizzle ORM.
| Tabla | Descripción |
|---|---|
products |
Catálogo de productos (sku, name, price, stock, etc.) |
sales |
Registro de ventas/tickets con datos de CFDI |
users |
Usuarios del sistema (username, pin, role) |
clients |
Clientes para facturación (RFC, razón social, puntos) |
config |
Configuración del negocio |
# Agregar usuario con rol cashier (por defecto) pos.exe add user juan 1234 # Agregar usuario admin pos.exe add user juan 1234 --role admin
| Rol | Descripción |
|---|---|
admin |
Acceso completo al sistema (configuración, usuarios, reportes) |
cashier |
Usuario de caja (solo ventas y reportes) |
bun run dev
pos --settings
Abre un menú interactivo para configurar:
- Tienda - Nombre, RFC, razón social, dirección, email, teléfono, régimen fiscal
- Facturación - API Key de FacturAPI, proveedor, modo sandbox
- Productos - Agregar, editar, eliminar, buscar, filtrar por categoría
- Usuarios - Agregar, editar, eliminar, cambiar rol
- Impuestos - Tasa de IVA (%), reiniciar número de ticket
- Impresora - Habilitar/deshabilitar impresión
- Ventas - Ver notas, filtrar por método de pago y status CFDI
- Clientes - Agregar, editar, eliminar, buscar, filtro por RFC/nombre/email/código
<<<<<<< HEAD
pos --help # Mostrar ayuda pos --version # Mostrar versión pos --settings # Abrir configuración TUI pos import products # Importar productos desde CSV pos export products # Exportar productos a CSV pos seed # Insertar productos de ejemplo pos add user <username> <pin> [--role] # Agregar usuario pos config get # Ver configuración pos config config set <key> <value> # Actualizar configuración
======= Puedes ejecutar los comandos directamente o a través de Docker:
| Comando | Ejecución Local | Ejecución Docker |
|---|---|---|
| Ayuda | pos.exe --help |
docker-compose run --rm app --help |
| Versión | pos.exe --version |
docker-compose run --rm app --version |
| Importar | pos.exe import products |
docker-compose run --rm app import products |
| Exportar | pos.exe export products |
docker-compose run --rm app export products |
| Seed | pos.exe seed |
docker-compose run --rm app seed |
| Usuario | pos.exe add user <user> <pin> |
docker-compose run --rm app add user <user> <pin> |
| Config Get | pos.exe config get |
docker-compose run --rm app config get |
| Config Set | pos.exe config set <k> <v> |
docker-compose run --rm app config set <k> <v> |
2ae9ae81a7c2b3405f737f12daecead51c952e57
sku,name,price,cost,category,stock,barcode,unittype,unitqty,minstock 001,Producto 1,10.50,5.00,BEB,100,123456789,pza,1,10 002,Producto 2,25.00,12.00,ALI,50,987654321,kg,1,5
| Campo | Requerido | Descripción |
|---|---|---|
| sku | ✅ | Código único |
| name | ✅ | Nombre del producto |
| price | ✅ | Precio de venta |
| cost | ❌ | Costo |
| category | ❌ | Categoría (default: GEN) |
| stock | ❌ | Stock inicial (default: 0) |
| minStock | ❌ | Stock mínimo (default: 5) |
| unitType | ❌ | pza, kg, g, lt, ml, m, cm (default: pza) |
| unitQty | ❌ | Cantidad por unidad |
| barcode | ❌ | Código de barras |
# Importar productos pos import products productos.csv # Simular importación (sin guardar) pos import products productos.csv --dry-run
El sistema soporta generación de facturas electrónicas mediante FacturAPI.
- Obtener API Key de FacturAPI
- Ejecutar
pos --settingse ir a Facturación - Ingresar API Key y configurar sandbox (pruebas) o producción
- Guardar configuración
- Al pagar una venta, seleccionar opción de facturar (tecla F)
- Ingresar RFC del cliente
- Ingresar razón social
- Ingresar email para enviar factura
- El sistema crea/busca automáticamente el cliente y genera la factura
Los clientes se almacenan en la tabla clients con:
- code - Código interno único (CL-00001, CL-00002, etc.)
- rfc - RFC único del cliente
- razonSocial - Nombre o razón social
- email - Correo electrónico
- telefono - Teléfono de contacto
- direccion - Dirección fiscal
- regimenFiscal - Régimen fiscal (601, 603, etc.)
- puntos - Puntos de fidelidad (escalable para futuro)
Los clientes acumulan puntos que pueden usarse a futuro para:
- Descuentos en compras
- Canje por productos
- Niveles de cliente (bronze, silver, gold)
El sistema está diseñado para escalar con más campos en el futuro.
| Tecla | Acción |
|---|---|
| Tab | Cambiar panel |
| ↑↓←→ | Navegar |
| Enter | Seleccionar/Pagar |
| 1-4 | Alternativas de navegación |
| / | Buscar productos |
| F | Facturar venta |
| R | Ver reportes |
| L | Cerrar sesión |
| Ctrl+Q | Salir |
| Tecla | Acción |
|---|---|
| + | Aumentar cantidad |
| - | Disminuir cantidad |
| d | Eliminar item |
| Tecla | Acción |
|---|---|
| 1-8 | Navegar secciones |
| ↑↓ | Mover en listas |
| Enter | Guardar/Confirmar |
| T | Impresión de prueba (en impresora) |
| E | Editar (en listas) |
| X | Eliminar (en listas) |
| A | Agregar (solo admin) |
| / | Buscar (en productos/clientes) |
| Esc | Volver atrás |
El sistema de impresión utiliza los datos del negocio desde la base de datos y puede imprimir un banner desde assets/banner.png.
| Tipo | Interfaz | Descripción |
|---|---|---|
| Windows Printer | printer:NOMBRE |
Impresora local Windows |
| TCP | tcp://192.168.1.100:9100 |
Impresora de red |
| USB | USB |
Impresora USB |
| Archivo | /dev/usb/lp0 |
Archivo/Dispositivo |
| Ancho | Caracteres | Tipo |
|---|---|---|
| 48 | 48 caracteres | 80mm (default) |
| 58 | 58 caracteres | 58mm |
| 80 | 80 caracteres | 80mm |
| Charset | Descripción |
|---|---|
| PC437 | USA |
| PC850 | Multilingual |
| PC860 | Portuguese |
| PC863 | Canadian French |
| PC865 | Nordic |
| PC858 | Euro |
| WIN1252 | Windows Latin-1 |
| ISO8859_1 | ISO Latin-1 |
- Seleccionar Tipo de impresora con flechas →/←
- Para Windows Printer, el campo Interfaz permite navegar ↑↓ para listar las impresoras del sistema
- Presionar T para imprimir ticket de prueba
- Enter para guardar configuración
# Compilar executable
bun build src/app.tsx --compile --outfile pos.exeEl ejecutable pos.exe queda en el directorio del proyecto. Los comandos CLI funcionan directamente con el ejecutable.
Repositorio: https://github.com/avalontm/openpos.git
Licencia MIT - Copyright (c) 2026 avalontm
Proyecto desarrollado por AvalonTM