2

Como implementei a geração de QR Code Pix estático (BRCode EMVCo + CRC16) em Node.js puro

Recentemente, enquanto desenvolvia um micro-SaaS voltado para prestadores de serviço e freelancers emitirem orçamentos formais com contrato e sinal de entrada, me deparei com um problema recorrente: a maioria das soluções para gerar QR Code Pix ou copia-e-cola na web dependia de SDKs pesados, bibliotecas cheias de dependências externas ou chamadas síncronas a APIs de gateways.

Para pagamentos de sinal de entrada (ex: 30% ou 50% de um projeto de freela), o Pix Estático (BRCode) é perfeito: não exige credenciais bancárias complexas, chaves de API com permissão de movimentação financeira nem servidores intermediários custosos. O cliente do prestador simplesmente aponta a câmera do banco ou cola o código e paga na hora diretamente na conta do profissional.

Resolvi dissecar a especificação oficial do Banco Central (Manual de Padrões para Iniciação do Pix / EMVCo MPM) e escrever uma implementação minimalista em Node.js/TypeScript puro, sem nenhuma dependência além de uma lib leve de renderização de SVG/canvas para o QR Code.

Compartilho abaixo como funciona a anatomia da string do BRCode e o algoritmo de CRC16.


A Anatomia do BRCode (Padrão EMVCo MPM)

A string do Pix Copia-e-Cola segue o padrão TLV (Type-Length-Value ou ID-Tamanho-Valor):

  • ID (2 dígitos numéricos): Identifica o campo.
  • Tamanho (2 dígitos numéricos): O comprimento exato do valor (com zero à esquerda, ex: 05).
  • Valor: Os dados brutos do campo.

Os campos obrigatórios definidos pelo Banco Central para um Pix estático são:

  1. Payload Format Indicator (ID 00): Sempre fixo em 01.
  2. Merchant Account Information (ID 26): Sub-campo que indica o arranjo (br.gov.bcb.pix) e a chave Pix destinatária.
  3. Merchant Category Code (ID 52): Código de categoria comercial (0000 para genérico).
  4. Transaction Currency (ID 53): Moeda ISO 4217 (986 para Real BRL).
  5. Transaction Amount (ID 54 - opcional): Valor da transação com ponto decimal e 2 casas (ex: 150.00).
  6. Country Code (ID 58): Código do país (BR).
  7. Merchant Name (ID 59): Nome do recebedor (sem acentos, até 25 chars).
  8. Merchant City (ID 60): Cidade do recebedor (sem acentos, até 15 chars).
  9. Additional Data Field Template (ID 62): Contém o txid (Reference Label, sub-campo 05). Para Pix estático genérico, o padrão é ***.
  10. CRC16 (ID 63): Checksum de integridade de 4 caracteres hexadecimais no final da string.

O Algoritmo de Checksum CRC16-CCITT (Polinômio 0x1021)

O ponto crítico onde a maioria das implementações quebra é no cálculo do CRC16. O Banco Central adota o padrão CRC16-CCITT:

  • Polinômio: 0x1021 (x¹⁶ + x¹² + x⁵ + 1)
  • Valor inicial: 0xFFFF
  • Sem reflexão de bits na entrada ou saída
  • O cálculo deve ser executado sobre a string completa concatenada com o prefixo 6304 (ID 63 + tamanho 04) no final.

Aqui está a implementação do cálculo em TypeScript/JavaScript puro:

function computeCRC16CCITT(payload: string): string {
  let crc = 0xFFFF;
  const polynomial = 0x1021;

  for (let i = 0; i < payload.length; i++) {
    crc ^= (payload.charCodeAt(i) << 8);
    for (let j = 0; j < 8; j++) {
      if ((crc & 0x8000) !== 0) {
        crc = ((crc << 1) ^ polynomial) & 0xFFFF;
      } else {
        crc = (crc << 1) & 0xFFFF;
      }
    }
  }

  // Retorna em hexadecimal maiúsculo com 4 dígitos (ex: 8B3A)
  return crc.toString(16).toUpperCase().padStart(4, '0');
}

Montando o Gerador de BRCode Completo

Para facilitar a composição dos campos TLV, criamos uma função simples:

function formatTLV(id: string, value: string): string {
  const len = value.length.toString().padStart(2, '0');
  return `${id}${len}${value}`;
}

export interface PixPayloadParams {
  pixKey: string;
  merchantName: string;
  merchantCity: string;
  amount?: number;
  txid?: string;
}

export function generateStaticBRCode({
  pixKey,
  merchantName,
  merchantCity,
  amount,
  txid = '***'
}: PixPayloadParams): string {
  // Limpeza de caracteres especiais/acentos (exigência Bacen)
  const cleanName = merchantName
    .normalize('NFD')
    .replace(/[\u0300-\u036f]/g, '')
    .slice(0, 25);
  const cleanCity = merchantCity
    .normalize('NFD')
    .replace(/[\u0300-\u036f]/g, '')
    .slice(0, 15);

  // Sub-campos da conta (ID 26)
  const gui = formatTLV('00', 'br.gov.bcb.pix');
  const key = formatTLV('01', pixKey);
  const merchantAccountInfo = formatTLV('26', `${gui}${key}`);

  // Sub-campo do TXID (ID 62)
  const txidField = formatTLV('05', txid);
  const additionalData = formatTLV('62', txidField);

  let payload = 
    formatTLV('00', '01') +             // Payload Format Indicator
    merchantAccountInfo +               // Informações da Conta Pix
    formatTLV('52', '0000') +           // Merchant Category Code
    formatTLV('53', '986') +            // Moeda (BRL)
    (amount ? formatTLV('54', amount.toFixed(2)) : '') + // Valor opcional
    formatTLV('58', 'BR') +             // País
    formatTLV('59', cleanName) +        // Nome
    formatTLV('60', cleanCity) +        // Cidade
    additionalData;                     // Dados adicionais (txid)

  // Adiciona o prefixo do CRC16 para o cálculo
  payload += '6304';

  const crc = computeCRC16CCITT(payload);
  return `${payload}${crc}`;
}

Onde Isso Foi Aplicado na Prática: O Fechou.doc

Usei essa implementação exata na construção do Fechou.doc.

A proposta do projeto nasceu de uma dor pessoal muito comum de quem presta serviço (devs, designers, arquitetos, etc.):

  • O cliente pede orçamento pelo WhatsApp.
  • O prestador manda só uma mensagem solta com valor.
  • O cliente aceita verbalmente, não paga sinal, pede alterações infinitas e depois atrasa ou some.

No Fechou.doc, unimos:

  1. Geração instantânea de PDF A4: Proposta comercial técnica com escopo fechado, cronograma e regras de revisão.
  2. Contrato de Prestação de Serviços Simplificado: Baseado no Código Civil (Arts. 593 a 609) com cláusula de validade de aceite eletrônico (dispensando cartório conforme a Lei 14.620/2023).
  3. Cálculo automático do Sinal (30% a 50%) com QR Code Pix embutido no PDF: Gerado exatamente com a rotina acima, renderizando o QR Code vetorial e a linha digitável do Copia-e-Cola no próprio documento de fechamento.
  4. Tabela de Referência de Preços 2026 por Região: Levantamento de médias de mercado para orientar autônomos que não sabem quanto cobrar.

Feedback Técnico e Discussão

Para quem quiser testar a geração do documento ou analisar a saída do BRCode em qualquer leitor de banco:
👉 fechou-doc.vercel.app/?ref=tabnews

Gostaria muito de ouvir a opinião da comunidade sobre:

  • Tratamento de chaves aleatórias (EVP) vs telefone/CPF/e-mail no parsing da string.
  • Limitações que vocês já encontraram na leitura de QR Codes do Bacen em diferentes bancos (ex: alguns bancos rejeitam espaços ou pontuações em nomes de cidades).

Espero que o código seja útil para quem estiver implementando cobranças Pix sem complicação em suas aplicações!

Carregando publicação patrocinada...