Configuración de la impresora de recibos: cómo conectar e imprimir pedidos

El Print Agent de RestaurantManage es un servicio ligero de Windows que recibe comandos de impresión desde la nube y los envía a tu impresora térmica de recibos — permitiendo la impresión automática de recibos cuando se pagan pedidos o cuando se necesita imprimir tickets de cocina. El agente admite impresoras de red (TCP puerto 9100), impresoras USB y conexiones Windows Spooler. Esta guía cubre la instalación, configuración, conexión de impresoras y resolución de problemas.

¿Cómo funciona la impresión de recibos?

El flujo de trabajo de impresión es completamente automático. Cuando el cajero confirma el pago o se activa un ticket de cocina, el backend de RestaurantManage genera el recibo completo como comandos de bytes ESC/POS. Estos bytes se envían a través de una conexión WebSocket segura (PrintHub) al Print Agent que se ejecuta en un PC con Windows en tu restaurante. El agente decodifica los datos y los reenvía directamente a la impresora térmica conectada. Todo el proceso tarda menos de dos segundos desde la confirmación del pago hasta el recibo impreso.

El pipeline de impresión completo

Comprender el pipeline completo ayuda con la resolución de problemas. Esta es la secuencia de eventos cada vez que se imprime un recibo o ticket de cocina:

1. Pago confirmado: El cajero marca un pedido como pagado, o se activa manualmente un ticket de cocina.
2. El backend formatea el recibo: El servidor de RestaurantManage ejecuta ReceiptFormattingService, que construye el diseño del recibo usando ReceiptBuilder y lo convierte en comandos de bytes ESC/POS mediante EscPosCommands y EscPosRasterEncoder.
3. Datos enviados vía PrintHub: Los bytes del recibo formateado (codificados como Base64) se transmiten a través de un canal WebSocket seguro (SignalR PrintHub) al Print Agent correcto, identificado por el ID de tu restaurante.
4. Print Agent recibe el trabajo: El servicio de Windows que se ejecuta en tu PC local recibe el payload Base64, lo decodifica a bytes ESC/POS sin procesar e identifica qué impresora usar.
5. Salida de la impresora: Los bytes decodificados se envían directamente a la impresora térmica vía TCP de red, Windows Spooler o USB — y el recibo se imprime en segundos.

Qué se incluye en un recibo impreso

Cada recibo generado por RestaurantManage incluye un conjunto completo de detalles de la transacción. El encabezado muestra el nombre, dirección y logotipo del restaurante (si está configurado). El cuerpo incluye el número de mesa, una lista numerada de todos los artículos pedidos con cantidades y precios unitarios, cualquier descuento aplicable y un desglose fiscal detallado por categoría tributaria. El pie de página muestra el total del pedido, el método de pago (efectivo, tarjeta, etc.), la fecha y hora del pago y un mensaje de agradecimiento opcional. Los tickets de cocina siguen un formato simplificado que muestra solo el número de mesa, nombres de artículos, cantidades y cualquier nota.

Cuándo se activan los recibos

Los recibos de clientes se imprimen automáticamente cuando el cajero confirma el pago total o parcial de un pedido. Los tickets de cocina se imprimen cuando se envía un nuevo pedido desde el panel del cajero o la aplicación móvil del camarero. En ambos casos, el backend gestiona el trabajo de impresión completamente y lo enruta al Print Agent automáticamente. El personal autorizado también puede iniciar una reimpresión desde el panel de administración si la impresión original se perdió o salió defectuosa.

¿Cómo instalo el Print Agent?

La instalación tarda unos cinco minutos en cualquier PC moderno con Windows. El PC debe permanecer encendido durante el horario de servicio del restaurante, ya que el Print Agent se ejecuta como un servicio de Windows en segundo plano.

1. Descargar: Obtén el instalador más reciente del Print Agent desde tu panel de administración o contacta con el soporte.
2. Instalar: Ejecuta el instalador en un PC con Windows que permanecerá encendido durante el horario de servicio.
3. Configurar: Abre config.json e introduce la URL base de la API, el ID del restaurante y la clave secreta del agente (proporcionada por tu administrador).
4. Conectar la impresora: Conecta tu impresora térmica por USB o conéctala a la misma red que el PC.
5. Iniciar el servicio: Ejecuta el Print Agent — se conecta a PrintHub automáticamente y muestra un indicador de estado verde.
6. Impresión de prueba: Procesa un pago de prueba desde el panel del cajero y verifica que el recibo se imprime correctamente.

Requisitos del sistema

El Print Agent tiene requisitos mínimos de hardware pero depende de un sistema operativo y entorno de ejecución compatibles:

• Sistema operativo: Windows 10 (versión 1909 o posterior) o Windows 11. El Print Agent es un servicio exclusivo de Windows y no funciona en macOS ni Linux.
• Entorno de ejecución: Debe estar instalado .NET 8 Runtime. El instalador te pedirá que lo descargues si no está presente — es gratuito de Microsoft.
• Conexión a internet: Se requiere una conexión a internet estable para comunicarse con la nube de RestaurantManage. El agente se reconecta automáticamente después de interrupciones breves.
• Acceso a la red: El PC debe poder acceder a la impresora — ya sea a través de cable USB o en el mismo segmento de red local.
• Procesador y RAM: Cualquier procesador moderno con al menos 512 MB de RAM disponible es suficiente. El agente es muy ligero.

Ejecutar como servicio de Windows

Para uso en producción, el Print Agent debe instalarse como servicio de Windows para que inicie automáticamente cuando el PC arranque — incluso antes de que inicie sesión un usuario. Para registrarlo como servicio, haz clic derecho en install-service.bat y elige Ejecutar como administrador. Esto registra el agente con el Administrador de control de servicios de Windows bajo el nombre RestaurantPrintAgent. Después de la instalación, puedes administrarlo desde el panel de Servicios (services.msc) o desde la línea de comandos usando sc start RestaurantPrintAgent y sc stop RestaurantPrintAgent. Para eliminar el servicio, ejecuta uninstall-service.bat como administrador.

Encontrar tu ID de restaurante y clave secreta

El ID del restaurante es el identificador único de tu restaurante en el sistema RestaurantManage. Puedes encontrarlo en el panel de administración en Configuración → Información del restaurante. La Clave secreta del agente es una credencial separada que autentica el Print Agent con el endpoint WebSocket de PrintHub — no es la misma que la contraseña de usuario. Para generar o regenerar una clave secreta, ve a Configuración → Print Agent en el panel de administración y haz clic en Generar nueva clave. Copia la clave inmediatamente y pégala en config.json — no se mostrará de nuevo después de navegar. Si pierdes la clave, simplemente genera una nueva; la antigua se invalidará automáticamente.

¿Qué tipos de conexión de impresora son compatibles?

El Print Agent admite tres métodos de conexión con conmutación automática entre ellos. Se admiten impresoras de red, impresoras USB y conexiones Windows Spooler. El agente prueba primero Spooler, luego pasa a USB directo y finalmente intenta recursos compartidos de red UNC.

Impresoras de red (recomendado)

Las impresoras de red son el método de conexión recomendado para la mayoría de los restaurantes. Una impresora térmica conectada a la red tiene su propia dirección IP y acepta datos de impresión sin procesar en el puerto TCP 9100 — el puerto estándar para impresión ESC/POS. Para configurar, conecta la impresora al router o switch con un cable Ethernet, luego usa la página de configuración integrada de la impresora o el menú del panel frontal para asignarle una dirección IP estática (por ejemplo, 192.168.1.100). Introduce esta dirección IP y el puerto 9100 en la configuración del Print Agent. La IP estática es importante — si la impresora recibe una nueva IP del DHCP cada vez que se reinicia, los trabajos de impresión fallarán.

Impresoras USB y Windows Spooler

Las impresoras térmicas USB se conectan directamente al PC con Windows que ejecuta el Print Agent. Después de conectar el cable USB, instala el controlador de Windows del fabricante si es necesario (muchas impresoras ESC/POS modernas usan un controlador genérico incluido en Windows). El Print Agent detectará la impresora a través de Windows Spooler. Si la impresora no aparece en el Spooler, se puede probar el método de direccionamiento USB directo: el agente puede escribir directamente en rutas de dispositivos USB como \\?\USB001 o rutas de puerto paralelo como LPT1.

Orden de conmutación automática

Cuando se recibe un trabajo de impresión, el Print Agent prueba los métodos de conexión en este orden: 1) Windows Spooler — si la impresora está registrada en Windows y es accesible a través del Spooler, se usa este método primero. 2) USB directo — si Spooler falla, el agente intenta escribir directamente en rutas de dispositivos USB (USB001, USB002, etc.) y puertos LPT. 3) Recurso compartido de red UNC — como último recurso, el agente intenta acceder a la impresora a través de una ruta de recurso compartido de red de Windows. Si los tres métodos fallan, el error se registra en la carpeta logs/ con detalles.

¿Cómo configuro el Print Agent?

El Print Agent se configura a través de un único archivo config.json ubicado en el directorio de instalación. Todos los ajustes son texto plano y entran en vigor la próxima vez que el servicio se inicia (o se reinicia). No hay interfaz gráfica para la configuración — basta con editar el archivo con cualquier editor de texto.

Explicación del archivo config.json

El archivo de configuración tiene tres campos obligatorios y acepta configuraciones opcionales de impresora:

• ApiBaseUrl: La URL base de tu servidor RestaurantManage, por ejemplo <code>https://restaurantmanage.xyz</code>. No incluyas una barra diagonal al final. El Print Agent usa esta URL para conectarse a PrintHub y comprobar actualizaciones.
• RestaurantId: El identificador único de tu restaurante. Puedes encontrarlo en el panel de administración en Configuración → Información del restaurante.
• AgentSecretKey: La clave secreta generada en el panel de administración en Configuración → Print Agent. Esta clave autentica al agente con el servidor sin necesitar inicio de sesión de usuario. Mantenla confidencial.

Un ejemplo completo de config.json tiene este aspecto: {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "tu-id-de-restaurante", "AgentSecretKey": "tu-clave-secreta"}. Después de editar el archivo, reinicia el servicio Print Agent para que los cambios surtan efecto.

Configuración del nombre e IP de la impresora

Para impresoras de red, necesitas la dirección IP de la impresora. Para encontrarla: la mayoría de las impresoras térmicas imprimen una página de configuración cuando se mantiene presionado el botón de alimentación durante el encendido — la dirección IP aparece allí. Alternativamente, revisa la lista de clientes DHCP de tu router para encontrar el nombre de host de la impresora. Una vez que tengas la IP, asígnala como dirección estática en la configuración de red de la impresora para que nunca cambie. Para impresoras Windows Spooler, el nombre de la impresora debe coincidir exactamente con cómo aparece en Configuración de Windows → Impresoras y escáneres. Los nombres de impresora distinguen entre mayúsculas y minúsculas.

Archivos de registro y diagnóstico

El Print Agent escribe registros detallados en la subcarpeta logs/ dentro del directorio de instalación. Los archivos de registro se nombran por fecha (por ejemplo, log-2026-04-06.txt) y rotan diariamente. Cada entrada de registro incluye una marca de tiempo, nivel de gravedad (INFO, ADVERTENCIA, ERROR) y una descripción de lo que ocurrió. Si estás resolviendo un fallo de impresión, revisa el archivo de registro de la fecha del problema — el mensaje de error exacto indicará si el problema está relacionado con la red, la autenticación o la impresora.

¿Cómo funciona la actualización automática?

El Print Agent comprueba actualizaciones aproximadamente cada 2,5 horas llamando al endpoint de actualización en el servidor de RestaurantManage. Si hay una nueva versión disponible, descarga el paquete de actualización como archivo ZIP a una carpeta de actualizaciones pendientes, ejecuta el script de instalación y reinicia el servicio automáticamente. Esto significa que tu restaurante siempre ejecuta la última versión sin intervención manual. Las comprobaciones de actualización incluyen un desfase temporal por restaurante para evitar que todos los agentes se actualicen simultáneamente.

Solución de problemas comunes

La mayoría de los problemas de impresión pertenecen a una de tres categorías: problemas de conexión, problemas de hardware de la impresora o errores de configuración. Los archivos de registro en la carpeta logs/ son el mejor punto de partida para diagnosticar cualquier problema.

Errores de conexión y autenticación

• El agente no se conecta al servidor: Verifica que ApiBaseUrl en config.json sea correcto y accesible desde el PC. Abre un navegador en el mismo PC y navega a la URL de la API — deberías ver una respuesta. Comprueba que el PC tiene una conexión a internet activa.
• Fallo de autenticación (error 401 en los registros): AgentSecretKey es incorrecto o ha sido regenerado. Inicia sesión en el panel de administración, genera una nueva clave en Configuración → Print Agent, actualiza config.json y reinicia el servicio.
• La conexión se cae y se reconecta repetidamente: Esto generalmente indica un problema de inestabilidad de red. Cambia de Wi-Fi a Ethernet por cable. Comprueba si un cortafuegos o antivirus está bloqueando las conexiones WebSocket salientes (el agente usa HTTPS puerto 443).
• El agente se conecta pero no recibe trabajos de impresión: Confirma que el ID del restaurante en config.json coincide exactamente con el del panel de administración (distingue entre mayúsculas y minúsculas). Verifica también que el Print Agent está habilitado en Configuración → Print Agent.

Problemas de calidad de impresión y codificación

• Caracteres o símbolos ilegibles en el recibo: Tu impresora térmica puede no soportar completamente el conjunto de comandos ESC/POS usado por RestaurantManage. Consulta la documentación de la impresora para verificar la compatibilidad. La mayoría de las impresoras térmicas de 58 mm y 80 mm fabricadas después de 2015 son compatibles.
• El recibo se imprime pero el texto está cortado: La configuración del ancho del papel puede ser incorrecta. RestaurantManage formatea los recibos para papel de 80 mm por defecto. Si usas una impresora de 58 mm, contacta con el soporte para habilitar el modo de papel estrecho.
• El recibo se imprime en blanco o solo con contenido parcial: Esto puede indicar un rollo de papel bajo o un cabezal de impresión obstruido. Reemplaza el papel y limpia el cabezal de impresión con un paño seco. Si el problema persiste, prueba la impresora directamente desde Windows para aislar si el problema es de hardware o software.
• Caracteres especiales o texto árabe/RTL no se imprimen correctamente: Asegúrate de que el conjunto de caracteres de tu impresora esté configurado en UTF-8 o la página de códigos adecuada para tu idioma. Este ajuste suele ser accesible en el menú de configuración de la impresora.

Fallos de inicio del servicio

• El agente no inicia como servicio de Windows: Debes ejecutar install-service.bat como Administrador (clic derecho → Ejecutar como administrador). Sin permisos elevados, el servicio no puede registrarse con el Administrador de control de servicios de Windows.
• El servicio inicia y luego se detiene inmediatamente: Comprueba el Visor de eventos de Windows (eventvwr.msc) en Registros de Windows → Aplicación para mensajes de error de RestaurantPrintAgent. Revisa también la carpeta logs/ para errores de inicio. Las causas comunes son config.json faltante o malformado, runtime .NET 8 faltante o conflicto de puertos.
• Falta el runtime .NET: Descarga e instala .NET 8 Runtime desde https://dotnet.microsoft.com. Después de la instalación, reinicia el servicio Print Agent.
• El cortafuegos bloquea al agente: Windows Defender u otro cortafuegos puede estar bloqueando la conexión saliente del agente. Añade una excepción para el ejecutable del Print Agent en la configuración del cortafuegos.

Guías relacionadas

• Panel del cajero: Cómo procesar pagos que activan la impresión de recibos
• Pantalla de cocina: Cómo se integra la impresión de tickets de cocina con el flujo de pedidos
• Primeros pasos: Guía de configuración completa desde el registro hasta el primer pedido