Codificador / Decodificador URL gratuito

O que a codificação de URL realmente faz

A codificação de URL (também chamada de codificação por porcentagem) é o mecanismo que a web usa para encaixar dados de caracteres arbitrários numa URL. As URLs foram originalmente projetadas para um alfabeto ASCII minúsculo (letras, dígitos e um pequeno conjunto de sinais de pontuação) e os caracteres fora desse alfabeto (espaços, letras acentuadas, ampersands, barras que não são separadores de caminho, emojis, qualquer coisa cirílica, CJK ou árabe) precisam ser escapados antes de poderem viajar com segurança por HTTP, registos do servidor, barras de endereço do navegador, manipuladores de copiar e colar e tubos do shell. A regra de codificação é direta: pegue na sequência de bytes UTF-8 do caractere, escreva cada byte como um sinal de porcentagem seguido de dois dígitos hexadecimais. Um espaço (um byte, 0x20) torna-se %20. Um ampersand (0x26) torna-se %26. O sinal do euro € (três bytes UTF-8 E2 82 AC) torna-se %E2%82%AC. A forma codificada é reversível (qualquer analisador de URL na web sabe como descodificá-la) e o resultado é uma cadeia que contém apenas caracteres ASCII «seguros».

Uma breve história da regra de codificação

A convenção da codificação por porcentagem remonta à RFC 1738 («Uniform Resource Locators (URL)», Tim Berners-Lee, Larry Masinter e Mark McCahill, dezembro de 1994), a primeira especificação formal de URL publicada pela IETF. A RFC 1738 definiu o conjunto original de caracteres «reservados» (caracteres com significado estrutural em URLs que devem ser codificados quando usados como dados) e o conjunto original «não reservados» (caracteres que nunca precisam de codificação). A especificação foi substancialmente revista na RFC 2396 (Berners-Lee, Fielding, Masinter, agosto de 1998) e novamente (de forma definitiva) na RFC 3986 («Uniform Resource Identifier (URI): Generic Syntax», Berners-Lee, Fielding, Masinter, janeiro de 2005), que continua a ser hoje a especificação formal de URI. A RFC 3986 alargou o conjunto não reservado para incluir o til (~), formalizou UTF-8 como codificação para os caracteres não ASCII em IRIs e apertou as regras sobre quando os caracteres reservados devem ser codificados por porcentagem ou deixados tal como estão. Para URIs não ASCII, a RFC 3987 («Internationalized Resource Identifiers», Duerst e Suignard, janeiro de 2005) definiu a extensão IRI que permite que as URLs contenham caracteres Unicode nativos, mapeando a forma IRI para a forma URI padrão por meio de UTF-8 + codificação por porcentagem. Para os nomes de domínio em particular, a RFC 3492 definiu o Punycode (Costello, março de 2003), a codificação usada para representar etiquetas de domínio Unicode (xn--exmpla-...) no DNS, estruturalmente semelhante mas com um algoritmo diferente. A especificação de URL de facto da web moderna é o WHATWG URL Living Standard, editado por Anne van Kesteren, que codifica o comportamento real dos navegadores, por vezes divergindo da RFC 3986 por compatibilidade retroativa com a forma como as URLs funcionam na prática.

Reservados, não reservados e os caracteres que sempre são codificados

A RFC 3986 divide os caracteres de URI em três classes. Os caracteres não reservados: letras A-Z a-z, dígitos 0-9 e os quatro sinais - _ . ~: nunca precisam de codificação e nunca ganham significado quando são codificados. Os caracteres reservados: : / ? # [ ] @ ! $ & ' ( ) * + , ; =: têm significado estrutural em URLs (a barra separa segmentos de caminho, o ponto de interrogação introduz a query, o ampersand separa parâmetros de query, o cardinal introduz o fragmento). Os caracteres reservados podem aparecer não codificados no seu papel estrutural; devem ser codificados quando usados como dados comuns. Todos os outros caracteres: caracteres de controlo, espaços, o próprio porcentagem e qualquer byte de uma sequência UTF-8 não ASCII, devem sempre ser codificados por porcentagem. O caractere porcentagem é especial: deve ser codificado como %25 quando aparece como dado, porque um porcentagem não codificado num contexto de URL introduz uma sequência de escape porcentual que o analisador tentará descodificar. Saltar esse passo produz alguns dos bugs de manipulação de URL mais comuns que existem.

encodeURI vs encodeURIComponent, quando usar cada um

O JavaScript fornece dois codificadores incorporados, ambos padronizados em ECMAScript desde 1999 (ES3). A escolha entre eles é a decisão de codificação de URL mais comum em código web, e enganar-se produz bugs subtis que passam nos testes em entradas simples mas falham com dados reais de utilizador que contêm ampersands, cardinais ou barras.

• encodeURIComponent: codifica tudo exceto o conjunto não reservado. Use-o quando estiver a codificar uma única peça de dados que será incorporada numa URL, o valor de um parâmetro de query, um segmento de caminho, um identificador de fragmento, o valor de um campo de formulário. A cadeia hello world&more torna-se hello%20world%26more: o ampersand interno é codificado, pelo que não será interpretado como separador de parâmetro de query quando a URL for posteriormente lida. É a ferramenta certa para «tenho uma entrada de utilizador, quero colocá-la numa URL em segurança».
• encodeURI: codifica apenas os caracteres que são ilegais em qualquer parte de uma URL. Deixa deliberadamente intactos os caracteres reservados (: / ? # [ ] @ ! $ & ' ( ) * + , ; =) porque podem estar a desempenhar trabalho estrutural. Use-o quando estiver a codificar uma URL inteira que já tem a sua estrutura montada, uma URL com os seus próprios separadores ? e &, uma URL com caracteres não ASCII no caminho ou na query que precisam de ser codificados sem perturbar a gramática da URL. A cadeia https://example.com/search?q=hello world torna-se https://example.com/search?q=hello%20world: as barras e o ponto de interrogação são preservados, apenas o espaço é codificado.

A regra mental: encodeURIComponent para dados, encodeURI para URLs. Use o errado e quebrará ou a estrutura da URL (encodeURIComponent numa URL inteira escapa as barras e ampersands de que precisava) ou falhará no escape da entrada do utilizador (encodeURI num valor de query deixa passar os ampersands e os seus dados serão analisados como múltiplos parâmetros).

application/x-www-form-urlencoded, a outra codificação

Existe uma segunda codificação, relacionada, usada especificamente para envios de formulários HTML: application/x-www-form-urlencoded. É quase idêntica à codificação porcentual de URL, exceto num pormenor, os espaços são codificados como + em vez de %20. Esta convenção vem da especificação original de formulários HTML e é preservada no URL Living Standard especificamente para o serializador application/x-www-form-urlencoded. Os descodificadores de dados codificados como formulário devem inverter a convenção: um + literal em dados de formulário é codificado como %2B, e um + na cadeia codificada descodifica-se de volta a um espaço. A API URLSearchParams do JavaScript trata desta convenção automaticamente; o encodeURIComponent não: codifica sempre os espaços como %20. Para cadeias de query montadas à mão para uma ação de formulário HTML, use URLSearchParams em vez de chamar encodeURIComponent em cada valor individualmente.

Quando precisa mesmo desta ferramenta

• Depurar uma chamada à API. Está a invocar um endpoint REST com um parâmetro de query que contém espaços ou caracteres especiais e a receber erros 400 ou resultados inesperados. Codifique aqui o valor do parâmetro, cole o resultado no seu pedido e confirme que a API trata a entrada corretamente.
• Construir uma URL partilhável à mão. Compor um deep-link para uma página de resultados de pesquisa, uma vista filtrada de um painel SaaS ou um formulário pré-preenchido, qualquer lugar onde precise de incorporar uma consulta de pesquisa ou um estado de seleção na URL.
• Descodificar uma URL capturada para ler o que ela realmente contém. Uma URL registada contém %E2%9C%93%20done: em que se descodifica isso? Cole, carregue em Descodificar, veja ✓ done.
• URLs OAuth e webhooks. O parâmetro redirect_uri nos fluxos OAuth deve ser codificado por porcentagem com precisão; enganar-se produz erros opacos «redirect_uri mismatch». As URLs de webhook que contêm parâmetros com dados de utilizador exigem uma codificação cuidadosa.
• Nomes de ficheiro com caracteres não ASCII em ligações de download. Uma ligação direta para um ficheiro chamado café-menu.pdf precisa que o é esteja codificado por porcentagem para que a ligação funcione em todos os navegadores e ferramentas de shell.
• Cadeias de ligação a bases de dados. As URLs do PostgreSQL, MySQL e bases de dados semelhantes (postgres://user:p@ssw0rd@host/db) precisam que a palavra-passe esteja codificada por porcentagem se contiver @, :, / ou outros caracteres reservados que confundiriam o analisador de URL.

Segurança: porque a codificação importa para além da estética

A codificação incorreta de URL é uma fonte antiga de vulnerabilidades web. O HTTP response splitting explora quebras de linha não codificadas (CR, LF, %0D%0A) em parâmetros de URL que são refletidas em cabeçalhos HTTP, permitindo a um atacante injetar cabeçalhos arbitrários ou até mesmo uma resposta completa. As redireções abertas exploram um tratamento ingénuo de URL que não descodifica nem valida corretamente as URLs fornecidas pelo utilizador antes de redirecionar. A falsificação de pedidos do lado do servidor (SSRF) pode abusar de caracteres codificados para contornar listas brancas de URL, uma expressão regular que bloqueia «http://internal» falha ao apanhar «http://%69nternal» se o servidor descodificar depois da verificação. A injeção SQL via parâmetros de URL não é, em si, uma questão de codificação de URL, mas é agravada quando aspas simples e outros metacaracteres SQL sobrevivem até à consulta à base de dados. A recomendação da OWASP desde o início dos anos 2000 tem sido: codificar na fronteira à entrada, descodificar na fronteira à saída, nunca misturar formas codificadas e descodificadas no mesmo buffer. Esta ferramenta faz exatamente o passo de codificar/descodificar, o que faz com o resultado é consigo, e a responsabilidade da segurança está na camada da aplicação.

Codificação dupla, o bug mais comum

A codificação dupla acontece quando uma cadeia já codificada é codificada de novo. O caractere espaço numa URL já codificada é %20; codifique-o outra vez e obtém %2520 (porque o % codifica-se em %25). Quando o destinatário descodifica uma vez, recebe de volta %20 em vez de um espaço. Quando descodifica duas vezes (nos raros casos em que a dupla-descodificação é suportada), obtém o espaço, mas a maioria dos analisadores não o faz, e a URL contém silenciosamente um %20 visível na barra de endereço. A correção é sempre: descodifique primeiro se não souber se a entrada já está codificada, e depois codifique exatamente uma vez. O mesmo padrão aplica-se em código, nunca chame encodeURIComponent duas vezes na mesma cadeia. Se tiver de transferir um valor entre contextos, descodifique a codificação anterior antes de a codificar de novo para o novo contexto. O botão Trocar desta ferramenta ajuda no ciclo de diagnóstico: cole uma URL suspeita, carregue em Descodificar para ver o que está lá dentro, carregue em Trocar, carregue em Codificar para obter a forma codificada canónica.

Privacidade: execução só no navegador

As URLs incorporam frequentemente dados sensíveis, tokens de autenticação em parâmetros de query, identificadores de utilizador em segmentos de caminho, consultas de pesquisa com contexto pessoal, valores de estado OAuth, URLs de webhook que incluem chaves de API. Os codificadores de URL do lado do servidor guardam uma cópia de cada URL que lá colar nos seus registos. Esta ferramenta usa as funções incorporadas do JavaScript encodeURIComponent, encodeURI, decodeURIComponent e decodeURI a correr localmente no separador do seu navegador. Sem passo de envio, sem telemetria, sem registo, verifique no separador Rede das DevTools enquanto carrega em Codificar (não dispara qualquer pedido), ou ponha a página offline (modo de avião) depois de carregada e o codificador continua a funcionar. Seguro para URLs com tokens, chaves de API, endpoints internos ou qualquer URL que não queira ver copiada para o disco rígido de um estranho.

Perguntas frequentes

Quando devo codificar texto em URL?

Sempre que incorporar entrada de utilizador ou dados com caracteres especiais numa URL, consultas de pesquisa numa cadeia de query, nomes de ficheiro num caminho, valores de parâmetros em pedidos de API, alvos de redireção em fluxos OAuth. Sem codificação, os caracteres especiais ou quebram a estrutura da URL (um & não escapado num valor é interpretado como separador de parâmetros) ou introduzem vulnerabilidades de segurança (uma quebra de linha não escapada permite o HTTP response splitting). A regra prática: qualquer cadeia que contenha algo diferente de letras, dígitos e os quatro sinais -_.~ precisa de codificação antes de entrar numa URL.

O que é codificação dupla e como evitá-la?

A codificação dupla acontece quando texto já codificado é codificado uma segunda vez, transformando %20 em %2520 (porque o próprio caractere porcentagem é codificado como %25). Destinatários que descodificam uma vez recebem a forma meio-descodificada em vez do original. Sempre: se não souber se uma cadeia já está codificada, descodifique-a primeiro e codifique-a exatamente uma vez. Em código, nunca chame encodeURIComponent sobre a saída de outro encodeURIComponent.

Esta ferramenta é segura para URLs sensíveis?

Sim. O codificador/descodificador usa as funções incorporadas do JavaScript a correr inteiramente no seu navegador. A URL que cola nunca atravessa a rede, verifique no separador Rede das DevTools enquanto carrega em Codificar (não dispara qualquer pedido), ou ponha a página offline (modo de avião) depois de carregada. Seguro para URLs com tokens OAuth, chaves de API, endereços de endpoints internos ou qualquer valor que não queira ver registado num servidor de terceiros.

Porque é que os meus dados de formulário têm sinais de mais em vez de %20?

Os envios de formulários HTML usam uma codificação distinta mas relacionada chamada application/x-www-form-urlencoded, que codifica espaços como + em vez de %20 por convenção histórica. Ambas as formas são válidas em cadeias de query de URL; os analisadores modernos aceitam qualquer uma. A API URLSearchParams do JavaScript usa a convenção de formulário; encodeURIComponent usa sempre %20. Se os seus dados precisarem de interoperar com código antigo de tratamento de formulários, use URLSearchParams; em qualquer outro destino, qualquer uma das formas serve.

E os caracteres não ASCII e os emojis?

A codificação de URL moderna usa UTF-8: cada caractere não ASCII é convertido para a sua representação UTF-8 multi-byte, depois cada byte é codificado por porcentagem. O sinal do euro (€, três bytes UTF-8) torna-se %E2%82%AC; um emoji como o foguete 🚀 (quatro bytes) torna-se %F0%9F%9A%80. A RFC 3987 (IRIs) e o WHATWG URL Standard formalizam ambos esta convenção UTF-8 primeiro. Sistemas mais antigos por vezes usavam Latin-1 ou outras codificações; se está a descodificar URLs antigas e o resultado parece embaralhado, a fonte pode ter usado uma codificação de caracteres diferente antes da codificação porcentual.

Ferramentas relacionadas