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:
- Payload Format Indicator (ID 00): Sempre fixo em
01. - Merchant Account Information (ID 26): Sub-campo que indica o arranjo (
br.gov.bcb.pix) e a chave Pix destinatária. - Merchant Category Code (ID 52): Código de categoria comercial (
0000para genérico). - Transaction Currency (ID 53): Moeda ISO 4217 (
986para Real BRL). - Transaction Amount (ID 54 - opcional): Valor da transação com ponto decimal e 2 casas (ex:
150.00). - Country Code (ID 58): Código do país (
BR). - Merchant Name (ID 59): Nome do recebedor (sem acentos, até 25 chars).
- Merchant City (ID 60): Cidade do recebedor (sem acentos, até 15 chars).
- Additional Data Field Template (ID 62): Contém o
txid(Reference Label, sub-campo05). Para Pix estático genérico, o padrão é***. - 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:
- Geração instantânea de PDF A4: Proposta comercial técnica com escopo fechado, cronograma e regras de revisão.
- 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).
- 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.
- 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!