Codificação de URL e Query Strings: Um Guia Prático

URLs permitem apenas um conjunto limitado de caracteres no caminho e na query. Todo o restante deve ser codificado com percent-encoding (ex.: espaço → %20, & → %26). Errar nisso resulta em erros 404, tags de analytics quebradas e bugs sutis em APIs.

O que precisa ser codificado?

• Valores de query que contêm espaços, &, =, # ou texto não-ASCII (emojis, acentos) precisam ser codificados.
• Segmentos de caminho com barras ou caracteres especiais também precisam de codificação—caso contrário, o roteador interpreta errado onde um segmento termina.

Os navegadores geralmente exibem uma URL "amigável" na barra de endereço, enquanto enviam a forma codificada na transmissão. APIs, no entanto, esperam que você codifique explicitamente ao construir strings manualmente.

encodeURIComponent vs encodeURI

Em JavaScript:

• encodeURIComponent — Use para valores de parâmetros de query (e geralmente as chaves também). Ele codifica quase tudo que poderia quebrar uma URL.
• encodeURI — Use para uma URL inteira apenas quando você precisa preservar delimitadores como ? e #. Raramente necessário no trabalho diário com APIs.

const q = "hello world & friends";
const params = new URLSearchParams({ q });
console.log(params.toString()); // q=hello+world+%26+friends

URLSearchParams cuida da codificação para queries no estilo application/x-www-form-urlencoded padrão e é preferível à concatenação manual de strings.

Construindo URLs com muitos parâmetros

Ao adicionar tags UTM, filtros ou chaves de API, os erros se acumulam: ? duplicado, & não codificado ou ordenação ambígua. Um pequeno utilitário—ou um construtor visual—mantém a string final válida.

Experimente nossa ferramenta URL Encode / Decode para inspecionar como as strings mudam, e o URL & Query String Builder para montar um link completo com codificação segura para UTF-8.

cURL e fetch

Ao copiar requisições das ferramentas de desenvolvedor do navegador, preste atenção em query strings já codificadas. Colá-las no código às vezes resulta em dupla codificação dos valores. Nosso conversor cURL to fetch() ajuda você a transformar um cURL funcional em JavaScript enquanto verifica a URL separadamente.

Se um link "funciona no Chrome" mas falha no seu script, compare a query string bruta byte a byte.

Lista de verificação rápida

• Codifique os valores antes de concatenar em ?a=...&b=...
• Prefira URL + URLSearchParams em vez de construção manual de strings
• Para nomes de domínio internacionalizados (IDN), o navegador cuida do punycode no hostname—concentre a codificação no caminho e na query