Codificação de URL Explicada: Codificação por Porcentagem em Requisições HTTP

URLs parecem simples por fora — uma string de texto apontando para um recurso. Mas por baixo dos panos, elas seguem uma gramática rígida que permite apenas um conjunto específico de caracteres. No momento em que você tenta passar um espaço, um ampersand ou um caractere não-ASCII em uma URL sem codificá-lo, as coisas quebram de formas difíceis de depurar. A codificação por porcentagem (comumente chamada de URL encoding) é o mecanismo que torna dados arbitrários seguros para embutir em uma URL.

Você pode codificar e decodificar URLs instantaneamente com o Codificador/Decodificador de URL do BrowseryTools — gratuito, sem cadastro, tudo fica no seu navegador.

Por que Caracteres Especiais Quebram URLs

A especificação de URL (RFC 3986) reserva certos caracteres para fins estruturais. O ? separa o caminho da query string. O & separa parâmetros de query entre si. O # marca um identificador de fragmento. O / separa segmentos de caminho. Se seus dados contiverem qualquer um desses caracteres, um analisador de URL não conseguirá distinguir entre seus dados e a estrutura da URL em si.

Considere uma busca por rock & roll. Construir a URL ingenuamente resulta em:

/search?q=rock & roll
          ^     ^
          |     └── parece que um novo parâmetro começa aqui
          └── esse & divide q de um segundo parâmetro fantasma

O analisador lê q=rock (com espaço no final) como o primeiro parâmetro, depois encontra o que parece ser o início de um segundo parâmetro chamado roll. Ambos os valores estão errados. A URL correta é /search?q=rock%20%26%20roll — o espaço vira %20 e o ampersand vira %26.

O que a Codificação por Porcentagem Faz na Prática

A codificação por porcentagem converte um byte em uma sequência de três caracteres: um sinal de porcentagem literal seguido de dois dígitos hexadecimais maiúsculos representando o valor do byte. O caractere de espaço (byte ASCII 32, hex 0x20) vira %20. O arroba (@, ASCII 64, hex 0x40) vira %40. A regra é:

percent-encode(byte) = "%" + byte.toString(16).toUpperCase().padStart(2, "0")

Examples:
  space  (0x20) → %20
  @      (0x40) → %40
  [      (0x5B) → %5B
  €      (UTF-8: 0xE2 0x82 0xAC) → %E2%82%AC

Para caracteres Unicode de múltiplos bytes (qualquer coisa fora do ASCII), o caractere é primeiro codificado em bytes UTF-8, e então cada byte é codificado por porcentagem. O símbolo do euro € tem três bytes UTF-8, então vira três sequências codificadas: %E2%82%AC.

Caracteres Seguros vs Caracteres Reservados

Nem todo caractere precisa ser codificado. A RFC 3986 define dois conjuntos que podem ser usados como estão:

• Caracteres não reservados — A–Z, a–z, 0–9, hífen, sublinhado, ponto, til. Não têm significado especial e nunca precisam de codificação.
• Caracteres reservados — : / ? # [ ] @ ! $ & ' ( ) * + , ; =. São seguros em suas posições estruturais, mas devem ser codificados quando aparecem como valores de dados.

Todo o resto — espaços, Unicode, caracteres de controle, a maioria da pontuação — deve sempre ser codificado.

encodeURI vs encodeURIComponent: A Diferença Crítica

O JavaScript possui duas funções de codificação embutidas, e confundi-las é um dos bugs de codificação de URL mais comuns em aplicações web.

encodeURI() é projetado para codificar uma URL completa. Ele deixa todos os caracteres reservados intactos porque eles são estruturalmente significativos em uma URL completa. Use-o se você tiver uma URL completa que pode conter espaços ou Unicode mas tem uma estrutura válida:

encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
//   ✓ space encoded, but & and ? left intact

encodeURIComponent() é projetado para codificar um único valor — um valor de parâmetro de query, um segmento de caminho, qualquer coisa que deva ser tratada como dado puro. Ele codifica caracteres reservados também, incluindo &, =, ? e /:

encodeURIComponent("rock & roll")
// → "rock%20%26%20roll"
//   ✓ & encoded — safe to use as a query parameter value

encodeURIComponent("https://example.com/page")
// → "https%3A%2F%2Fexample.com%2Fpage"
//   ✓ colons and slashes encoded — safe as a redirect_uri value

A regra prática: ao construir uma URL, use encodeURIComponent() em cada valor de parâmetro individualmente, nunca na URL completa. Use encodeURI() apenas em uma URL completa que você deseja normalizar. No código moderno, prefira as APIs URL e URLSearchParams à codificação manual — elas lidam com a codificação automaticamente e corretamente.

Armadilhas na Codificação de Query String

Vários bugs sutis aparecem repetidamente ao codificar query strings. O sinal + merece atenção especial: no formato application/x-www-form-urlencoded (o formato que formulários HTML enviam), um espaço é codificado como + em vez de %20. Essa é uma convenção legada que antecede a RFC 3986. Se o seu backend decodifica por URL usando regras de codificação de formulário e o frontend envia %20, funciona bem. Mas se o frontend envia + e seu backend decodifica com as regras da RFC 3986, o + é mantido como um sinal de mais literal — não como espaço.

// URLSearchParams uses application/x-www-form-urlencoded (+ for spaces)
new URLSearchParams({ q: "rock & roll" }).toString()
// → "q=rock+%26+roll"

// encodeURIComponent uses RFC 3986 (%20 for spaces)
"q=" + encodeURIComponent("rock & roll")
// → "q=rock%20%26%20roll"

// Both are valid — just be consistent on both ends

Como Dados de Formulário São Codificados por URL

Quando um formulário HTML envia com method="GET", o navegador serializa os campos do formulário em uma query string usando application/x-www-form-urlencoded. Cada nome e valor de campo é codificado (espaços como +, caracteres especiais como %XX), e os campos são unidos com &. Para formulários method="POST" sem atributo enctype, a mesma codificação é usada mas os dados vão no corpo da requisição em vez da URL.

Esse também é o formato que o fetch() usa quando você passa um objeto URLSearchParams como corpo, e é o que a maioria dos frameworks server-side decodifica automaticamente ao ler envios de formulário.

Base64 em URLs

O Base64 padrão usa + e / — ambos com significados especiais em URLs. Quando dados codificados em Base64 precisam aparecer em uma URL (um padrão comum para tokens, dados de imagens ou assinaturas criptográficas), use a variante Base64URL. Ela substitui + por - e / por _, produzindo uma string segura em qualquer posição de URL sem codificação adicional. JWTs usam esse formato para seus segmentos de cabeçalho e payload.

Bugs Reais de Codificação

Alguns padrões de bug que aparecem em aplicações de produção:

• Codificação dupla — codificar uma URL já codificada. %20 vira %2520 porque o próprio % é codificado para %25. Sempre verifique se um valor já está codificado antes de codificá-lo novamente.
• encodeURIComponent ausente no redirect_uri — fluxos OAuth passam um redirect_uri como parâmetro de query. Se ele contém ? ou & e não está codificado, o servidor de autenticação interpreta esses caracteres como parte da estrutura da URL externa, quebrando o redirecionamento.
• Codificação não-UTF-8 — sistemas mais antigos ou servidores mal configurados às vezes codificam strings por porcentagem usando ISO-8859-1 em vez de UTF-8. A sequência de bytes para é difere entre os dois. Sempre imponha UTF-8 consistentemente nos dois lados.
• Registro de URLs brutas em logs — registrar uma URL que contém dados de usuário codificados pode produzir logs enganosos se o visualizador de logs decodificar sequências de porcentagem automaticamente, ocultando o que foi realmente enviado.

Codifique e Decodifique URLs Instantaneamente

Seja depurando um redirecionamento OAuth, construindo uma query string manualmente, inspecionando uma requisição de API malformada ou apenas tentando entender o que uma URL codificada por porcentagem realmente contém — o Codificador/Decodificador de URL do BrowseryTools resolve na hora. Cole sua string, escolha codificar ou decodificar e veja o resultado imediatamente. Sem chamadas ao servidor, sem cadastro.