Codificação de URL explicada: %20, + e erros comuns

O que a codificação de URL realmente é

A codificação de URL, também chamada de codificação percentual, é como uma URL carrega caracteres que ela não pode conter. Uma URL só aceita um pequeno conjunto de letras ASCII, dígitos e sinais. Todo o resto — um espaço, um acento, um emoji, uma palavra em cirílico ou árabe — precisa ser escrito como % seguido de dois dígitos hexadecimais para cada byte.

O mesmo truque vale para caracteres que são permitidos mas têm significado. Um ? abre a consulta e um & separa parâmetros, então uma busca por pão & queijo precisa enviar o e-comercial como %26, ou o servidor vê dois parâmetros em vez de um.

Esse é todo o trabalho: deixar um valor seguro dentro de uma URL sem mudar o seu significado. Não é compressão, nem criptografia, nem filtro de segurança.

Como um caractere vira %XX

A codificação trabalha com bytes, não com caracteres. Primeiro o texto vira bytes UTF-8; depois cada byte que precisa ser codificado é escrito como % e seu valor em hexadecimal.

Um caractere ASCII é um byte, então um espaço (byte 32, hex 20) vira %20. Caracteres fora do ASCII ocupam de dois a quatro bytes em UTF-8, e cada byte ganha seu próprio escape:

• ç → bytes C3 A7 → %C3%A7
• € → bytes E2 82 AC → %E2%82%AC
• 😀 → bytes F0 9F 98 80 → %F0%9F%98%80

Decodificar faz o caminho inverso: junta os bytes e os lê como UTF-8. Se os bytes foram gerados com outro conjunto de caracteres, como Latin-1, sai texto embaralhado — ação em vez de ação. Todos os navegadores e frameworks modernos usam UTF-8, e você também deveria.

Reservados, não reservados e por que o contexto importa

A RFC 3986 divide os caracteres de uma URL em dois grupos.

Os não reservados — A–Z a–z 0–9 - . _ ~ — nunca precisam ser codificados. Codificá-los é permitido mas inútil, e um bom codificador os deixa como estão.

Os reservados — : / ? # [ ] @ ! $ & ' ( ) * + , ; = — dão estrutura à URL. Codificar ou não depende de onde ele está. A / entre segmentos do caminho precisa continuar barra; uma / dentro de um nome de arquivo passado como parâmetro precisa virar %2F. Por isso não existe um único jeito certo de "codificar uma URL": você codifica cada parte conforme o destino.

encodeURIComponent vs encodeURI

O JavaScript tem duas funções nativas, e escolher a errada é o bug de URL mais comum.

Aplique encodeURI a um valor como a&b=c e o & e o = sobrevivem, transformando um parâmetro em dois. Aplique encodeURIComponent a uma URL inteira e cada / e : é escapado, e o link deixa de ser link. A regra: monte a URL por partes e codifique cada valor com encodeURIComponent — ou, melhor ainda, deixe o URLSearchParams fazer isso.

Outras linguagens têm a mesma divisão: quote e quote_plus no Python, rawurlencode e urlencode no PHP. Nosso codificador e decodificador de URL oferece os dois modos para você ver a diferença no seu próprio texto.

+ ou %20: a exceção dos formulários

Num caminho, o espaço é %20 e um + é só um sinal de mais. Mas formulários HTML enviados com o tipo padrão application/x-www-form-urlencoded codificam o espaço como + na consulta, e os servidores decodificam de volta.

O problema começa quando as duas convenções se encontram. Um telefone como +55 11 91234-5678 colocado sem codificação numa consulta chega como 55 11 91234-5678, porque o servidor leu o + como espaço. A solução é codificar o mais como %2B, o que qualquer codificador que siga as regras de formulário faz. Na dúvida sobre a convenção do outro lado, %20 para espaço e %2B para mais são sempre seguros.

Dupla codificação e o bug %2520

%25 é o próprio sinal de porcentagem codificado. Então, quando você vê %2520 numa URL, é um %20 codificado pela segunda vez: um valor passou por um codificador depois de já estar codificado.

Isso costuma acontecer numa fronteira — um framework codifica um parâmetro que o código chamador já tinha codificado, ou uma URL de redirecionamento é codificada uma vez para caber em outra URL e depois de novo por uma biblioteca. O sintoma visível é um 404, uma busca pelo texto literal %20 ou um nome de arquivo cheio de sinais de porcentagem.

Decodificar duas vezes recupera o original, mas a correção de verdade é achar o segundo codificador e removê-lo. Codifique exatamente uma vez, no momento em que o valor entra na URL.

Codificar não é escapar, nem criptografar

A codificação percentual deixa um valor seguro dentro de uma URL. Ela não faz nada pelo HTML, JavaScript ou SQL. Assim que o servidor decodifica %3Cscript%3E, ele tem de novo um <script> comum, então a saída ainda precisa ser escapada conforme o destino e as consultas ao banco ainda precisam de parâmetros.

Também não é sigilo. Qualquer um decodifica uma URL, e URLs ficam em logs do servidor, histórico do navegador, ferramentas de análise e no cabeçalho Referer da página seguinte. Nunca coloque senha, token ou dados pessoais numa consulta porque "parece embaralhado". O mesmo vale para o Base64, como explica nosso guia de Base64.

Quando a decodificação dá errado

A maioria dos problemas com URL é um destes:

• "URIError: malformed URI sequence". Um % não é seguido de dois dígitos hexadecimais, ou os bytes não são UTF-8 válido. Um sinal de porcentagem literal precisa ser enviado como %25.
• Acentos saem como ç ou �. Os bytes foram escritos num conjunto de caracteres e lidos em outro. Garanta que os dois lados usem UTF-8.
• Um parâmetro é cortado num &. O valor não foi codificado, ou foi codificado com encodeURI em vez de encodeURIComponent.
• Sinais de mais viram espaços. A decodificação de formulário tratou o + como espaço. Codifique um mais de verdade como %2B.
• %2520, %253D e companhia. Dupla codificação: ache o segundo codificador.

Cole a URL num decodificador e olhe cada parâmetro separadamente — o detalhamento costuma deixar o problema óbvio em segundos.

Ferramentas e guias relacionados:

• Codificador e decodificador de URL - Codifique texto ou uma URL inteira, decodifique %XX em texto e veja cada parâmetro.
• Codificador e decodificador Base64 - Codifique texto para Base64 ou de volta, com saída URL-safe e UTF-8 tratado.
• Base64 explicado: como a codificação e a decodificação funcionam

Perguntas frequentes