Solución de Problemas

Esta página cubre los problemas más comunes encontrados con el Terminal POS y sus soluciones. Si su problema no está listado aquí, contacte a su administrador del sistema o revise los logs de la aplicación en logs/pos-terminal.log.

La Impresora No Responde

Síntomas: Los recibos no se imprimen después de completar una venta, o la luz de la impresora está apagada.

Soluciones:

1. Verifique que la impresora esté encendida y el cable USB o de red esté conectado de forma segura.
2. Para impresoras USB, verifique que la impresora aparezca en la lista de dispositivos del sistema. En Linux, ejecute lsusb y busque el fabricante de la impresora.
3. Para impresoras de red, confirme que la dirección IP de la impresora sea alcanzable ejecutando ping <ip-impresora> desde el terminal de la tienda.
4. Reinicie la aplicación del Terminal POS. La conexión con la impresora se restablece al iniciar.
5. Verifique que la impresora tenga papel y no muestre una luz de error (generalmente un LED rojo parpadeante indica un atasco de papel o tapa abierta).

Si los recibos aún no se imprimen, la venta no se pierde. Todas las transacciones se almacenan en la base de datos independientemente del estado de la impresora. Puede reimprimir cualquier recibo desde el historial de transacciones.

Escáner de Código de Barras No Detectado

Síntomas: Escanear un código de barras no produce ningún efecto en la pantalla del Terminal POS.

Soluciones:

1. Desconecte el escáner y conéctelo de nuevo. La mayoría de los escáneres USB son detectados automáticamente.
2. Asegúrese de que el escáner esté configurado para operar en modo de emulación de teclado (HID). La mayoría de los escáneres vienen en este modo por defecto, pero consulte el manual del escáner si fue reiniciado recientemente.
3. Asegúrese de que el campo de entrada del Terminal POS tenga el foco. Haga clic en la pantalla principal de ventas si otro diálogo ha tomado el foco.
4. Pruebe el escáner con un editor de texto. Si los datos del código de barras aparecen en el editor pero no en el Terminal POS, el problema está en la configuración de la aplicación y no en el hardware.

Fallos de Sincronización

Síntomas: El indicador de estado de sincronización muestra "Sin Conexión" o "Error" aunque la tienda tenga conectividad a internet.

Soluciones:

1. Verifique que el servidor HQ esté ejecutándose y sea accesible. Intente alcanzar el endpoint de sincronización desde la máquina de la tienda: curl https://hq.ejemplo.com:3001/health.
2. Revise el SYNC_TOKEN en el archivo .env del servidor de la tienda. Si el token fue revocado o expiró, genere uno nuevo desde el Gerente HQ.
3. Revise los logs del servidor de la tienda para mensajes de error específicos. Las causas comunes incluyen certificados TLS expirados, reglas de firewall bloqueando el puerto WebSocket o fallas de resolución DNS.
4. Reinicie el servidor de la tienda. La conexión de sincronización se restablecerá automáticamente.

Las ventas y otras operaciones locales no se ven afectadas por fallos de sincronización. Todos los datos se almacenan localmente y se sincronizarán una vez que se restaure la conexión.

Caja Registradora Bloqueada

Síntomas: Un cajero no puede abrir una nueva sesión de caja porque el sistema reporta que la caja ya está abierta, pero nadie la está usando.

Soluciones:

1. Esto generalmente ocurre después de una caída del sistema o un corte de energía durante una sesión activa.
2. Un usuario con el permiso pos:force_close_register (típicamente un gerente de tienda) puede forzar el cierre de la sesión obsoleta desde Menú > Gerente > Forzar Cierre de Caja.
3. El cierre forzado crea un Reporte Z con los datos disponibles. El conteo de efectivo se registra como cero ya que no se realizó un conteo físico.
4. Después del cierre forzado, la caja queda disponible para una nueva sesión.

Búsqueda de Productos Lenta

Síntomas: Escribir en el campo de búsqueda de productos tiene un retraso notable antes de que aparezcan los resultados.

Soluciones:

1. La base de datos local de productos puede necesitar reindexación. Reinicie el servidor de la tienda, lo cual activa una reindexación al iniciar.
2. Si la tienda tiene un catálogo de productos muy grande (más de 50,000 artículos), considere actualizar la memoria de la máquina o cambiar a un SSD si actualmente usa un disco duro mecánico.
3. Verifique que PostgreSQL esté ejecutándose y responda con docker compose ps o su gestor de procesos.