O que é codificação de URL
Uma URL só pode conter um conjunto limitado de caracteres: letras sem acento, números e alguns símbolos, conforme a RFC 3986. Todo o resto — espaço, acentos, emojis e símbolos com significado especial, como &, ? e # — precisa ser convertido para o formato %XX, em que XX é o valor hexadecimal de cada byte em UTF-8. Esse processo se chama percent-encoding ou, no jargão, URL encode.
Sem essa conversão, links quebram de formas difíceis de perceber. O exemplo clássico: um parâmetro ?busca=arroz & feijão. O servidor entende que busca vale só “arroz ” e que existe um segundo parâmetro chamado “ feijão”. Codificado, fica ?busca=arroz%20%26%20feij%C3%A3o e chega inteiro.
Como usar
Codificar e decodificar
- Cole o texto ou a URL no campo Entrada.
- Escolha o método: encodeURIComponent para valores de parâmetros ou encodeURI para uma URL completa.
- Clique em Codificar ou Decodificar. O resultado é refeito enquanto você digita.
- Use Inverter para jogar o resultado de volta na entrada e conferir a volta.
Analisar URL
Cole um link completo e veja protocolo, domínio, porta, caminho, fragmento e uma tabela com todos os parâmetros da query string já decodificados. É útil para conferir links de campanha com UTM, depurar redirecionamentos e entender URLs longas de sistemas.
Como a codificação funciona, com exemplo
O texto é convertido em bytes UTF-8, e cada byte que não é permitido vira % + dois dígitos hexadecimais. Veja o texto Pão & café:
| Caractere | Bytes UTF-8 | Codificado |
|---|---|---|
P | 50 | P (permitido) |
ã | C3 A3 | %C3%A3 |
| espaço | 20 | %20 |
& | 26 | %26 |
é | C3 A9 | %C3%A9 |
Resultado: P%C3%A3o%20%26%20caf%C3%A9.
encodeURIComponent x encodeURI
As duas funções do JavaScript usam o mesmo mecanismo, mas diferem no que preservam:
- encodeURIComponent preserva apenas letras, números e
- _ . ! ~ * ' ( ). Todo o resto é codificado, inclusive/ ? : & = + # ,. É a escolha certa para um pedaço da URL, principalmente o valor de um parâmetro. - encodeURI também preserva os caracteres estruturais de uma URL (
: / ? # & = + , ;e outros). Serve para “limpar” uma URL inteira que tem acentos ou espaços, sem destruir a estrutura.
Usar encodeURI em um valor de parâmetro é um erro comum: um & ou = dentro do valor não é codificado e quebra a query string. Na dúvida, codifique cada valor separadamente com encodeURIComponent e monte a URL depois.
Anatomia de uma URL
Tomando como exemplo https://loja.com.br:8080/busca?q=tenis&cor=azul#topo:
- Protocolo:
https: - Host:
loja.com.br:8080(domínio + porta; a porta é omitida quando é a padrão, 443 para HTTPS) - Caminho:
/busca - Query string:
?q=tenis&cor=azul, com os parâmetrosqecor - Fragmento:
#topo, que não é enviado ao servidor; o navegador usa para rolar até uma parte da página
Um mesmo parâmetro pode aparecer mais de uma vez (como cor=azul&cor=preto), e o analisador mostra cada ocorrência numa linha.
Erros comuns
- Codificar duas vezes:
%20vira%2520. Se você vir%25seguido de dois dígitos, provavelmente houve codificação dupla. - Textos em Latin-1: sistemas antigos codificam “é” como
%E9, que não é UTF-8 válido e gera erro ao decodificar. - Esquecer de codificar o
#: tudo depois dele some da requisição.
Ferramentas relacionadas
O gerador de link de WhatsApp aplica exatamente essa codificação na mensagem pronta. Para dados binários em URLs e tokens, veja o Base64 URL-safe. E, para ler respostas de API, use o formatador de JSON.