O que é Codificação Percentual? (RFC 3986 Explicado de Forma Simples)

O que é Codificação Percentual?

A codificação percentual, também chamada de codificação de URL, é a forma padrão de representar caracteres em uma URI (Uniform Resource Identifier) que não são permitidos ou que têm significado especial. Ela funciona substituindo cada caractere que precisa ser codificado por um sinal de porcentagem (%) seguido de dois dígitos hexadecimais que representam o valor em bytes do caractere.

Por exemplo, o caractere de espaço (valor de byte 0x20) é codificado como %20. O arroba @ (valor de byte 0x40) é codificado como %40. Esse mecanismo garante que qualquer dado possa ser incorporado com segurança em uma URI sem entrar em conflito com a sintaxe da URI.

O termo "codificação percentual" vem do uso do caractere de porcentagem como prefixo de escape. A especificação formal está definida na RFC 3986, publicada pela Internet Engineering Task Force (IETF) em janeiro de 2005 e escrita por Tim Berners-Lee, Roy Fielding e Larry Masinter.

Como Funciona a Codificação Percentual

O processo de codificação segue estas etapas: primeiro, o caractere é convertido em sua representação em bytes usando uma codificação de caracteres (quase sempre UTF-8 na web moderna). Em seguida, cada byte é representado por um sinal de porcentagem seguido de dois dígitos hexadecimais (usando maiúsculas A-F por convenção, embora os decodificadores devam aceitar minúsculas).

// Codificação passo a passo de um caractere de espaço
// Caractere: ' ' (espaço)
// Valor de byte ASCII/UTF-8: 0x20 (decimal 32)
// Codificado em percentual: %20

// Codificação passo a passo de um caractere multi-byte: e com acento agudo
// Caractere: e com acento agudo (U+00E9)
// Bytes UTF-8: 0xC3 0xA9
// Codificado em percentual: %C3%A9

// Codificação passo a passo de um caractere de 3 bytes
// Caractere: ideograma CJK (U+4E2D)
// Bytes UTF-8: 0xE4 0xB8 0xAD
// Codificado em percentual: %E4%B8%AD

Os dígitos hexadecimais devem sempre vir em pares. Um sinal de porcentagem isolado ou um sinal de porcentagem seguido de caracteres não hexadecimais é inválido e causará um erro de decodificação. Essa é uma causa comum do erro "URI malformed" em JavaScript.

A codificação percentual é sempre reversível. O decodificador lê o sinal de porcentagem, toma os dois caracteres seguintes como um valor de byte hexadecimal e o converte de volta ao caractere original. Para caracteres UTF-8 multi-byte, os bytes codificados consecutivos são combinados e decodificados juntos.

Quais Caracteres Devem Ser Codificados?

Nem todos os caracteres precisam de codificação percentual. A RFC 3986 define duas categorias: caracteres não reservados, que nunca precisam de codificação, e caracteres reservados, que devem ser codificados quando não estão sendo usados para sua finalidade reservada. Todos os demais caracteres (incluindo espaços, caracteres não ASCII e caracteres de controle) devem sempre ser codificados.

Caracteres que NÃO precisam de codificação (não reservados): letras maiúsculas (A-Z), letras minúsculas (a-z), dígitos (0-9), hífen (-), ponto (.), sublinhado (_) e til (~). Esses 66 caracteres podem aparecer em qualquer lugar de uma URI sem codificação.

Caracteres que às vezes precisam de codificação (reservados): : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Esses caracteres têm significado sintático especial em URIs. Eles só precisam de codificação quando usados como dados, em vez de como delimitadores.

Caracteres que sempre precisam de codificação: espaços, caracteres não ASCII (qualquer caractere acima de 127), caracteres de controle (0-31 e 127) e caracteres inseguros como < > { } | \ ^ ` ".

Caracteres Reservados vs. Não Reservados na RFC 3986

A distinção entre caracteres reservados e não reservados é fundamental para o funcionamento das URIs. Os caracteres reservados servem como delimitadores que definem a estrutura de uma URI. Por exemplo, :// separa o esquema da autoridade, / separa os segmentos de caminho, ? inicia a string de consulta e # inicia o fragmento.

Categoria	Caracteres	Quando Codificar
Não reservados	A-Z a-z 0-9 - . _ ~	Nunca
Delimitadores gerais	: / ? # [ ] @	Quando usados como dados, não como delimitadores
Subdelimitadores	! $ & ' ( ) * + , ; =	Quando usados como dados em componentes que lhes atribuem significado
Todos os demais caracteres	Espaços, não ASCII, caracteres de controle, etc.	Sempre

Um princípio fundamental da RFC 3986 é que URIs que diferem apenas no fato de um caractere reservado estar codificado em percentual ou aparecer literalmente não são equivalentes. Por exemplo, /path/to e /path%2Fto são URIs diferentes, mesmo que %2F seja decodificado como /. A primeira tem dois segmentos de caminho; a segunda tem um único segmento de caminho que contém uma barra literal.

Codificação Percentual vs. Codificação de URL: São a Mesma Coisa?

"Codificação percentual" e "codificação de URL" são frequentemente usadas como sinônimos e, na maioria dos contextos, significam a mesma coisa. No entanto, existe uma distinção histórica sutil. "Codificação de URL" pode às vezes se referir ao formato mais antigo application/x-www-form-urlencoded, usado por formulários HTML, que codifica espaços como + em vez de %20.

O formato application/x-www-form-urlencoded foi definido na especificação HTML e é anterior à RFC 3986. Ele tem regras ligeiramente diferentes: espaços se tornam +, e o conjunto de caracteres que não são codificados é um pouco diferente. O uso moderno do termo "codificação de URL" quase sempre se refere à codificação percentual da RFC 3986, na qual os espaços são %20.

Na prática, você deve usar a codificação percentual da RFC 3986 para todos os contextos de URI (segmentos de caminho, parâmetros de consulta em APIs REST, identificadores de fragmento). Use o formato application/x-www-form-urlencoded apenas ao lidar com envios de formulários HTML ou quando uma API específica o exigir.

// Codificação percentual da RFC 3986 (recomendada para URIs)
encodeURIComponent('hello world')  // "hello%20world"

// application/x-www-form-urlencoded (formulários HTML)
new URLSearchParams({q: 'hello world'}).toString()  // "q=hello+world"

// Equivalente em Python
from urllib.parse import quote, quote_plus
quote('hello world', safe='')   # "hello%20world"
quote_plus('hello world')       # "hello+world"