Codificador / descodificador URL

Porque usar um codificador URL?

O percent-encoding (ou codificação URL) é indispensável sempre que manipula parâmetros numa URL. Caracteres especiais como &, =, ? ou espaços precisam de ser codificados para não quebrar a estrutura da URL.

Sem a codificação correta, um parâmetro contendo preco=10&20 seria interpretado como dois parâmetros distintos (preco=10 e 20). O navegador não consegue adivinhar a sua intenção: a codificação elimina a ambiguidade.

Três situações em que a codificação URL é indispensável:

• Parâmetros de query string → Um & ou = num valor corta a string no lugar errado
• Parâmetros UTM → Espaços ou caracteres acentuados em utm_campaign quebram o tracking de analytics
• Redirecionamentos e callbacks → URLs aninhadas (OAuth, SSO, emails marketing) precisam de ser codificadas integralmente

Como usar o codificador / descodificador URL em 3 passos

Passo 1: Colar o conteúdo

Cole no campo de entrada:

• Texto puro se quer codificar (ex.: preco=10€ & frete grátis)
• Uma string codificada se quer descodificar (ex.: preco%3D10%E2%82%AC+%26+frete+gr%C3%A1tis)

Passo 2: Selecionar a operação

Clique em Codificar URL para transformar texto em percent-encoding, ou em Descodificar URL para recuperar o texto original a partir de uma string codificada.

Passo 3: Copiar o resultado

O resultado aparece instantaneamente. Clique no botão copiar para obter a string convertida, pronta para ser inserida no seu código, URL ou configuração.

O que é percent-encoding?

O percent-encoding é o mecanismo definido pela RFC 3986 para representar caracteres especiais numa URI. Cada byte não permitido é substituído por % seguido de dois dígitos hexadecimais representando o seu valor UTF-8.

Exemplo concreto:

Texto original: Café & Chá = 15€
Codificado:     Caf%C3%A9+%26+Ch%C3%A1+%3D+15%E2%82%AC

O é (U+00E9) ocupa dois bytes em UTF-8 (C3 A9), resultando em %C3%A9. O símbolo € (U+20AC) ocupa três bytes (E2 82 AC), resultando em %E2%82%AC.

Caracteres não reservados (nunca codificados)

Esses caracteres passam como estão numa URL:

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

Caracteres reservados (codificados nos valores)

Tabela de codificação dos caracteres comuns

Nota: A diferença entre query e path diz respeito apenas ao espaço. Em query string (application/x-www-form-urlencoded), o espaço torna-se +. Num caminho de URL, ele torna-se %20.

Casos de uso reais

Caso 1: Parâmetros UTM com caracteres especiais

Problema: Cria um link de tracking para uma campanha chamada "Saldos verão 2025 - 50%".

Sem codificação:

https://captaindns.com?utm_campaign=Saldos verão 2025 - 50%

Os espaços, o hífen e o % quebram o link. O Google Analytics não captura a campanha.

Com codificação:

https://captaindns.com?utm_campaign=Saldos+ver%C3%A3o+2025+-+50%25

O tracking funciona corretamente, cada caractere especial é preservado.

Caso 2: URL de callback OAuth

Problema: Configura um fluxo OAuth e precisa de passar uma URL de retorno como parâmetro.

Sem codificação:

https://auth.captaindns.com/authorize?redirect_uri=https://captaindns.com/callback?token=abc&scope=read

O servidor interpreta scope=read como um parâmetro de /authorize, não de /callback.

Com codificação do redirect_uri:

https://auth.captaindns.com/authorize?redirect_uri=https%3A%2F%2Fcaptaindns.com%2Fcallback%3Ftoken%3Dabc&scope=read

A URL aninhada é corretamente isolada. O fluxo OAuth funciona.

Caso 3: Debug de um link de email quebrado

Problema: Um cliente informa que um link na sua newsletter não funciona. O link bruto no email é:

https://captaindns.com/oferta?nome=Caf%C3%A9+%26+Ch%C3%A1&code=PROMO%2D20

Ação: Cole a parte após ? no descodificador para ler os parâmetros:

• nome = Café & Chá
• code = PROMO-20

Identifica imediatamente se os valores estão corretos ou se uma codificação dupla corrompeu o link.

❓ FAQ - Perguntas frequentes

P: Qual é a diferença entre a codificação URL e o Base64?

R: A codificação URL (percent-encoding) substitui caracteres especiais por %XX para torná-los compatíveis com URLs. O Base64 codifica dados binários (imagens, ficheiros) em caracteres ASCII. Os dois não são intercambiáveis: use a codificação URL para parâmetros de URL, o Base64 para transmitir dados binários em texto.

P: Porque é que os espaços se tornam +?

R: É uma convenção do formato application/x-www-form-urlencoded, usado por formulários HTML e query strings. Nos caminhos de URL (antes do ?), o espaço é codificado como %20. As duas representações são válidas nos seus respetivos contextos.

P: Que caracteres não são codificados?

R: Os 66 caracteres não reservados definidos pela RFC 3986 nunca são modificados: letras A-Z, a-z, dígitos 0-9, e quatro símbolos: -, _, ., ~. Todos os outros caracteres são codificados quando aparecem num valor de parâmetro.

P: Posso codificar uma URL completa?

R: Não, codifique apenas os valores dos parâmetros. Os separadores estruturais (://, /, ?, &, =) devem permanecer como estão para que a URL continue funcional. Por exemplo, codifique o valor Café & Chá, mas não o ? ou o & que estruturam a URL.

P: O que acontece com uma codificação dupla?

R: Uma codificação dupla transforma %26 em %2526 (o % é recodificado). O servidor recebe então a string literal %26 em vez de &. É uma armadilha comum em redirecionamentos aninhados. Se suspeita de uma codificação dupla, descodifique duas vezes e compare os resultados.

P: O que acontece com uma codificação inválida?

R: Se tentar descodificar uma sequência inválida (por exemplo %GG ou um % isolado), a ferramenta exibe uma mensagem de erro explicativa em vez de um resultado corrompido. Corrija a sequência de origem antes de tentar novamente.

Ferramentas complementares

Recursos úteis

• RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax (especificação oficial do percent-encoding)
• RFC 3987 - Internationalized Resource Identifiers (IRIs) (extensão da RFC 3986 para caracteres Unicode)
• MDN - encodeURIComponent() (referência JavaScript da codificação URL)
• WHATWG URL Standard (especificação ativa do parsing e da serialização de URLs)