Agente de Impressão – iSoft Brasil

O que é o Agente de Impressão?

O PrintAgentClient é um componente JavaScript que se conecta, via WebSocket local, a um agente instalado na máquina do usuário (um executável leve para Windows). Com ele, qualquer sistema web pode enviar documentos para impressão diretamente na impressora escolhida — sem abrir o diálogo padrão do navegador e sem depender de plugins ou extensões.

Não é só HTML: o agente também imprime PDF, cupons em impressoras térmicas via ESC/POS (rede ou porta serial) e etiquetas Zebra via ZPL — cobrindo relatórios, comprovantes, cupons fiscais e etiquetas com controle total sobre impressora, cópias, margens, cabeçalho e rodapé.

Impressão de HTML, sem diálogo do navegador

Impressão de PDF direto do sistema

Cupom térmico via ESC/POS (rede ou serial)

Etiquetas Zebra via ZPL

Escolha de impressora, cópias e papel

Margens, cabeçalho e rodapé personalizáveis

Integração pronta

Já pronto para o Maker (Softwell)

Se você já usa a plataforma Maker, não precisa programar nada — temos as funções do Print Agent prontas para importar, já no padrão de Fluxo do Maker.

Isoft Brasil - Print - Inicializar PrintAgent

Isoft Brasil - Print - Lista Impressoras

Isoft Brasil - Print - Imprimir PDF

Isoft Brasil - Print - ESC/POS - Imp. térmica Rede

Isoft Brasil - Print - comandos ZPL para impressão

Marque a opção "Também sou usuário do Maker" no formulário de download e enviaremos as funções prontas para o seu e-mail.

Conectando ao agente

O cliente abre um WebSocket local (porta padrão 9099) com reconexão automática

import { PrintAgentClient } from './PrintAgentClient';

const print = new PrintAgentClient({ port: 9099 });

print.on('connect',    () => console.log('Agente pronto'));
print.on('disconnect', () => console.warn('Reconectando...'));
print.on('error',      (err) => console.error(err));

print.connect(); // reconexão automática com backoff exponencial

Ping

const { agentVersion, latency } = await print.ping();
// { agentVersion: "1.0.0", latency: 3 }

Listar impressoras

const impressoras = await print.listPrinters();
// [{ name: "EPSON L3250", isDefault: true, status: 0 }, ...]

Parâmetros do printHtml

Todos os campos aceitos pela função de impressão de HTML — para PDF, ESC/POS e ZPL, veja a seção Outros Formatos

Parâmetro obrigatório

Campo	Tipo	Descrição
`html`	string	HTML completo a imprimir — pode ser `document.documentElement.outerHTML` ou qualquer string HTML montada

Parâmetros opcionais

Campo	Tipo	Padrão	Descrição
`printer`	string	impressora padrão do Windows	Nome exato da impressora — use `listPrinters()` para obter os nomes disponíveis
`copies`	number	1	Quantidade de cópias
`landscape`	boolean	false	`true` = paisagem, `false` = retrato
`pageSize`	string	'A4'	'A4', 'A3', 'Letter', 'Legal', 'Tabloid'
`scaleFactor`	number	100	Zoom de impressão em % — útil para ajustar margens apertadas
`printBackground`	boolean	true	Imprime cores/imagens de fundo do CSS
`margins`	object	margens da impressora	Controle fino de margens (veja abaixo)
`header`	string	—	Texto no cabeçalho de cada página
`footer`	string	—	Texto no rodapé — suporta `&P` (página atual) e `&T` (total de páginas)

Objeto `margins`

margins: {
  marginType: 'custom',  // 'default' | 'none' | 'printableArea' | 'custom'
  top:    10,            // mm — só usado quando marginType = 'custom'
  bottom: 10,
  left:   15,
  right:  15,
}

Exemplo completo no seu site

Conecte o agente uma única vez e chame printHtml em qualquer botão de impressão

import { PrintAgentClient } from './PrintAgentClient';

const print = new PrintAgentClient();
print.on('connect', () => console.log('Agente pronto'));
print.connect();

// Em qualquer botão de impressão:
async function imprimirRelatorio() {
  const html = document.getElementById('relatorio').outerHTML;

  await print.printHtml({
    html,
    printer:         'HP LaserJet Pro',  // opcional
    copies:          1,
    pageSize:        'A4',
    landscape:       false,
    printBackground: true,
    scaleFactor:     100,
    margins: { marginType: 'custom', top: 15, bottom: 15, left: 20, right: 20 },
    footer:  'Página &P de &T',
  });
}

Outros formatos de impressão

Além de HTML, o agente também imprime PDF, cupons térmicos e etiquetas Zebra

Envie um arquivo PDF como base64. O agente salva em arquivo temporário, abre no Chromium e imprime sem exibir nenhuma janela.

const buf    = await pdfBlob.arrayBuffer();
const base64 = btoa(String.fromCharCode(...new Uint8Array(buf)));

await print.printPdf({ base64, printer: 'HP LaserJet', copies: 1 });

Envio de comandos ESC/POS em base64 para impressoras térmicas de cupom. Conexão via TCP/IP (rede) ou porta serial (COM).

await print.printEscPos({
  connection: { type: 'tcp', host: '192.168.1.50', port: 9100 },
  data: base64EscPosBytes,  // Uint8Array → base64
});

// Via porta serial (requer módulo serialport no agente):
connection: { type: 'com', port: 'COM3', baudRate: 9600 }

Envio de comandos ZPL para impressoras Zebra via TCP, geralmente na porta 9100.

await print.printZpl({
  host: '192.168.1.60',
  port: 9100,
  zpl:  '^XA^FO50,50^A0N,30,30^FDOlá Mundo^FS^XZ',
});

Tratamento de erros

O agente precisa estar instalado na máquina do usuário. Se não estiver conectado, o PrintAgentClient lança uma exceção com a mensagem "Agente não conectado" — capture-a e mostre um aviso orientando o usuário a instalar o executável. Se a impressora não responder dentro do tempo limite, o erro retornado é um Timeout.

try {
  await print.printHtml({ html });
} catch (err) {
  if (err.message.includes('não conectado'))
    alert('Instale e abra o IsoftBrasil Print Agent');
  else if (err.message.includes('Timeout'))
    alert('Impressora não respondeu');
  else
    alert(`Erro: ${err.message}`);
}

Baixar o Agente de Impressão

Preencha seus dados abaixo. Enviaremos o link de download para o e-mail informado — e, se você usa o Maker, as funções prontas também.

Quer integrar o Agente de Impressão no seu sistema?

Fale com a nossa equipe e receba o passo a passo de instalação e integração.

Falar com a iSoft Brasil

Agente de Impressão iSoft