Codificação de URLs explicada: Tudo que você precisa saber

Toda vez que você pesquisa no Google, compartilha um link com parâmetros de consulta ou constrói uma API REST, a codificação de URLs está trabalhando nos bastidores. No entanto, muitos desenvolvedores a tratam como um mistério — ou pior, a ignoram até que algo quebre.

Este guia explica a codificação de URLs (também chamada de percent-encoding) desde o início: o que é, por que existe, como funciona e como lidar com ela corretamente nos seus projetos.

O que é codificação de URLs?

A codificação de URLs é um mecanismo que substitui certos caracteres por um sinal % seguido de dois dígitos hexadecimais. Ela garante que as URLs contenham apenas caracteres do conjunto ASCII seguro, tornando-as válidas e transmissíveis pela internet.

Por exemplo, um espaço se torna %20, e um "e comercial" se torna %26.

A especificação formal é definida na RFC 3986, que determina quais caracteres são permitidos em URLs e quais devem ser codificados.

Por que a codificação de URLs é necessária?

URLs só podem conter um conjunto limitado de caracteres:

• Letras: A–Z, a–z
• Dígitos: 0–9
• Caracteres não reservados: -, _, ., ~

Tudo o mais — espaços, caracteres acentuados, símbolos como &, =, ?, # — deve ser codificado se aparecer em uma URL. Sem codificação, o servidor não consegue distinguir de forma confiável entre os dados reais e os caracteres estruturais da URL.

Considere esta URL:

https://example.com/search?q=olá mundo&lang=pt

O espaço em "olá mundo" cria ambiguidade. Ele faz parte da consulta, ou sinaliza algo mais? A codificação de URLs elimina essa ambiguidade:

https://example.com/search?q=ol%C3%A1%20mundo&lang=pt

Como funciona a codificação de URLs?

O processo de codificação é simples:

1. Pegar um caractere que não está no conjunto seguro.
2. Convertê-lo em seu valor em bytes (em UTF-8 para caracteres não-ASCII).
3. Representar cada byte como % seguido de dois dígitos hexadecimais.

Exemplos

Caractere	Bytes UTF-8	Codificado
Espaço	0x20	%20
&	0x26	%26
ã	0xC3 0xA3	%C3%A3
ç	0xC3 0xA7	%C3%A7
中	0xE4 0xB8 0xAD	%E4%B8%AD

Note que caracteres não-ASCII como ã produzem múltiplos bytes codificados porque o UTF-8 usa sequências multi-byte para caracteres fora do intervalo ASCII básico.

Codificação de URLs vs. codificação de formulários

Há uma distinção importante entre a codificação de URLs (percent-encoding conforme RFC 3986) e a codificação de formulários (application/x-www-form-urlencoded):

Aspecto	Codificação URL	Codificação formulário
Espaço →	%20	+
Padrão	RFC 3986	Especificação HTML
Usado em	Path, query string	Envio de formulários

Na codificação de formulários, espaços se tornam + em vez de %20. Essa é uma fonte comum de bugs quando desenvolvedores confundem os dois formatos.

Quando você precisa codificar URLs?

Você precisa de codificação de URLs em vários cenários comuns:

• Parâmetros de consulta: Valores com caracteres especiais (&, =, ?, espaços) devem ser codificados.
• Caminhos de URL com espaços ou Unicode: Nomes de arquivo como meu arquivo.pdf ou café.md precisam de codificação.
• Construção dinâmica de URLs: Ao concatenar entrada do usuário em URLs, sempre codifique a entrada.
• URLs de redirecionamento: Parâmetros como ?redirect=https://outro.com/pagina?a=1&b=2 precisam que a URL interna esteja codificada.

Como codificar URLs no código

JavaScript

// encodeURI: codifica uma URL completa (preserva ://, ?, &, =)
encodeURI("https://example.com/olá mundo");
// → "https://example.com/ol%C3%A1%20mundo"

// encodeURIComponent: codifica um valor individual (codifica tudo de especial)
encodeURIComponent("olá mundo&mais");
// → "ol%C3%A1%20mundo%26mais"

Python

from urllib.parse import quote, quote_plus

quote("olá mundo")      # → "ol%C3%A1%20mundo"
quote_plus("olá mundo") # → "ol%C3%A1+mundo"

PHP

urlencode("olá mundo");    // → "ol%C3%A1+mundo"
rawurlencode("olá mundo"); // → "ol%C3%A1%20mundo"

Erros comuns na codificação de URLs

1. Dupla codificação: Codificar uma string que já está codificada produz %2520 em vez de %20. Sempre verifique se seu framework já codifica os valores.
2. Usar a função errada: Em JavaScript, encodeURI e encodeURIComponent se comportam de forma diferente. Use encodeURIComponent para valores de parâmetros de consulta.
3. Esquecer de decodificar no servidor: Se você codifica no cliente, o framework do servidor geralmente decodifica automaticamente — mas nem sempre. Verifique se seu backend lida com isso.
4. Codificar a URL inteira: Usar encodeURIComponent em uma URL completa vai codificar os caracteres ://, ? e &, quebrando a estrutura da URL.

Experimente nosso codificador/decodificador de URLs gratuito

Nosso Codificador/Decodificador de URLs torna a codificação de URLs instantânea e sem complicação. Basta colar seu texto ou URL, escolher codificar ou decodificar, e obter o resultado imediatamente.

Recursos:

• Codificação e decodificação instantâneas com um clique
• Suporta caracteres Unicode de qualquer idioma
• Funciona no seu navegador — nenhum dado é enviado para nenhum servidor
• Mostra ambos os formatos — percent-encoding e codificação de formulário

Seja para depurar uma URL quebrada, construir query strings ou testar endpoints de API, ter uma ferramenta de codificação de URLs confiável economiza tempo e previne bugs frustrantes.

Decodificar URLs

A decodificação é o processo inverso: substituir sequências %XX por seus caracteres originais. A maioria dos frameworks web lida com isso automaticamente para requisições recebidas, mas você pode precisar decodificar manualmente quando:

• Analisa URLs de logs ou bancos de dados
• Trabalha com requisições HTTP brutas
• Processa URLs enviadas por usuários

Conclusão

A codificação de URLs é uma peça pequena, mas crítica da infraestrutura web. Entender quando e como codificar (e decodificar) URLs previne bugs, melhora a segurança e garante que suas aplicações lidem corretamente com caracteres internacionais.

Salve nosso Codificador/Decodificador de URLs nos favoritos para tarefas rápidas de codificação e decodificação — é grátis, rápido e funciona inteiramente no seu navegador.