QR Code por dentro: Reed–Solomon, Pix, vCard e Wi-Fi

As duas camadas de um QR Code

Um QR Code (definido pela norma ISO/IEC 18004) é uma matriz de módulos claros e escuros. A norma padroniza a camada física: os padrões de posicionamento nos três cantos, os padrões de alinhamento e de tempo que sincronizam a leitura, a "zona de silêncio" branca ao redor, e, o mais importante, a correção de erro Reed–Solomon que permite ler o código mesmo danificado. Nada disso depende do que está escrito: a matriz é o envelope. Dentro do envelope vai a segunda camada, o payload, que é só uma string de texto. Do ponto de vista de quem usa, o QR é uma caixa de texto: você coloca uma string e o leitor a devolve intacta.

Não existe "QR de Wi-Fi" ou "QR de Pix" no nível do código, existe um texto que segue uma convenção, e o aplicativo do celular decide o que fazer ao reconhecer o prefixo. Se o texto começa com "https://", o navegador abre; se começa com "WIFI:", o sistema oferece conectar à rede; se é um bloco "BEGIN:VCARD", a agenda pergunta se você quer salvar o contato. Por isso o gerador de QR Code não tem mágica por trás de cada tipo: ele só monta a string certa e a embrulha na matriz. É essa densidade que separa o QR (bidimensional, centenas a milhares de caracteres) de um código de barras tradicional, que é unidimensional e guarda só um número curto.

Módulo

Cada quadradinho preto ou branco. É a menor unidade da matriz; a leitura converte módulos em bits.

Versão

O tamanho da matriz, de 1 (21×21 módulos) a 40 (177×177). Cada versão acima soma 4 módulos por lado.

Correção de erro (Reed–Solomon)

Módulos extras de redundância que reconstroem dados perdidos por sujeira, risco ou um logo por cima.

Máscara

Um dos 8 padrões aplicados sobre os dados para evitar manchas grandes que confundem o leitor.

Payload

A string codificada dentro do código, o conteúdo que a convenção de prefixo faz o app interpretar.

1. 1994A Denso Wave cria o QR Code

   Masahiro Hara, na fabricante japonesa Denso Wave, projeta o código para rastrear peças automotivas, daí a leitura rápida e omnidirecional.

2. Junho de 2000Vira norma ISO/IEC 18004

   O QR Code é aprovado como norma internacional. A Denso Wave abre mão de cobrar pela patente, o que dispara a adoção mundial.

3. 2015 / 2024Edições revisadas da norma

   A ISO/IEC 18004 é atualizada (edições de 2015 e 2024), mas a estrutura de versões e os quatro níveis de correção seguem os mesmos.

4. 16 de novembro de 2020O Pix entra em operação

   O Banco Central lança o Pix, e o QR de pagamento no padrão BR Code (EMV) vira parte do cotidiano brasileiro.

A camada física: correção de erro, versão e máscara

Parte dos módulos de um QR não guarda o seu texto: guarda redundância. O código usa Reed–Solomon, uma família de correção de erro que trata os dados como coeficientes de um polinômio e adiciona "códigos de verificação" capazes de reconstruir símbolos perdidos. Você escolhe quanta redundância quer entre quatro níveis. Quanto maior o nível, mais dano o código tolera, e mais módulos ele gasta para os mesmos dados, ficando mais denso. Os percentuais abaixo são a fração de dados que o código consegue recuperar se estiverem corrompidos ou cobertos.

A escolha do nível interage com o tamanho. Mais correção significa mais códigos de verificação; para caber tudo, o código sobe de versão e ganha módulos. A capacidade máxima cai à medida que o nível sobe, como mostra o gráfico para a maior versão (40, com 177×177 módulos). Repare que ir de L para H corta a capacidade em mais da metade: é o preço da resistência a dano.

Antes de virar imagem, os dados passam por um mascaramento. O codificador testa oito máscaras, padrões que invertem certos módulos segundo uma regra, e escolhe a que tem a menor penalidade, uma pontuação que castiga manchas grandes de uma só cor, listras e padrões que imitam os marcadores de posição. Sem isso, um texto azarado poderia gerar uma matriz que o leitor confunde. É por isso que dois QR do mesmo texto, gerados por softwares diferentes, podem ter aparência distinta: escolheram máscaras diferentes, mas decodificam o mesmo conteúdo.

A camada de payload: as convenções de conteúdo

A tabela reúne as convenções mais usadas. Quase todas reaproveitam esquemas de URI que já existem na web (mailto:, tel:, sms:, geo:), o QR não inventou nada, só empacotou o texto num quadrado escaneável. A coluna de especificação mostra que cada "tipo" tem uma fonte: uma RFC, uma norma ou uma referência de facto.

Gere qualquer um desses formatos abaixo. A ferramenta monta a string, aplica o nível de correção e devolve a imagem, tudo no navegador, sem enviar seu conteúdo a lugar nenhum. Para salvar o resultado com nitidez, vale entender os formatos de imagem para a web: um QR deve sair em PNG ou SVG, nunca em JPEG, cuja compressão borra as bordas dos módulos.

Wi-Fi e vCard, com o escape na prática

O formato de Wi-Fi é um dos mais úteis: coloque a rede num QR e o visitante entra sem digitar a senha. A sintaxe não é uma norma ISO, é a convenção do projeto ZXing, que virou o padrão de facto seguido por praticamente todos os leitores. Os campos são T (tipo de segurança: WPA, WEP ou nopass), S (o SSID) e P (a senha), terminados por dois pontos-e-vírgula. Um exemplo direto:

WIFI:T:WPA;S:CafeGuest;P:Bemvindo2026;;

O detalhe que quebra muita gente é o escape. Como ponto-e-vírgula separa os campos, um SSID ou senha que contenha os caracteres especiais barra invertida, ponto-e-vírgula, vírgula, aspas ou dois-pontos precisa escapá-los com uma barra invertida na frente, a mesma regra do MECARD, segundo o ZXing. Este é o primeiro exemplo trabalhado do guia:

Rede:  Rede;Café      →  Rede\;Café
Senha: sen:ha,123      →  sen\:ha\,123

WIFI:T:WPA;S:Rede\;Café;P:sen\:ha\,123;;

O cartão de contato usa o padrão vCard (RFC 6350, versão 4.0). Cada linha é um campo: FN é o nome de exibição, N separa sobrenome e nome, ORG a organização, TEL o telefone. Vale um aviso de compatibilidade: a RFC 6350 tornou obsoleta a RFC 2426 (vCard 3.0), mas muitos aparelhos e apps de contatos ainda leem melhor a versão 3.0. Se um vCard 4.0 abrir torto em algum celular antigo, gerar a versão 3.0 costuma resolver. Veja um vCard 4.0 completo:

BEGIN:VCARD
VERSION:4.0
FN:Jane Doe
N:Doe;Jane;;;
ORG:Example Studio
TITLE:Product Designer
TEL;VALUE=uri:tel:+5511998877665
EMAIL:[email protected]
URL:https://jkit.tools
END:VCARD

Pix: o BR Code campo a campo e o CRC-16

O QR de pagamento Pix segue o BR Code, a implementação brasileira do padrão EMV® QR Code Merchant-Presented Mode (MPM), definida pelo Banco Central no arranjo Pix. A grande sacada é que esse texto é o próprio "Pix copia e cola": quando você copia o código, copia exatamente a string que estaria dentro do QR. Os dois são intercambiáveis porque são o mesmo dado. O BR Code não é texto livre: é uma sequência de campos no formato TLV, identificador (ID) de 2 dígitos, tamanho (length) de 2 dígitos e valor,, terminada por uma verificação CRC-16 no campo 63.

O segundo exemplo trabalhado do guia é um Pix estático completo, com uma chave de e-mail fictícia. Cada linha abaixo é um campo TLV; a indentação em 26 e 62 mostra os subcampos aninhados. Leia como ID, tamanho e valor:

00 02 01                      Payload Format Indicator
26 38                         Merchant Account Information
   00 14 br.gov.bcb.pix       GUI do arranjo Pix
   01 16 [email protected]     chave Pix (e-mail)
52 04 0000                    Merchant Category Code (MCC)
53 03 986                     moeda: 986 = BRL (ISO 4217)
54 05 25.00                   valor da transação (opcional)
58 02 BR                      país (ISO 3166-1)
59 13 FULANO DE TAL           nome do recebedor
60 09 SAO PAULO               cidade do recebedor
62 07                         Additional Data Field
   05 03 ***                  txid (identificador da cobrança)
63 04 674F                    CRC-16 (verificacao final)

A string contínua, sem espaços, fica assim, e é ela, exatamente, que o app lê:

00020126380014br.gov.bcb.pix0116joao@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62070503***6304674F

O campo 63 fecha o código com um CRC-16 na variante CCITT-FALSE. Ele não é uma assinatura de segurança, é um dígito verificador, como o que fecha um CPF ou um CNPJ (veja o guia de validação de CPF e CNPJ): serve para o app detectar um caractere trocado antes de tentar pagar. O detalhe que engana: o CRC é calculado sobre a string inteira já incluindo o ID e o tamanho do próprio campo 63, ou seja, incluindo os quatro caracteres "6304", mas antes do valor de quatro dígitos. A fórmula parte de um polinômio gerador:

1. Inicialize o registradorComece com um registrador de 16 bits valendo 0xFFFF (65.535).
2. Percorra cada bytePara cada caractere da string (do "00..." até e incluindo "6304"), faça o XOR do byte deslocado 8 bits à esquerda no registrador.
3. Oito deslocamentos por byteRepita 8 vezes: se o bit mais alto (0x8000) estiver ligado, desloque à esquerda e faça XOR com 0x1021; senão, só desloque. Mantenha só 16 bits.
4. Sem reflexão, sem xoroutNão há reflexão de bits na entrada nem na saída, e o xorout é 0x0000, o resultado é o próprio registrador.
5. Escreva em hexadecimalFormate em 4 dígitos hexadecimais maiúsculos. Para o exemplo acima, o resultado é 674F. Para conferir o algoritmo, a string "123456789" precisa dar 0x29B1, é o vetor de teste oficial do CRC-16/CCITT-FALSE.

Como o CRC depende de todo o resto, mudar um centavo do valor muda o código inteiro, não dá para editar um BR Code na mão sem recalcular a verificação. Para saber a qual instituição pertence uma chave ou um ISPB, use a lista de participantes do Pix.

Estático vs. dinâmico e o risco do "quishing"

O gerador de QR Code monta códigos estáticos: o conteúdo (link, Wi-Fi, vCard, Pix) fica todo dentro da imagem, sem intermediários, o que é ideal para privacidade e durabilidade. Prefira o dinâmico só quando precisar mesmo trocar o destino depois ou medir cliques, e, nesse caso, lembre que o código morre se o encurtador sair do ar, e que cada scan passa por um servidor que registra data, hora e, muitas vezes, sua localização aproximada (a mesma pegada de metadados que suas fotos deixam, tema do guia de metadados EXIF).