Codificador / decodificador URL

Por que usar um codificador URL?

O percent-encoding (ou codificação URL) é indispensável sempre que você manipula parâmetros em uma URL. Caracteres especiais como &, =, ? ou espaços precisam 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 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 = em um 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 ser codificadas integralmente

Como usar o codificador / decodificador URL em 3 passos

Passo 1: Colar o conteúdo

Cole no campo de entrada:

• Texto puro se você quer codificar (ex.: preco=10€ & frete grátis)
• Uma string codificada se você quer decodificar (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 Decodificar 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 em uma URI. Cada byte não permitido é substituído por % seguido de dois dígitos hexadecimais representando 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 em uma 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 se torna +. Em um caminho de URL, ele se torna %20.

Casos de uso reais

Caso 1: Parâmetros UTM com caracteres especiais

Problema: Você cria um link de tracking para uma campanha chamada "Saldão verão 2025 - 50%".

Sem codificação:

https://captaindns.com?utm_campaign=Saldão 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=Sald%C3%A3o+ver%C3%A3o+2025+-+50%25

O tracking funciona corretamente, cada caractere especial é preservado.

Caso 2: URL de callback OAuth

Problema: Você configura um fluxo OAuth e precisa 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/offre?nom=Caf%C3%A9+%26+Th%C3%A9&code=PROMO%2D20

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

• nom = Café & Thé
• code = PROMO-20

Você 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, arquivos) 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: Por 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 em seus respectivos 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 em um 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 você suspeita de uma codificação dupla, decodifique duas vezes e compare os resultados.

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

R: Se você tentar decodificar 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)