Codificación de URL explicada: percent-encoding y errores comunes

La codificación de URLs — también llamada percent-encoding — es el sistema que permite a una URL transportar caracteres para los que nunca fue diseñada. Una URL es, en el fondo, una cadena estrictamente formateada de caracteres ASCII. En el momento en que necesitas meter un espacio, un acento, un emoji o una palabra en árabe, tienes un problema: esos caracteres no están en el conjunto ASCII, y varios signos de puntuación ya están reservados para la estructura.

La solución es la sustitución. Cualquier carácter que no pueda aparecer literalmente se reemplaza por un signo de porcentaje seguido de dos dígitos hexadecimales, que representan el valor del byte de ese carácter. Un espacio es %20, un signo de interrogación es %3F, una almohadilla es %23, y un ampersand es %26. Leer y escribir estas secuencias de escape es justo lo que hace un codificador de URLs.

Tres ideas explican casi todos los bugs de codificación que encontrarás. La codificación es sensible al contexto — las reglas difieren entre la ruta y la cadena de consulta. La codificación es idempotente cuando se hace una vez — codificar un valor ya codificado por segunda vez crea un valor roto. Y la codificación debe respetar la estructura — los caracteres que construyen una URL nunca deberían codificarse, porque hacerlo los convierte en datos.

El resto del artículo recorre qué caracteres son seguros, en qué se diferencian la ruta y la cadena de consulta, por qué + y %20 no son intercambiables, cómo gestiona UTF-8 los scripts no latinos, el bug de la doble codificación y su firma, y cuándo no debes codificar en absoluto. Si solo necesitas una conversión, el codificador y decodificador de URLs la hace al instante en tu navegador.

¿Por qué las URLs necesitan codificación?

Una URL no es un campo de texto libre; es una dirección estructurada con una gramática. Los caracteres ?, &, =, #, / y % están reservados, lo que significa que tienen tareas estructurales. La ? marca dónde termina la ruta y empieza la consulta; & separa parámetros; = separa un parámetro de su valor; # inicia el fragmento.

En el momento en que uno de esos caracteres aparece en tus datos, la URL se vuelve ambigua. Una búsqueda de a&b se leería como dos parámetros, y un valor que contenga # truncaría todo lo posterior en un fragmento que nunca llega al servidor. Codificarlos — a%26b — elimina la ambigüedad, porque %26 solo puede significar «un carácter ampersand» y nunca «comienza un nuevo parámetro».

Lo mismo se aplica a los caracteres simplemente ilegales. Las URLs se definen sobre un repertorio ASCII limitado, así que un espacio, un carácter de control o cualquier cosa no latina no puede aparecer literalmente sin escaparse. El percent-encoding es el único mecanismo que maneja ambos casos: los caracteres reservados que se malinterpretarían y los caracteres que no se pueden escribir en absoluto.

¿Qué caracteres se pueden dejar en paz?

Hay un pequeño conjunto de caracteres que nunca necesitas codificar, conocido como los caracteres no reservados. Memorizarlo ahorra mucha incertidumbre, porque cualquier cosa de este conjunto significa exactamente lo mismo en toda la URL:

Fíjate en la última fila: los caracteres reservados son condicionales. Una / que separa segmentos de la ruta debe quedarse literal, pero una / dentro de un nombre de archivo debería codificarse como %2F o se interpretará como un nivel de directorio extra. Esa regla condicional — estructura frente a datos — es todo el juego.

Ruta frente a cadena de consulta: las reglas difieren

Una URL tiene zonas distintas, y las reglas de codificación no son uniformes entre ellas. La parte antes de la ? es la ruta; todo lo que sigue es la cadena de consulta. Navegadores, servidores y librerías de análisis aplican convenciones diferentes a cada una, lo que es una fuente callada de bugs.

• En la ruta, un espacio debería codificarse como %20. Un + en la ruta es un signo más literal, no un espacio.
• En la cadena de consulta, tanto %20 como + pueden significar un espacio, pero solo porque las cadenas de consulta siguen tradicionalmente la convención application/x-www-form-urlencoded de los formularios HTML.
• Los decodificadores no se ponen de acuerdo. En JavaScript, URLSearchParams convierte + en un espacio, mientras que decodeURIComponent deja + como un más literal. Mézclalos y la misma URL da dos valores distintos.

La conclusión práctica es saber para qué zona estás codificando y decodificar con el decodificador correspondiente. Si un valor hace un viaje de ida y vuelta incorrecto pero el texto parece estar bien, comprueba si un + espurio se está interpretando como un espacio en un sitio y como un signo más en otro.

La trampa del + frente al %20

Esto merece su propia sección porque es el bug de codificación más común, y es invisible hasta que te muerde. Tanto + como %20 pueden representar un espacio — pero solo dentro de una cadena de consulta, y solo bajo la convención de codificación de formularios.

La convención del + viene del envío de formularios HTML. Cuando un formulario envía datos como application/x-www-form-urlencoded, los espacios en los valores de los campos se escriben como +. Esa convención se trasladó a las cadenas de consulta, por lo que ?q=hello+world y ?q=hello%20world llegan ambas como «hello world» en la mayoría de servidores.

El modo de fallo es sutil. Si codificas el texto literal 1+1 porque quieres que el signo más sobreviva, obtienes 1%2B1 — correcto. Pero si sustituyes ingenuamente los espacios por + en una ruta, o dejas que un decodificador de formularios toque un valor donde +se pretendía literal, obtienes una corrupción silenciosa: «1 1» en vez de «1+1».

El hábito seguro es usar %20 para los espacios en todas partes, lo cual es inequívoco en todas las zonas, y reservar + para el caso específico de codificación de formularios donde sabes que el receptor lo espera. Al depurar, recuerda la asimetría: URLSearchParams decodifica + como un espacio, decodeURIComponent no.

UTF-8, acentos y scripts no latinos

El texto no latino añade un pliegue que sorprende a todo el mundo la primera vez. Una URL es ASCII, así que una letra acentuada o un carácter árabe deben convertirse primero a bytes — en UTF-8 — y luego cada byte se codifica en porcentaje individualmente.

La palabra francesa café se codifica como caf%C3%A9: las letras ASCII pasan sin cambios, mientras que la é son dos bytes en UTF-8, dando %C3 y %A9. Una palabra en árabe se expande más — cada letra son varios bytes, así que una palabra corta se convierte en una larga secuencia de grupos de porcentaje como %D9%85%D8%B1....

• Un carácter puede ser varios grupos. Nunca asumas que un grupo de porcentaje equivale a un carácter; cuenta bytes, no secuencias de escape.
• El juego de caracteres equivocado estropea el texto. Si el servidor decodifica los bytes con una codificación de un solo byte en vez de UTF-8, los acentos se vuelven galimatías. UTF-8 es el estándar por defecto por algo — mantente con él salvo que tengas una razón heredada específica para no hacerlo.
• Los navegadores modernos lo ocultan. Muestran URLs legibles y hacen la codificación al enviar, así que una URL en árabe pegada se ve limpia en la barra de direcciones aunque la petición por la red vaya codificada en porcentaje. Ese hueco entre la pantalla y el cable es justo por lo que a veces hace falta un codificador explícito.

Es también el caso donde una herramienta dedicada ayuda más, porque codificar texto no latino a mano es propenso a errores. El codificador de URLs convierte el texto a su forma correcta en UTF-8 con porcentajes y viceversa.

El bug de la doble codificación y su firma

La doble codificación es el bug que sigue dando, porque produce una URL que parece codificada y sin embargo llega mal. Ocurre cuando un valor ya codificado se codifica otra vez — frecuente cuando una función pasa un valor a otra sin saber que la primera ya lo había escapado.

Sigue la aritmética. Un espacio se convierte en %20. Codifica esa salida otra vez y es el propio signo de porcentaje el que se codifica, ya que % es un carácter reservado: %20 se convierte en %2520. Una ronda de decodificación ahora da la cadena literal %20 en vez de un espacio, porque el valor contenía un signo de porcentaje real.

La firma reveladora es un %25 donde debería haber un % — %2520, %2526, %252F son todos valores doblemente codificados. Si los ves, el valor se codificó dos veces.

La solución es decodificar exactamente el número de veces que se codificó, pero la mejor solución es la prevención: codifica un valor bruto una vez, en la frontera donde entra en la URL, y mantén una única fuente de verdad sobre si un valor ya está codificado. Las funciones que «amablemente» vuelven a codificar su entrada son las culpables habituales.

¿Cuándo no deberías codificar?

Codificar es una herramienta, no una política de «codifica todo, por si acaso». Aplicada a ciegas rompe las URLs que se suponía que debía proteger, porque los caracteres estructurales son lo que hace que una URL sea analizable.

• Nunca codifiques el esqueleto estructural. El :// tras el esquema, las / entre los segmentos de la ruta, y los ? & = # de la cadena de consulta deben quedarse literales. Codifícalos y la dirección deja de ser una dirección.
• Nunca codifiques un valor ya codificado. Ese es el bug de doble codificación de la sección anterior, y es completamente autoinfligido.
• No codifiques para «limpiar» una URL que no entiendes. Si una URL ya está fallando, codificar más al azar rara vez ayuda y a menudo oculta el verdadero problema. Decodifícala por completo primero, mira cuáles son realmente los valores brutos, y luego codifica una vez.

El modelo mental a conservar: codifica el valor, nunca la estructura. Construye la URL a partir de partes de confianza, codifica cada valor de datos exactamente una vez al entrar, y deja que los delimitadores hagan su trabajo.

Dónde se nota esto en la práctica

Estas son las situaciones en las que un bug de codificación cuesta tiempo de verdad, y donde conocer las reglas se paga.

• Los parámetros de búsqueda. Una caja de búsqueda que contenga & o = se dividirá en parámetros extra a menos que el valor esté codificado. Los constructores de consulta de los frameworks normalmente lo gestionan; la concatenación de cadenas, no.
• Los enlaces de seguimiento. Los parámetros UTM llevan títulos y nombres de campañas que suelen contener espacios y acentos. Un solo espacio sin codificar en un enlace de correo y toda la URL se rompe para cada destinatario que hace clic.
• Las peticiones a APIs. Las APIs reciben valores como parámetros de URL, y un # sin codificar trunca silenciosamente la petición, mientras que un + literal se convierte en un espacio. La codificación no es opcional aquí — es parte del contrato.
• Redirecciones y URLs reenviadas. Cuando una URL se pasa dentro de otra, debe codificarse como un único valor, o la URL externa malinterpretará los delimitadores de la interna.

Cada uno de estos casos es el mismo bug con diferente traje: un valor no se codificó donde la gramática lo exigía, o se codificó dos veces por un código que no confiaba en el último paso.

Codifica o decodifica una URL sin complicaciones

Sea cual sea el problema de URL, la conversión en sí debería tardar segundos:

• Un codificador y decodificador de URLs gratuito que maneja el percent-encoding en ambas direcciones.
• Manejo correcto de UTF-8 para acentos, árabe y otros scripts no latinos.
• Se ejecuta completamente en tu navegador — nada de lo que pegas se sube.
• Parte del conjunto más amplio de herramientas de texto : contador de palabras, contador de caracteres, conversor de mayúsculas y codificador Base64.

Preguntas frecuentes