ESC/POS: diseñar tickets térmicos fiables, compatibles y recuperables

Sistema de punto de venta con tableta e impresora portátil de recibos
Fotografía de SumUp · Unsplash (licencia gratuita). Contexto real de impresión de tickets; no representa una Epson específica. · Ver imagen original

Una impresora de tickets parece un periférico sencillo hasta que aparece una ñ convertida en otro símbolo, el logo sale cortado, el cajón se abre dos veces o un reintento genera dos recibos. La dificultad de ESC/POS no es aprender tres bytes: es controlar la frontera entre documento, encoder, transporte y estado físico del dispositivo.

En este artículo analizamos la familia de comandos ESC/POS con referencia a la documentación oficial de Epson. El foco es diseño de drivers y recuperación operacional para POS. No se presupone que todos los equipos de 58 u 80 mm soporten las mismas funciones. El laboratorio propuesto es conceptual y los casos de hardware están pendientes de ejecución. La compatibilidad de una secuencia depende de fabricante, modelo, firmware, interfaz y configuración.

Flujo de impresión ESC/POS: maquetar ticket, codificar comandos, transmitir e imprimir.
Diagrama editorial original. El resultado de impresión puede ser ambiguo ante fallos de comunicación.

ESC/POS no equivale a una única especificación universal

ESC/POS es una familia de comandos usada por impresoras de recibos. Una combinación de bytes puede expresar «alinear al centro», «imprimir un símbolo QR» o «consultar el estado». Pero incluso cuando dos dispositivos dicen ser compatibles, sus conjuntos de comandos, parámetros, tablas de caracteres, modos de gráfico y estados pueden diferir.

La matriz de impresoras compatibles de Epson muestra qué comandos aplica cada modelo. Fabricantes como Star y Bixolon también publican especificaciones propias. Por tanto, no existe base suficiente para la afirmación «ESC @, GS V y todos los códigos QR funcionan en cualquier impresora térmica». La capacidad debe consultarse o probarse para el modelo concreto.

CapaPregunta de compatibilidadEjemplo
Comando¿Existe en este modelo y firmware?GS V para corte, GS ( k para QR
Parámetros¿Qué rangos y variantes acepta?Tamaño de módulo QR, tipo de corte
Codificación¿Qué página se selecciona con cada n?ESC t n y CP858/CP850
Transporte¿Hay canal de lectura de status?USB, TCP raw, spooler/driver de OS
Estado físico¿Cortó, imprimió y tiene papel?Sensores, cutter, buffer de impresión

Separar estas capas permite versionar un perfil de dispositivo y evitar una clase con cientos de excepciones condicionales dispersas.

Ilustración conceptual de protocolo de impresoras de tickets ESC/POS: codificación, transporte y salida.
Ilustración conceptual original: síntesis visual del tema del artículo, no captura ni prueba ejecutada.

El pipeline del ticket: de datos a bytes

Un ticket suele comenzar como una estructura de dominio: identificador, líneas de venta, cantidades, impuestos, moneda y un pie. En esa etapa no deberían existir comandos ESC/POS ni cortes manuales de strings según el número fijo de caracteres. Después vienen layout, encoding y transporte.

Venta confirmada / número de documento
       ↓
Modelo de ticket (datos tipados, importes y orden de líneas)
       ↓
Layout (ancho imprimible, columnas, estilos y desbordes)
       ↓
Encoder por perfil (code page, QR, imagen, comandos soportados)
       ↓
Payload de bytes inmutable + checksum/hash
       ↓
Transport adapter (USB, TCP, spooler) + observación de estado
       ↓
Job ledger (resultado confirmado, fallido o ambiguo)

Esto es importante: un write() exitoso sobre un socket puede significar que el sistema operativo aceptó bytes, no que la impresora los haya convertido en papel. Tampoco equivale a un commit de transacción en la aplicación que creó el pedido. Conservar un identificador único de trabajo es más útil que registrar solamente «print success».

Caracteres españoles: ESC t no activa UTF-8

El código original de este artículo mostraba ESC t 16 seguido de text.encode('utf-8'). Esa combinación era conceptualmente incorrecta: ESC t n selecciona una tabla de caracteres, mientras que UTF-8 es una codificación multibyte. Un valor n asociado a CP858 en determinados modelos no convierte automáticamente el parser del dispositivo en un decodificador UTF-8.

La referencia ESC t de Epson especifica que el rango de n y la tabla correspondiente dependen del modelo. Incluso una página de códigos disponible puede no estar seleccionada con el mismo identificador en equipos de fabricantes distintos.

Supongamos que el perfil del modelo confirma una tabla compatible con cp858 y conoce su valor n. Entonces el encoder podría ser:

from dataclasses import dataclass

ESC = b"\x1b"
GS = b"\x1d"

@dataclass(frozen=True)
class PrinterProfile:
    model: str
    codepage_number: int   # Valor verificado en documentación del equipo.
    python_codec: str      # Ej.: "cp858", NO implica soporte UTF-8.
    supports_cut: bool
    supports_qr: bool


def select_codepage_and_encode(profile: PrinterProfile, text: str) -> bytes:
    if not 0 <= profile.codepage_number <= 255:
        raise ValueError("Número de tabla ESC t fuera de rango")
    encoded = text.encode(profile.python_codec, errors="strict")
    return ESC + b"t" + bytes([profile.codepage_number]) + encoded

El punto decisivo no es adivinar codepage_number=16. Es verificar la correspondencia entre n y python_codec para un modelo/firmware y probar caracteres como á é í ó ú ñ Ñ €. errors="strict" permite detectar letras no representables en lugar de corromper silenciosamente el recibo. Para scripts y caracteres no soportados, algunas arquitecturas convierten la región a una imagen, siempre que el perfil de gráficos lo permita; esto aumenta el tamaño del payload y exige medir legibilidad.

También hay que tratar el ancho físico con cuidado: una letra acentuada no es necesariamente un byte en UTF-8, ni una celda monoespaciada equivale siempre a un ancho en milímetros. El formato depende de fuente, modo doble ancho, resolución y papel imprimible. Un layout robusto calcula medidas con los parámetros reales de la impresora.

QR: función definida, compatibilidad condicionada

Epson utiliza funciones de la familia GS ( k para configurar, almacenar y renderizar QR. Los identificadores exactos de funciones son importantes: seleccionar el modelo (165), tamaño (167), corrección de errores (169), almacenar bytes (180) e imprimir (181). No hay una única «secuencia universal de QR» que se pueda enviar sin consultar el modelo.

El siguiente encoder ilustra el formato para dispositivos Epson que hayan confirmado soporte de esas funciones. No controla USB/TCP ni verifica el resultado físico.

# Fragmento autocontenido para probar el formato de las funciones QR.
GS = b"\x1d"


def gs_k(body: bytes) -> bytes:
    n = len(body)
    if not 1 <= n <= 65535:
        raise ValueError("Longitud GS ( k fuera del rango de 16 bits")
    return GS + b"(k" + bytes([n & 0xFF, n >> 8]) + body


def encode_qr(data: bytes, *, module_size: int = 4) -> bytes:
    if not data:
        raise ValueError("El QR no puede estar vacío")
    if len(data) + 3 > 65535:
        raise ValueError("Contenido demasiado grande para este framing")
    if not 1 <= module_size <= 16:
        raise ValueError("Tamaño de módulo fuera del rango de este ejemplo")

    return b"".join((
        gs_k(b"\x31\x41\x32\x00"),                # Función 165: modelo 2
        gs_k(b"\x31\x43" + bytes([module_size])), # Función 167: tamaño
        gs_k(b"\x31\x45\x31"),                # Función 169: corrección M
        gs_k(b"\x31\x50\x30" + data),         # Función 180: datos
        gs_k(b"\x31\x51\x30"),                # Función 181: imprimir
    ))

Las validaciones de longitud, tamaño y modelo de QR deben ajustarse al rango del equipo; los valores mostrados no garantizan que todos los modelos admitan 16 como tamaño de módulo. En un driver real, supports_qr y los límites forman parte del perfil. El contenido binario debe definirse según el contrato del documento: un identificador, una URL o un QR fiscal pueden tener codificaciones y requisitos propios.

Antes de imprimir un QR en producción, una prueba de papel debería comprobar que un lector independiente recupera exactamente el payload, incluso tras redimensionar, imprimir en condiciones térmicas reales y acercarse a los límites de capacidad. Que el comando no produzca un error de escritura no demuestra que el símbolo sea legible.

Logotipos, imágenes y el problema de lo «obsoleto»

La impresión de gráficos admite diferentes familias de comandos: bitmaps raster, gráficos almacenados en memoria del dispositivo, variantes NV y comandos más recientes. En la lista de Epson, GS v 0 aparece marcado como obsolete. Esto no significa que ningún dispositivo actual lo acepte; significa que no debería presentarse como único método recomendado para desarrollos nuevos sin contrastar la matriz de comandos.

Una ruta de imagen debe definir, para cada modelo: ancho máximo en puntos, conversión a monocromo/halftone, dithering, límites del buffer, rotación, recorte y velocidad. Los logos guardados en memoria NV tienen requisitos de aprovisionamiento y actualización distintos de imágenes enviadas en cada ticket. Las capturas del navegador no son equivalentes a la salida binaria; hay que probar ambos artefactos por separado.

Diseñar el driver como render_logo(bitmap, capabilities) permite elegir la estrategia y registrar una degradación aceptable (por ejemplo, imprimir texto alternativo si faltan gráficos), sin acoplar la lógica del POS a un opcode particular.

Corte y estado: no confundir comandos con confirmaciones

GS V selecciona modos de corte en modelos con cutter y compatibilidad para el parámetro elegido. El comando no certifica por sí solo que el corte haya concluido. Similarmente, DLE EOT puede solicitar determinados estados en tiempo real, mientras que GS a habilita Automatic Status Back (ASB). La disponibilidad, semántica y recepción de esas señales dependen de modelo e interfaz.

El problema aparece cuando se mezclan canales unidireccionales con protocolos de estado bidireccionales. Una cola de impresión del sistema operativo puede aceptar el trabajo y no transmitir respuestas de la misma forma que una conexión TCP raw. En otros casos hay notificaciones ASB asíncronas que necesitan un parser separado del stream de trabajo. No se debe asumir que una llamada a status certifica la emisión completa de un recibo concreto. La guía Epson de comandos distingue explícitamente esas familias.

Una tabla de compatibilidad, fechada por firmware, debería identificar si el equipo ofrece:

CapacidadDecisión de driverPrueba física
ESC tPágina y número n configuradosImpresión y lectura de caracteres ES
QR GS ( kFunciones y límites permitidosEscaneo de contenido exacto
GráficosModo raster/NV/graphics seleccionadoLogo completo, márgenes y contraste
GS VCorte activado solo si está soportadoCorte real en modo elegido
DLE EOT, ASBParser de estado por interfazPapel retirado/tapa abierta/reconexión según fabricante

Los tests deben identificar modelo y firmware concretos, no solo «impresora ESC/POS de 80 mm».

El fallo más difícil: el resultado ambiguo de un envío

Pensemos en el siguiente recorrido: la aplicación acepta el pago, genera el recibo y comienza a escribir bytes por TCP. La conexión se corta después del envío. El cliente sabe que ocurrió un error de transporte, pero no sabe si la impresora recibió todo, una parte o si llegó a imprimir. Reintentar automáticamente puede producir un ticket duplicado; no reintentar puede dejar al operador sin papel.

No existe una transacción distribuida automática entre sale.commit() y el cabezal térmico. Por eso conviene modelar el trabajo como estado explícito:

EstadoQué se sabeSiguiente acción
QUEUEDPayload fijado, aún no enviadoEnviar una vez por política
SENDINGIntento iniciadoRegistrar intento y transporte
ACK_TRANSPORTEl canal/spooler aceptó datos, no prueba impresiónEsperar evidencia adicional si existe
CONFIRMEDEvidencia de confirmación definida por el perfil/operaciónCerrar job, conservar auditoría
FAILEDFallo confirmado antes de entregaReintentar con idempotencia controlada
AMBIGUOUSPuede haber existido entrega/impresión parcialReconciliar con operador o señal fiable; evitar duplicado silencioso

Esta máquina de estados es una propuesta de diseño, no un feature nativo de ESC/POS. En la práctica, CONFIRMED debe definirse con precisión: puede indicar una observación operacional externa y no un acknowledgement transaccional de la impresora.

Un ledger útil guarda job_id, document_number, modelo, transporte, payload_sha256, timestamps, número de intentos, error de transporte y evidencia de resolución. No se debería incluir en los logs el contenido íntegro de tickets con datos personales. El número visible de documento ayuda a distinguir una reimpresión autorizada de un duplicado accidental.

Reintentos: idempotencia de API no implica exactly-once en papel

Una API puede rechazar dos envíos del mismo job_id; una cola puede deduplicar solicitudes; un worker puede usar un lock para evitar concurrencia. Son controles valiosos, pero no revierten la incertidumbre después de que una impresora recibió bytes sin una confirmación vinculada inequívocamente a ese trabajo. Si se decide reimprimir, la UI debería mostrar que se trata de una reimpresión y registrar quién la autorizó, de acuerdo con las reglas del negocio y fiscales aplicables.

La recuperación requiere tratar por separado estado de venta, generación de bytes, estado del trabajo y estado físico. Resolver el fallo imprimiendo de nuevo sin verificar los dos últimos puede multiplicar el problema.

Testabilidad: separar encoder y transporte

Un driver diseñado como función pura permite probar bytes sin hardware. Podemos comprobar la codificación, la cabecera QR y los límites de longitud antes de probar impresoras reales:

# Extracto de tests del encoder (suponiendo importados los helpers anteriores).

def test_cp858_espaniol():
    profile = PrinterProfile("modelo-verificado", 16, "cp858", True, True)
    payload = select_codepage_and_encode(profile, "Niño €")
    assert payload[:3] == b"\x1b\x74\x10"
    assert payload[3:] == "Niño €".encode("cp858")


def test_qr_framing():
    payload = encode_qr(b"pedido-001", module_size=4)
    assert payload.startswith(b"\x1d\x28\x6b\x04\x00\x31\x41\x32\x00")
    assert b"\x31\x50\x30pedido-001" in payload

Atención: el valor 16 aparece aquí para verificar el framing del encoder, no para declarar que todas las impresoras identifican CP858 con ese número. El test de compatibilidad real necesita el perfil documentado y una impresión física.

El transporte se prueba con un fake que simula escritura parcial, timeout y reconexión. Esto solo valida nuestra política de software; el resultado físico sigue requiriendo hardware. No generamos aquí una secuencia de status fija para cualquier modelo porque su interpretación y mecanismo de recepción varían por interfaz.

Protocolo de aceptación para impresoras reales

Estado: propuesto, NO EJECUTADO en esta revisión. El entorno se especifica con fabricante/modelo/firmware, interfaz, versión del driver, ancho de papel, DPI y configuración de red. Una matriz mínima:

  1. Impresión de ASCII, tildes, ñ, Ñ, € y caracteres no representables; registrar sustitución o error esperado.
  2. Ticket de 58/80 mm con tablas, importes, fuentes y márgenes; medir desbordes visuales sin inferirlos solo del string.
  3. QR con distintos tamaños de módulo, un payload conocido y lectura de retorno.
  4. Logo por comandos gráficos soportados, dithering, alineación y persistencia de NV cuando exista.
  5. Corte: completo/parcial únicamente si el modelo lo permite, con comprobación de fin físico.
  6. Estado: papel vacío, tapa abierta, desconexión y reconexión; indicar qué se observa mediante el transporte real.
  7. Pérdida de conexión antes/durante/después del envío: registrar cuándo puede marcarse FAILED y cuándo debe quedar AMBIGUOUS.
  8. Envíos largos, jobs consecutivos y reintentos autorizados; comprobar que el ledger corresponde a los documentos físicos.

Las pruebas de estado, hardware y desconexión quedan pendientes de impresora disponible. No se presentan resultados ni porcentajes inventados. Un encoder que supera tests unitarios todavía puede fallar ante buffer, firmware y mecanismos de spooler reales.

Integración con un POS, Odoo y Flutter

La aplicación puede estar escrita en Python, Dart, JavaScript o cualquier otro lenguaje. El diseño útil no consiste en abrir un socket dentro de la vista de facturación. Conviene crear un servicio de impresión que acepte un ticket tipado, produzca un payload inmutable y entregue el resultado a una cola con estados recuperables. El frontend necesita mostrar QUEUED, AMBIGUOUS y CONFIRMED según evidencia, sin identificar automáticamente «HTTP 200 del servicio» con «papel impreso».

En Odoo 18, el addon que define el flujo debería mantener las extensiones en su propio módulo, respetar ACL/record rules y no modificar vistas ni modelos core. Esa frontera de extensibilidad se desarrolla en Odoo 18: herencia y seguridad.

Para Flutter, si existe un SDK propietario de impresión, quizás convenga un plugin mediante Platform Channels o Pigeon; un encoder binario puro podría permanecer en Dart. El acceso nativo solo se justifica por API, fiabilidad o rendimiento medidos. En los dispositivos con spooler de sistema, la confirmación debe seguir distinguiendo lo que informa el SDK de lo que ocurre en el mecanismo físico.

Conclusión

El error más costoso en ESC/POS no es memorizar mal un opcode: es suponer que todos los modelos lo aceptan, que UTF-8 se activa con ESC t o que un write() completado certifica un ticket físico. Un driver fiable mantiene un perfil de capacidades por modelo, codifica de manera comprobable, separa transporte de resultado e incorpora un estado de envío ambiguo para recuperarse sin duplicados silenciosos.

Lo que debe probarse primero es el encoder; lo que debe comprobarse después, en hardware, es todo lo que el encoder no puede observar.

Referencias primarias