● HTTPS ● HTTP

Referencia del SDK de impresión en navegador: printAgent.js

Imprime en impresoras térmicas ZPL, ESC/POS y TSPL directo desde cualquier página web, sin plugins ni backend propio, con la librería printAgent.js de Text2 Barcode.

Introducción

printAgent.js es la librería de navegador que permite imprimir a impresoras térmicas directamente desde tu app web, sin plugins ni backend propio.

Carga la librería → llama a los métodos del objeto global PrintAgent → la librería se comunica con el agente local de Text2 Barcode, que gestiona la impresora física.

Requisito: Text2 Barcode debe estar instalado y corriendo en el equipo donde se imprime. La librería se conecta a él en localhost:9101 (HTTPS) o localhost:9100 (HTTP), con fallback automático si el puerto seguro no responde.
Nombre anterior: esta librería se llamaba t2bprinter.js y su objeto global T2bPrinter (con los errores T2bHttpError, T2bConnectionError y T2bBlockedResponseError). Ese archivo sigue disponible, sin cambios, en https://text2barcode.com/lib/t2bprinter.js para las integraciones existentes. En código nuevo usa printAgent.js con PrintAgent, PrintAgentHttpError, PrintAgentConnectionError y PrintAgentBlockedResponseError.

Requisitos previos

  1. Instalar Text2 Barcode en el equipo de impresión.
  2. Incluir la librería en tu página:
    https://text2barcode.com/lib/printAgent.js
  3. Una impresora térmica compatible (Zebra GK420, Bixolon SRP-330II, TSC, etc.).

Inicio rápido

Todos los métodos son async/await. Flujo típico en 3 pasos:

1 — Incluir SDK
<script src="https://text2barcode.com/lib/printAgent.js"></script>
2 — Buscar impresora
const printer = await PrintAgent.find(it => it.name.includes("Zebra"));
3 — Enviar trabajo
if (printer) {
  const result = await PrintAgent.write(printer, `^XA^FO50,50^A0N,50^FDHello^FS^XZ`);
  console.log(result); // { result: true, message: "..." }
}

Configuración del objeto

Propiedades del objeto global PrintAgent. Todas tienen valores funcionales por defecto.

PropiedadTipoDefaultDescripción
enableDebug boolean false Activa logs en consola (console.debug / console.warn). Útil para diagnosticar conectividad en desarrollo.
servers { id, name, securePort, defaultPort }[] Text2 Barcode (9100/9101) y agentes compatibles Agentes de impresión a probar, en orden de prioridad. Antes de cada solicitud la librería comprueba cuál está corriendo y trabaja con el primero que responda. Puedes reordenarlo o recortarlo (por ejemplo, para trabajar solo con Text2 Barcode).
Detección automática: No necesitas configurarlo. Cada agente tiene su propio par de puertos, así que pueden estar abiertos a la vez.
useSecureConnection boolean true Protocolo preferido: HTTPS (true) o HTTP (false). Se usa solo si la app elegida responde en él; si no, la librería usa el otro puerto de esa misma app.
probeTimeoutMs number 2000 Tiempo máximo, en milisegundos, que se espera a que cada puerto responda al sondeo de disponibilidad (GET /). Un sondeo que expira cuenta como "no disponible". No aplica a las solicitudes en sí (write, convert…): esas nunca se cortan, porque la app pudo haber recibido ya el trabajo.
Permiso de red local: Chrome puede pedirlo en la primera llamada. Sube el valor si ese aviso tarda más en contestarse.
Ejemplo
PrintAgent.enableDebug = true; // activar logs de depuración

Tipos de datos

Los métodos de descubrimiento devuelven objetos de tipo Device:

Tipo Device
type Device = {
  uid:               string;   // identificador único (nombre, IP, MAC o ID de plantilla)
  name:              string;   // nombre visible de la impresora
  deviceType:        "printer" | "template";
  connection:        "driver" | "bluetooth" | "network" | "ttb";
  manufacturer?:     string;   // fabricante (ej: "Zebra Technologies") — solo impresoras driver
  resolution?:       number;   // resolución en DPI (opcional)
  driverConnection?: string;   // nombre del puerto/conexión del driver (opcional)
  queuedJobs?:       number;   // trabajos en cola reportados por el driver (opcional)
  statusText?:       "idle" | "printing" | "paused" | "offline" | "error" | "unknown";
  port?:             number;   // puerto de red (opcional) — solo impresoras de red
}

Valores de deviceType:

ValorDescripción
printerImpresora física detectada en el sistema.
templatePlantilla de impresora configurada en Text2 Barcode (no corresponde a un dispositivo físico conectado).

Valores de statusText (solo impresoras driver):

ValorDescripción
idleSin estado especial reportado por el driver.
printingLa impresora está imprimiendo un trabajo.
pausedLa impresora está pausada.
offlineLa impresora está desconectada o apagada.
errorLa impresora reporta un estado de error (papel, atasco, etc.).
unknownEl driver reportó un estado no reconocido.

Valores de connection:

ValorDescripciónPlataforma
driverImpresora instalada vía driver del SO. Cuando connection === "driver", el campo driverConnection indica el puerto físico del driver (ej: "USB023", "LPT1").Windows, macOS, GNU/Linux
bluetoothConexión BluetoothAndroid, iOS
networkConexión de red (IP / host). El campo port indica el puerto TCP.Todas
ttbConexión a través de Text2 BarcodeTodas

API principal

status() StatusResult

PrintAgent.status()→ Promise<StatusResult>
Verifica los puertos de Text2 Barcode (9101 HTTPS y 9100 HTTP) en paralelo. Útil para diagnóstico: saber exactamente cuál puerto está disponible.

Sin parámetros. Siempre resuelve, nunca rechaza.

Uso
const s = await PrintAgent.status();

console.log("Disponible:", s.isAvailable);         // true si alguna app responde
console.log("App activa:", s.server?.profile.name); // null si ninguna responde
console.log("9101 HTTPS:", s.port9101.available);  // puertos de Text2 Barcode
console.log("9100 HTTP:",  s.port9100.available);
console.log("Puerto activo:", s.active);           // null si ninguna responde
Respuesta
{
  "servers": [
    { "profile": { "id": "text2barcode", "name": "Text2 Barcode", "securePort": 9101, "defaultPort": 9100 },
      "secure":   { "available": true,  "protocol": "https", "port": 9101, "info": { ... } },
      "insecure": { "available": false, "protocol": "http",  "port": 9100, "info": null },
      "active":   { "port": 9101, "protocol": "https" },
      "isAvailable": true },
    { "profile": { ... }, "isAvailable": false, ... }
  ],
  "server":      { "profile": { "id": "text2barcode", ... }, ... },
  "port9101":    { "available": true,  "protocol": "https", "port": 9101, "info": { ... } },
  "port9100":    { "available": false, "protocol": "http",  "port": 9100, "info": null },
  "active":      { "port": 9101, "protocol": "https" },
  "isAvailable": true
}
CampoTipoDescripción
serversobject[]Estado de cada app, en orden de prioridad: profile (id, name, securePort, defaultPort), secure y insecure (available, protocol, port, info), active e isAvailable.
serverobject | nullApp con la que trabaja la librería: la primera que responde en orden de prioridad. null si ninguna responde.
port9101 / port9100objectPuertos de Text2 Barcode: available (bool), protocol, port, info (JSON del servidor o null)
active{ port, protocol } | nullPuerto activo de la app en server (el seguro si responde, si no el HTTP). null si ninguna responde.
isAvailablebooleantrue si al menos una app responde.
Probar status() Test

Comprueba ambos puertos en paralelo y muestra el estado con indicadores visuales.

● HTTPS ● HTTP

isAvailable() boolean

PrintAgent.isAvailable()→ Promise<boolean>
Comprobación rápida de si Text2 Barcode está disponible en alguno de sus puertos (9101 HTTPS o 9100 HTTP).

Sin parámetros. Siempre resuelve, nunca rechaza.

Uso
if (await PrintAgent.isAvailable()) {
  // El agente Text2 Barcode está corriendo
} else {
  alert("Text2 Barcode no está disponible.");
}
Respuesta
true   // o false si ningún puerto responde
Probar isAvailable() Test

Devuelve true si el servidor responde en algún puerto.

available() Device[]

PrintAgent.available()→ Promise<{ printer: Device[] }>
Lista todas las impresoras disponibles en el dispositivo.

Sin parámetros.

Uso
const res = await PrintAgent.available();
for (const p of (res.printer || [])) {
  console.log(p.name, p.connection);
}
Respuesta
{
  "printer": [
    {
      "deviceType":      "printer",
      "uid":             "RT-420BE-USB",
      "driverConnection":"USB023",
      "name":            "RT-420BE-USB",
      "connection":      "driver",
      "resolution":      203,
      "queuedJobs":      0,
      "statusText":      "idle",
      "manufacturer":    "4BARCODE"
    },
    { ... }
  ]
}
Probar available() Test

Ejecuta PrintAgent.available() y muestra la lista completa de impresoras detectadas.

default() Device

PrintAgent.default()→ Promise<Device | null>
Devuelve la impresora marcada como predeterminada en el sistema operativo.

Sin parámetros.

Uso
const printer = await PrintAgent.default();
if (printer) console.log(printer.name);
Respuesta
{
  "deviceType":      "printer",
  "uid":             "RT-420BE-USB",
  "driverConnection":"USB023",
  "name":            "RT-420BE-USB",
  "connection":      "driver",
  "resolution":      203,
  "queuedJobs":      0,
  "statusText":      "idle",
  "manufacturer":    "4BARCODE"
}
Probar default() Test

Ejecuta PrintAgent.default() y retorna el objeto Device de la impresora predeterminada del sistema.

filter(predicate) Device[]

PrintAgent.filter(predicate)→ Promise<Device[]>
Devuelve todas las impresoras que cumplen el criterio.
ParámetroTipoReq.Descripción
predicate (Device) => boolean ✓ Función que recibe un Device y retorna true para incluirlo en el resultado.
Uso
const printers = await PrintAgent.filter(it => it.name.includes("ZPL"));
Respuesta
[
  {
    "deviceType":      "printer",
    "uid":             "RT-420BE-USB",
    "driverConnection":"USB023",
    "name":            "RT-420BE-USB",
    "connection":      "driver",
    "resolution":      203,
    "queuedJobs":      0,
    "statusText":      "idle",
    "manufacturer":    "4BARCODE"
  }
]
Probar filter(predicate) Test

Filtra impresoras por coincidencia parcial (case-insensitive) en el campo name.

Predicado: it.name.toLowerCase().includes(texto)

find(predicate) Device

PrintAgent.find(predicate)→ Promise<Device | null>
Devuelve la primera impresora que cumple el criterio, o null si ninguna coincide.
ParámetroTipoReq.Descripción
predicate (Device) => boolean ✓ Función que recibe un Device y retorna true para seleccionarlo.
Uso
// Por nombre exacto
const p1 = await PrintAgent.find(it => it.name === "Zebra GK420d");

// Contiene texto
const p2 = await PrintAgent.find(it => it.name.includes("ZPL"));

// Por tipo de conexión
const p3 = await PrintAgent.find(it => it.connection === "driver");
Respuesta
{
  "deviceType":      "printer",
  "uid":             "RT-420BE-USB",
  "driverConnection":"USB023",
  "name":            "RT-420BE-USB",
  "connection":      "driver",
  "resolution":      203,
  "queuedJobs":      0,
  "statusText":      "idle",
  "manufacturer":    "4BARCODE"
}
Probar find(predicate) Test

Busca la primera impresora que coincida. Elige el campo y el valor para construir el predicado.

Predicado: it.name === "…"

write(device, data) Result

PrintAgent.write(device, data)→ Promise<{ result: boolean, message: string }>
Envía comandos en texto plano (ZPL, ESC/POS, TSPL) a una impresora. Payload: { device, data } enviado como text/plain.
ParámetroTipoReq.Descripción
device Device ✓ Objeto Device obtenido con find(), default(), filter(), etc. Debe incluir uid, name y connection.
data string ✓ Contenido del trabajo de impresión:
• ZPL: bloque ^XA … ^XZ
• ESC/POS: bloque <EscPos> … </EscPos>
• TSPL: comandos TSPL para impresoras TSC
Uso
const result = await PrintAgent.write(printer, `
^XA
^PW609
^LL403
^PON
^CI28
^FO38,30^GB545,349,5^FS
^FO85,60^A0N,33,33^FH^FDZPL PRINT TEST - 3"^FS
^BY2,2,44^FO90,280^BCN,,Y,N
^FD123456789012^FS
^FO465,20^BQN,2,4
^FH\\^FDLA,123456789012^FS
^PQ1,0,1,Y
^XZ
`);
Respuesta
{ "result": true, "message": "messages" }
Probar write(printer, data) Test

Selecciona una impresora y edita el contenido a enviar. Las impresoras se cargan al abrir este panel.

writeAsBlob(device, blob) Result

PrintAgent.writeAsBlob(device, blob)→ Promise<{ result: boolean, message: string }>
Envía datos binarios a la impresora sin conversión. Usa FormData con campos json (metadatos del dispositivo) y blob (datos binarios). Endpoint: /write.
ParámetroTipoReq.Descripción
device Device ✓ Objeto Device destino. Se serializa como JSON en el campo json del FormData.
blob Blob ✓ Datos binarios a enviar. Útil para contenido ya compilado (bytes ESC/POS, archivos ZPL desde disco). MIME recomendado: application/octet-stream.
Uso
const zpl  = '^XA^FO50,50^A0N,50,50^FDHello^FS^XZ';
const blob = new Blob([zpl], { type: "application/octet-stream" });
const result = await PrintAgent.writeAsBlob(printer, blob);
Respuesta
{ "result": true, "message": "messages" }
Probar writeAsBlob(printer, blob) Test

Sube un archivo y lo envía a la impresora como Blob de tipo application/octet-stream.

Se envía tal cual con MIME fijo: application/octet-stream.

writeBlob(device, data) Result

PrintAgent.writeBlob(device, data)→ Promise<{ result: boolean, message: string }>
Envía datos binarios al endpoint dedicado /writeBlob. Usa FormData con campos device (JSON del dispositivo) y data (blob con nombre "data"). Diferencia con writeAsBlob: endpoint distinto y formato de campos diferente.
ParámetroTipoReq.Descripción
device Device ✓ Objeto Device destino. Se serializa como JSON en el campo device del FormData.
data Blob ✓ Blob de datos a imprimir (ZPL, TSPL, ESC/POS compilado…). Se envía con nombre de archivo "data" en el campo data del FormData.
Diferencias entre writeAsBlob y writeBlob
// writeAsBlob → endpoint /write, campos: json + blob
formData.append('json', JSON.stringify({ device }));
formData.append('blob', blob);

// writeBlob → endpoint /writeBlob, campos: device + data
formData.append('device', JSON.stringify(device));
formData.append('data', blob, 'data');
Uso
const zpl  = '^XA^FO50,50^A0N,50,50^FDHello^FS^XZ';
const blob = new Blob([zpl], { type: "application/octet-stream" });
const result = await PrintAgent.writeBlob(device, blob);
Respuesta
{ "result": true, "message": "messages" }
Probar writeBlob(device, data) Test

Sube un archivo y lo envía al endpoint /writeBlob. Usa campos device y data en FormData.

Se envía con nombre "data" vía FormData al endpoint /writeBlob.

convert(resource, payload) Result

PrintAgent.convert(resource, payload)→ Promise<ConvertResult>
Convierte una imagen o PDF a ZPL/ESC-POS/TSPL. Puede imprimir directamente, devolver el resultado en base64, o almacenarlo en el servidor.
ParámetroTipoReq.Descripción
resource Blob | File ✓ Archivo fuente (PNG, JPG o PDF). Puede ser un File de un <input type="file">.
payload object ✓ Configuración de la conversión. Ver tabla de opciones abajo.

payload.options

OpciónTipoReq.Descripción
action "print" | "store" | "return" ✓ "print" — convierte e imprime directamente (requiere device)
"return" — devuelve el resultado en base64
"store" — guarda el archivo en el servidor (requiere storageName)
fromFormat "png" | "jpg" | "pdf" ✓ Formato del archivo fuente.
toFormat "zpl" | "esc-pos" | "tspl" ✓ Formato destino de la conversión.
resize { width?, height? } — Redimensiona antes de convertir. Puedes pasar solo width o height; el otro lado se calcula proporcionalmente.
dithering string — Algoritmo para conversión a blanco/negro:
"FloydSteinbergDithering" — recomendado para fotos
"AtkinsonDithering" — patrones más compactos
"NoDithering" — umbral simple (igual que omitir la opción); ver threshold
gamma number — Ajuste de tono opcional, solo junto con dithering (de 0.1 a 3.0). 1 no cambia nada; menor a 1 aclara la imagen y compensa la ganancia de punto de las impresoras térmicas (0.8 es un buen punto de partida); mayor a 1 la oscurece.
threshold number — Umbral de 0 a 255 (entero, 127 por defecto): el nivel de gris que separa el negro del blanco. Más bajo imprime más claro; más alto, más oscuro. Con dithering es el punto de corte de la difusión de error; sin dithering (u omitiéndolo o con "NoDithering") es el de la conversión simple a blanco y negro. Un valor fuera de rango se rechaza.
luma "REC_601" | "REC_709" — Solo junto con dithering: cómo se pasa el color a gris antes de aplicarlo. "REC_601" (por defecto) es la fórmula clásica; "REC_709" da más peso al verde y cambia cómo se ven los colores en gris. Cualquier otro valor se rechaza.
serpentine boolean — Solo junto con dithering: recorre las filas en zigzag, alternando el sentido, lo que reduce los patrones direccionales de recorrer siempre hacia el mismo lado. false por defecto.
storageName string — Nombre del archivo a guardar cuando action es "store".

payload.device (Device) — requerido solo cuando action === "print".

Uso
const file = document.querySelector('#file-input').files[0];

const result = await PrintAgent.convert(file, {
  options: {
    action:     "print",                      // "print" | "return" | "store"
    fromFormat: "png",                        // "png" | "jpg" | "pdf"
    toFormat:   "zpl",                        // "zpl" | "esc-pos" | "tspl"
    resize:     { width: 600 },              // redimensionar (proporcional si solo width/height)
    dithering:  "FloydSteinbergDithering",   // algoritmo de dithering
    threshold:  127,                         // opcional (0 - 255, por defecto 127): nivel de gris que separa negro de blanco
    luma:       "REC_601",                   // opcional, con dithering: "REC_601" (por defecto) | "REC_709"
    serpentine: false,                       // opcional, con dithering: recorrido en zigzag (por defecto false)
    gamma:      0.8                          // opcional (0.1 - 3.0): menor a 1 aclara, mayor a 1 oscurece
  },
  device: printer  // requerido si action === "print"
});
Respuesta (action: "return")
{
  "data":     "ZPL o formato codificado en base64",
  "width":    600,
  "height":   400,
  "filename": "converted.zpl",
  "options":  { "action": "return", "toFormat": "zpl", "...": "eco de las opciones recibidas" }
}

options devuelve las opciones tal como llegaron a la app; algunas versiones de la app no lo incluyen.

Probar convert(resource, payload) Test

Selecciona una imagen o PDF y configura las opciones. Si action es "print", elige también la impresora destino.

Recetas

Solución de problemas

SíntomaQué revisar
No aparecen impresoras Verifica que Text2 Barcode esté corriendo. Usa status() para confirmar conectividad. Revisa permisos del navegador/SO.
Nombre no coincide Llama a available() para ver el nombre real y cópialo exacto, o filtra por uid.
Caracteres especiales En ZPL: asegura ^CI28 para UTF-8. En ESC/POS: verifica las banderas de charset.
Impresiones lentas / colas Evita enviar múltiples trabajos simultáneos. Espera siempre el await de write() antes del siguiente.