Assine PDFs no Assinador Gov.br direto da sua aplicação web

1. Instalação da extensão

Para uso em produção, recomendamos instalar a extensão a partir das lojas oficiais:

• Chrome / Edge: Chrome Web Store – Assinador Gov.br (Integração)
• Firefox: Firefox Add-ons – Assinador Gov.br (Integração)

Durante o desenvolvimento é possível carregar a pasta assinador-govbr-chrome-extension em modo desenvolvedor (chrome://extensions → “Carregar sem compactação”). Para usuários finais, use sempre as lojas oficiais acima.

2. Navegadores e plataformas compatíveis

3. Exemplo mínimo de uso na página

Depois de instalada e autorizada para o domínio da sua aplicação, a extensão expõe a API window.AssinadorGovBrExtension.signFiles() diretamente no contexto da página. Você não precisa incluir scripts adicionais; basta chamar a função e tratar a Promise de retorno.

// Lista de arquivos a assinar (URL pública ou acessível pela extensão)
const files = [
  { url: 'https://meu-sistema.gov.br/arquivos/contrato.pdf' },
  // { url: 'https://meu-sistema.gov.br/arquivos/termo.pdf' },
];

const botao = document.querySelector('#btn-assinar');
const statusEl = document.querySelector('#status');

function setStatus(type, text) {
  statusEl.hidden = false;
  statusEl.textContent = text;
  statusEl.dataset.type = type; // use para estilizar (success/error/etc)
}

botao.addEventListener('click', async () => {
  if (!window.AssinadorGovBrExtension) {
    setStatus('error', 'Extensão não detectada. Verifique se ela está instalada e habilitada.');
    return;
  }

  botao.disabled = true;
  setStatus('running', 'Abrindo o Assinador Gov.br... conclua a assinatura na nova aba.');

  try {
    const signedFiles = await window.AssinadorGovBrExtension.signFiles(files);

    const ok = signedFiles.filter(f => f.base64 && !f.error).length;
    if (ok > 0) {
      setStatus('success', `Assinatura concluída. ${ok} arquivo(s) disponível(is) para download.`);
      console.log('Retorno da extensão:', signedFiles);
    } else {
      setStatus(
        'success',
        'Assinatura concluída no Gov.br. Baixe os arquivos diretamente na aba do Assinador.'
      );
    }
  } catch (err) {
    setStatus('error', 'Erro ao assinar: ' + (err && err.message ? err.message : String(err)));
  } finally {
    botao.disabled = false;
  }
});

Um exemplo completo pronto para uso está disponível em assinador-govbr-chrome-extension/example/example.html dentro deste projeto.

4. Formato dos arquivos de entrada (files)

A função signFiles(files) recebe um array, em que cada item representa um documento a ser enviado ao Assinador. São aceitos três formatos:

• { url: 'https://...' } – a extensão faz o download.
• { base64: '...', filename: 'x.pdf' } – base64 de um arquivo suportado.
• { blob: Blob, filename: 'x.pdf' } – objeto Blob já disponível na página.

const files = [
  // 1) A partir de URL (PDF ou outros formatos suportados)
  { url: 'https://meu-sistema.gov.br/docs/documento_1.pdf' },

  // 2) A partir de base64 (precisa informar filename)
  {
    base64: 'JVBERi0xLjcKJc...', // somente o conteúdo base64, sem o prefixo data:
    filename: 'relatorio_assinado.pdf',
  },

  // 3) A partir de Blob (por exemplo, após um upload local)
  {
    blob: meuBlobDePdf,
    filename: 'contrato_cliente.pdf',
  },
];

A extensão normaliza todos os arquivos para PDF/base64 internamente, garantindo nomes de arquivo consistentes. Se o tipo MIME original não for suportado, a chamada será rejeitada com erro.

5. Retorno da Promise (signedFiles)

A Promise retornada por signFiles resolve para um array com objetos: { filename, base64 } ou { filename, error }. Em casos de falha global (por exemplo, extensão ausente), a Promise é rejeitada com um Error.

function base64ToBlob(base64, mimeType = 'application/pdf') {
  const binary = atob(base64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return new Blob([bytes], { type: mimeType });
}

function downloadSignedFiles(signedFiles) {
  signedFiles.forEach((f) => {
    if (f.error) {
      console.warn('Falha ao obter arquivo assinado', f.filename, f.error);
      return;
    }
    if (!f.base64) return;

    const blob = base64ToBlob(f.base64, 'application/pdf');
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = f.filename || 'documento_assinado.pdf';
    a.target = '_blank';
    a.click();
    URL.revokeObjectURL(url);
  });
}

Veja um fluxo completo (incluindo validação de base64, mensagens de status e interface para download) em example/example.html dentro da pasta da extensão.

6. Boas práticas e limitações

7. Depuração rápida (checklist)

• A extensão aparece como instalada e habilitada em chrome://extensions (ou na tela de extensões do navegador)?
• O domínio da sua página está coberto pelas permissões da extensão?
• Há mensagens de erro no console da sua página ou na aba do Assinador?
• As URLs dos arquivos retornam 200 OK e permitem CORS para a extensão?