Anúncios incomodam? Ir Sem anúncios Hoje 

Codificação de URL O Que é Escapado e Por Que Sua API Quebra Sem Isso

Publicado em 25 abr. 2026

Sua chamada à API parecia correta. O ponto final correspondia, os cabeçalhos estavam certos e a resposta retornava 400 Request Bad. Após vinte minutos de olhar para ela, você percebe o problema: um endereço de e-mail na cadeia de consulta que contém um + sinal — que o servidor decodificou como um espaço. Isso é a codificação por porcentagem, e quebra coisas de maneiras que são realmente difíceis de depurar.

Este guia aborda o que a codificação por porcentagem realmente faz, quais caracteres precisam ser codificados em quais contextos, a armadilha comum em JavaScript e como usar uma ferramenta como a Codificador/Decodificador de URL para verificar seu trabalho.

O Que a Codificação por Porcentagem Realmente Faz

Uma URL pode conter apenas um subconjunto de caracteres ASCII. Tudo o que for diferente — espaços, caracteres internacionais, símbolos com significado especial em URLs — deve ser convertido em um formato seguro antes da transmissão.

A codificação por porcentagem faz isso substituindo cada byte inseguro por um sinal de porcentagem seguido de dois dígitos hexadecimais. Um espaço se torna %20, um hash se torna %23, um traço de barra se torna %2F. O nome vem do sinal de porcentagem inicial.

O padrão (RFC 3986) define "caracteres não reservados" que nunca precisam ser codificados: letras (A–Z, a–z), dígitos (0–9) e quatro símbolos: - _ . ~. Tudo o que for diferente é ou um caractere reservado (usado para delimitar a estrutura da URL) ou deve ser codificado.

Os Caracteres que Quebram APIs

Aqui estão os que causam mais danos na prática:

Caractere	Codificado	Contextos que exigem codificação	Notas
Espaço	%20	Todos os contextos	Também codificado como `+` em dados de formulário — veja abaixo
&	%26	Valores de cadeia de consulta	Separa parâmetros de consulta; deve ser codificado dentro do valor
=		Valores de cadeia de consulta	Separa chave de valor; codifique-o dentro do valor próprio
+		Valores de cadeia de consulta	Decodificado como espaço em codificação de formulário — use `%2B` para um sinal literal de mais
#	%23	Cadeia de consulta, valores de cadeia de consulta	Marca o fragmento; tudo após isso nunca é enviado ao servidor
?		Segmentos de caminho, valores de cadeia de consulta	Inicia a cadeia de consulta; codifique-o no caminho ou nos valores
/		Segmentos de caminho (quando literal)	Separa segmentos de caminho; codifique-o dentro do valor do segmento
@	%40	Valores de cadeia de consulta	Endereços de e-mail em parâmetros de consulta devem ter isso codificado

Três Contextos, Regras Diferentes

A parte da URL que você está codificando altera o que precisa ser escapado.

URL completa — Quando você tem uma URL completa para passar, deseja preservar sua estrutura. Barras, sinais de pergunta e sinais de hash permanecem inalterados. Apenas os caracteres fora do conjunto permitido são codificados.

Valor da cadeia de consulta — É aqui que a maioria dos erros em APIs reside. Cada valor em uma cadeia de consulta deve ser codificado para que os caracteres usados para estruturar a consulta (&, =, #, +) não apareçam literalmente no valor. Se o nome do usuário for "John & Jane", a cadeia de consulta deve ler name=John%20%26%20Jane, e não name=John & Jane (que o servidor interpreta como dois parâmetros separados).

Segmento de caminho — Um segmento de caminho é a parte entre barras. Se um segmento contém uma barra (por exemplo, um nome de arquivo com uma barra), deve ser codificado como %2F. Alguns servidores tratam %2F em um caminho como uma preocupação de segurança; conheça seu backend antes de usá-lo.

encodeURI vs encodeURIComponent — A Armadilha em JavaScript

JavaScript oferece duas funções de codificação integradas, e usar a errada é uma falha muito comum.

// encodeURI — encodes a full URL
// Preserves: : / ? # [ ] @ ! $ & ' ( ) * + , ; =
encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
// Note: & and = are NOT encoded — the query structure is preserved

// encodeURIComponent — encodes a single value
// Encodes everything except: A-Z a-z 0-9 - _ . ! ~ * ' ( )
encodeURIComponent("hello world&lang=en")
// → "hello%20world%26lang%3Den"
// Note: & and = ARE encoded — safe to use as a query value

// The bug: using encodeURI on a value
encodeURI("hello world&lang=en")
// → "hello%20world&lang=en"  ← & survives! Server sees two parameters.

// The correct approach for building query strings
const name = "John & Jane"
const email = "john+jane@example.com"
const url = `https://api.example.com/users?name=${encodeURIComponent(name)}&email=${encodeURIComponent(email)}`
// → "https://api.example.com/users?name=John%20%26%20Jane&email=john%2Bjane%40example.com"

Regra geral: use encodeURIComponent em valores individuais antes de colocá-los em uma URL. Use encodeURI apenas quando você tem uma URL completa e deseja limpá-la sem destruir sua estrutura.

O Sinal de Mais: Codificação de Formulário vs Codificação por Porcentagem

Quando um formulário HTML envia com method="GET", os navegadores codificam os dados usando application/x-www-form-urlencoded. Nesse formato, espaços se tornam + em vez de %20. Muitas frameworks de servidor (PHP, Django, Rails) decodificam automaticamente + como um espaço em cadeias de consulta.

Isso cria um problema quando o valor contém literalmente um sinal de mais — por exemplo, um número de telefone como +44 7700 900000. Se você passar como +44..., o servidor decodifica o sinal de mais inicial como um espaço e obtém 44.... A solução é codificar um sinal de mais literal como %2B, que permanece intacto em ambos os esquemas de decodificação.

Para trabalhos com APIs modernas, use %20 para espaços (o que encodeURIComponent produz) em vez de depender de +.

Dupla Codificação: Quando a Codificação Faz Erro

A dupla codificação ocorre quando você codifica algo que já foi codificado. O sinal de porcentagem em %20 é codificado para %2520 — o servidor decodifica %25 para um sinal literal de porcentagem, resultando na string %20 em vez de um espaço.

Isso geralmente surge quando:

Você armazena uma URL em um banco de dados e codifica novamente antes de usá-la
Uma framework ou biblioteca codifica valores que você já codificou manualmente
Você está construindo uma URL que contém outra URL como parâmetro

Para evitar isso: codifique exatamente uma vez, no ponto em que compõe a URL. Se você não tiver certeza se um valor já foi codificado, decodifique primeiro (com decodeURIComponent), depois re-codifique de forma limpa.

Depuração da Codificação de URL no DevTools

Quando uma solicitação à API se comporta de forma inesperada, abra DevTools (F12), vá para a aba Network e clique na solicitação falhada. Sob Headers, encontre a URL da solicitação — o navegador mostra-a na forma bruta após codificação. Sob Payload, você pode ver os parâmetros de consulta decodificados de volta aos valores originais, o que facilita identificar se um ampersand foi interpretado como separador ou passado literalmente.

Para testes manuais, uma ferramenta online de codificação e decodificação de URL permite que você cole uma string e veja exatamente como ela se parece na forma codificada — útil para verificar valores antes de incorporá-los em uma solicitação. O IO Tools Codificador/Decodificador de URL trata ambas as direções e mostra o resultado imediatamente.