FactuTPV Agent: la única forma de usar cualquier impresora térmica con un TPV cloud — sin excepción

Si vendes con TPV cloud en 2026, la impresión de tickets es uno de los pocos puntos donde casi todo el mercado falla. El navegador es muy potente para casi todo (vender, cobrar, facturar, emitir VeriFactu) pero el último kilómetro — los bytes ESC/POS saliendo por un puerto USB o un socket TCP 9100 — sigue siendo territorio de drivers nativos. Y el navegador tiene limitaciones duras por seguridad:

• WebUSB no funciona en iPad/iOS ni en Safari. Y en Windows obliga a sustituir el driver del fabricante por WinUSB (con Zadig) — un paso técnico que espanta al 90% de los clientes no técnicos.
• Web Bluetooth solo está en Chrome/Edge (Android y escritorio), no en iOS ni Safari, y el emparejamiento hay que hacerlo en cada dispositivo por separado.
• Web Serial exige Chrome/Edge en Windows/Linux/ChromeOS y funciona mal con las impresoras cuyo driver de Windows bloquea el puerto COM virtual.
• LAN directo con Chrome 142+ (Local Network Access API) funciona solo con Epson ePOS y Star WebPRNT — que son el 10% del mercado. El otro 90% (Xprinter, Unykach, HPRT, Rongta, HOIN, Bixolon, MUNBYN…) usa ESC/POS raw sobre TCP 9100, que Chrome bloquea por política de seguridad.
• Y el backend del TPV en la nube no puede hablar con la IP 192.168.x.y del cliente porque está detrás del NAT del router.

El resultado: la mayoría de TPV cloud españoles (Holded, Alegra, Contabilizate, muchos otros) no imprimen tickets térmicos más allá del diálogo PDF del navegador. Otros (SumUp, iZettle) te obligan a comprar su hardware propietario. Los intentos serios de middleware universal son de pago por impresora: PrintNode cobra ~$9/mes por cada impresora, QZ Tray tiene licencia comercial. Ninguna de esas soluciones está integrada de serie con un TPV gratuito en España.

FactuTPV resuelve este problema de raíz con el Agente FactuTPV: un pequeño servicio gratuito que actúa como puente universal entre el navegador y cualquier impresora térmica, en cualquier sistema operativo, sin licencias ni comisiones.

El Agente FactuTPV es un binario nativo (~12 MB) escrito en Go, con arquitectura multi-plataforma y build cross-compile CGO-free por defecto:

• Windows: MSI firmado con certificado EV Code Signing (Sectigo) para que SmartScreen lo considere editor de confianza desde el primer clic. Se registra como Servicio Windows (arranca con el sistema, corre como SYSTEM).
• macOS: PKG firmado y notarizado por Apple (pasa por Gatekeeper sin warnings). Se registra como LaunchDaemon del sistema (arranque al login, corre como root).
• Linux: paquete DEB/RPM con servicio systemd de usuario o sistema. Instalación estándar con dpkg -i o dnf install.

Al arrancar, el agente:

1. Escucha en localhost:17777 con un panel de administración web (en HTTP para el propio equipo) y el endpoint de emparejamiento.
2. Si está vinculado a una cuenta FactuTPV, abre un WebSocket inverso (reverse-WS) saliente hacia wss://api.factutpv.es/ws/agent con JWT de dispositivo. Por ahí le llegan los trabajos de impresión desde cualquier device del tenant.
3. Lista impresoras disponibles al backend y actualiza su lista en tiempo real cuando se editan en la web.
4. Al recibir un trabajo, dispara por el transporte correspondiente: TCP 9100 raw, USB gousb/libusb, Bluetooth RFCOMM, Serie, Windows Spooler o CUPS.

Capacidades avanzadas que cubren todos los casos reales:

• Port fallback automático: si el puerto configurado falla, prueba 9100 → 4000 → 80 sin intervención.
• MAC rescue: si la IP cambia por DHCP, busca la impresora por su MAC address en la LAN y actualiza el destino.
• Auto-route L3: si el host tiene IP en una subred sin ruta directa, añade la ruta automáticamente al arrancar.
• Cola persistente con retroceso exponencial: si la impresora está ocupada, guarda el trabajo en bbolt local y lo reintenta con backoff. Sobrevive reinicios.
• Descubrimiento multi-transport: escanea 6 puertos ESC/POS × todas las IPs de la LAN + mDNS + USB + Bluetooth en paralelo. Encuentra cualquier impresora del local en 5-15 segundos.

Esta es la ventaja que convence a cualquier hostelero en cuanto la prueba:

Una sola instalación del Agente en UN ordenador del local (Mac mini, PC Windows de caja, Raspberry Pi Linux — lo que tengas encendido permanentemente) permite que cualquier número de dispositivos del tenant impriman en esa misma impresora: iPads de camareros, tablets Android en caja, móviles de sala, PCs de oficina. Todos comparten la impresora a través del agente.

No hace falta nada por dispositivo. El iPad abre FactuTPV en Safari o Chrome, vende un ticket, y sale impreso en la impresora térmica de la barra. Cero configuración en el iPad, cero hardware propietario, cero Apple AirPrint (que no soporta cajón portamonedas ni corte automático ESC/POS).

El flujo técnico:

1. iPad hace una venta en FactuTPV.
2. El backend renderiza el ESC/POS del ticket.
3. El backend envía los bytes al agente del local por el reverse-WS abierto.
4. El agente dispara el TCP 9100 (o USB, o lo que toque) a la impresora física.
5. Ticket impreso en <2 segundos.

Este escenario — crítico para cualquier restaurante con varios camareros o cualquier retail con varios puntos de cobro — no está disponible en ningún otro TPV cloud español sin hardware propietario o middleware de pago.

Los dos middleware universales comparables en el mundo son PrintNode (comercial, $9/mes por impresora) y QZ Tray (licencia comercial de pago, Java). Ambos son productos sólidos pero ambos cobran por cada impresora.

Traducido a números: un restaurante con 3 impresoras (caja, cocina, barra) pagaría con PrintNode 27 $/mes × 12 meses = 324 $/año, solo por el middleware. Con QZ Tray, ~75 $ de alta × 3 = 225 $ + mantenimiento. Con FactuTPV, 0 € extra — el agente va incluido en cualquier plan, incluido el gratuito.

De instalador a impresora imprimiendo: < 5 minutos.

1. Descarga e instala desde github.com/ulisesbaena/factutpv-agent-releases. El MSI/PKG/DEB se ejecuta automáticamente al arrancar el sistema como servicio.
2. Tras instalar, el agente abre http://localhost:17777/admin en tu navegador con un código de 6 dígitos en pantalla grande.
3. En FactuTPV → Ajustes → Impresoras → Ver agentes → Vincular nuevo agente. Pega el código, pon un nombre ("PC barra", "Mac oficina"). El agente queda vinculado a tu cuenta.

Desde este momento, en Ajustes → Impresoras → Añadir impresora → tipo Agente, puedes pulsar Descubrir impresoras y el agente escaneará el local. Selecciona la que quieras y guarda. Prueba a imprimir. Listo.

Si alguna vez cambias de red, enchufas la impresora a otro router, o el DHCP cambia la IP — el agente se adapta solo. Si borras el agente desde la web, el agente local detecta que su JWT ya no sirve y se auto-limpia en 15 minutos (o con un clic en su panel local).

La decisión de construir un agente nativo propio no la tomamos a la ligera. Evaluamos las alternativas durante meses:

• Solo WebUSB/WebBluetooth/LNA: descartado porque iPad no funciona, Windows requiere Zadig, y el 90% de impresoras chinas (Xprinter, Unykach, HPRT…) solo soportan TCP 9100 raw que Chrome bloquea por seguridad.
• PrintNode o QZ Tray licenciado: descartado porque tendríamos que trasladar el coste ($9/impresora/mes) al cliente. Para un restaurante con 3 impresoras son 324 $/año solo por imprimir — rompe el diferencial de precio de FactuTPV.
• Tunnel desde backend al cliente (Cloudflare Tunnel, ngrok): descartado por coste operativo y complejidad — requeriría un túnel por tenant, gestión de credenciales, y limitaría la escalabilidad.
• Requerir hardware propietario: descartado porque rompería el modelo de FactuTPV (cloud puro sin hardware). Queremos que cualquier cliente use la impresora que ya tiene comprada.

La conclusión: construir un agente propio, gratuito, open-source-releases, firmado digitalmente, con la misma arquitectura reverse-WS que usan los runners de GitHub Actions. Código en Go para aguantar años con mínimo mantenimiento. Patrón probado en la industria, adaptado al caso del TPV.

El resultado es un producto que ningún competidor español tiene: un TPV cloud con impresión térmica universal gratis, con cobertura multi-dispositivo y compatibilidad con cualquier marca/modelo del mercado. Sin letra pequeña.