Guia Completo de URL Encoding

"Enviei parametros em portugues para a API e voltaram corrompidos."

Enviado: ?name=Joao Silva
Recebido: ?name=Jo%C3%A3o%20Silva

A causa deste problema e URL encoding. Entende-lo corretamente significa que voce nunca mais lutara com caracteres quebrados.

---

Por Que o Encoding e Necessario

URLs foram criadas nos anos 1990 e so permitem caracteres ASCII.

Caracteres Seguros em URLs

A-Z  a-z  0-9  - _ . ~

So isso.

Caracteres Problematicos em URLs

O Que o Encoding Faz

Converte caracteres problematicos para o formato %XX (hexadecimal).

Espaco -> %20
&      -> %26
a      -> %C3%A3 (por exemplo)

---

Funcoes de Encoding em JavaScript

Diferencas Principais

const text = "hello world&name=Joao Silva";

encodeURI(text);
// "hello%20world&name=Joao%20Silva"
// & e = permanecem intactos (preserva estrutura URL)

encodeURIComponent(text);
// "hello%20world%26name%3DJoao%20Silva"
// & -> %26, = -> %3D (codifica tudo)

Quando Usar Qual

Erros Comuns

// Errado: encodeURIComponent na URL completa
const url = "https://api.com/search?q=teste";
encodeURIComponent(url);
// "https%3A%2F%2Fapi.com%2Fsearch%3Fq%3Dteste"
// Nao usavel como URL!

// Correto: So codificar o valor
const query = "teste";
const url = `https://api.com/search?q=${encodeURIComponent(query)}`;
// "https://api.com/search?q=teste"

---

URLSearchParams - A Forma Moderna

Use URLSearchParams em vez de codificacao manual.

Uso Basico

const params = new URLSearchParams({
  name: "Joao Silva",
  city: "Sao Paulo",
  tags: "desenvolvedor,frontend"
});

params.toString();
// "name=Joao+Silva&city=Sao+Paulo&tags=desenvolvedor%2Cfrontend"

O encoding acontece automaticamente. Sem espaco para erros.

Com Objeto URL

const url = new URL("https://api.com/search");
url.searchParams.set("q", "Joao Silva");
url.searchParams.set("page", 1);

url.toString();
// "https://api.com/search?q=Joao+Silva&page=1"

Parsing (Decodificacao)

const url = new URL("https://api.com/search?name=Joao%20Silva");

url.searchParams.get("name");  // "Joao Silva" <- decodificado automaticamente!

---

Resolucao de Problemas Praticos

Problema 1: Duplo Encoding

// Codificar um valor ja codificado
const encoded = "%20";
encodeURIComponent(encoded);
// "%2520"
// % -> %25 causando corrupcao completa

Solucao: Verificar se ja esta codificado antes de codificar

function safeEncode(str) {
  try {
    // Se ja codificado, decodificar primeiro e re-codificar
    return encodeURIComponent(decodeURIComponent(str));
  } catch {
    // Falha na decodificacao = ainda nao codificado
    return encodeURIComponent(str);
  }
}

Problema 2: Duas Faces do Espaco

%20  vs  +

Ambos representam espaco mas tem origens diferentes.

encodeURIComponent("hello world");  // "hello%20world"
new URLSearchParams({q: "hello world"}).toString();  // "q=hello+world"

Ambos sao processados corretamente pelos servidores. Mas escolha um metodo para consistencia.

Problema 3: O Framework Ja Codifica

axios, fetch, React Router, etc. codificam automaticamente.

// axios - codificacao automatica
axios.get('/search', { params: { name: 'Joao Silva' } });
// Requisicao: /search?name=Joao%20Silva

// Errado: Codificacao manual causa duplo encoding
axios.get('/search', { params: { name: encodeURIComponent('Joao Silva') } });
// Requisicao: /search?name=Joao%2520Silva (quebrado)

Regra: Se usar um framework, nao codifique manualmente.

---

Tratamento no Lado do Servidor

Node.js / Express

// Auto-decodificado
app.get('/search', (req, res) => {
  const name = req.query.name;  // "Joao Silva"
});

// Igual para parametros de rota
app.get('/users/:name', (req, res) => {
  const name = req.params.name;  // "Joao Silva"
});

Python / Flask

from flask import request

@app.route('/search')
def search():
    name = request.args.get('name')  # "Joao Silva"

PHP

$name = $_GET['name'];  // "Joao Silva"
// PHP tambem auto-decodifica

---

Casos Especiais

Base64 em URL

Base64 padrao contem +, /, = que causam problemas em URLs.

// Base64 padrao
btoa("hello");  // "aGVsbG8="

// Base64 seguro para URL
function base64UrlEncode(str) {
  return btoa(str)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');  // remover padding
}

base64UrlEncode("hello");  // "aGVsbG8"

JWT usa este formato.

Cuidado com Fragmento (#)

https://example.com/page?name=Joao#section
                                  ^
                        Nao enviado ao servidor daqui

Tudo apos # (fragmento) e processado apenas no navegador e nao e enviado ao servidor.

---

Dicas de Debug

Barra de Endereco do Navegador

Navegadores mostram URLs decodificadas para legibilidade.

Exibido: https://example.com/users/Joao Silva
Real: https://example.com/users/Joao%20Silva

Verifique a URL real da requisicao na aba Network das Ferramentas de Desenvolvedor.

Testando com curl

# URL codificada diretamente
curl "https://api.com/search?name=Joao%20Silva"

# Deixar curl codificar
curl -G "https://api.com/search" --data-urlencode "name=Joao Silva"

---

Resumo

Principio Fundamental: Sempre que possivel, deixe URLSearchParams ou seu framework tratar, e evite codificacao manual.

---

Ferramentas Relacionadas