Codificación de URL

La codificación de URL (también llamada percent-encoding) es el mecanismo que transforma caracteres especiales o no ASCII en una secuencia segura para incluirlos en una URL. Cada carácter problemático se sustituye por el símbolo % seguido de dos dígitos hexadecimales que representan su código en UTF-8: el espacio se convierte en %20, la ñ en %C3%B1 y la € en %E2%82%AC. Sin este mecanismo, una URL con tildes, espacios o símbolos especiales se rompería o se interpretaría de forma incorrecta por servidores y navegadores.

Por qué es necesaria la codificación

Las URLs solo pueden contener caracteres ASCII imprimibles, y dentro de ellos algunos tienen significado estructural reservado (? separa la querystring, & separa parámetros, # inicia el fragmento, / separa segmentos de ruta). Si el valor de un parámetro contiene alguno de esos caracteres, hay que codificarlo para que el servidor no lo malinterprete.

Ejemplo: si quieres buscar precio & calidad como término de búsqueda, la URL correcta es:

https://ejemplo.com/buscar?q=precio%20%26%20calidad

Sin codificar, el & rompería la querystring y el servidor recibiría dos parámetros en lugar de uno.

Caracteres frecuentes y su codificación

Los caracteres no reservados (letras A-Z/a-z, dígitos 0-9 y -, _, ., ~) no necesitan codificarse nunca.

Codificación en JavaScript

JavaScript ofrece dos funciones nativas según el contexto:

// Para codificar una URL completa (preserva la estructura)
const url = 'https://ejemplo.com/búsqueda?q=precio & calidad';
encodeURI(url);
// "https://ejemplo.com/b%C3%BAsqueda?q=precio%20&%20calidad"
// ⚠️ el & no se ha codificado porque encodeURI respeta la estructura

// Para codificar un valor de parámetro (escapa todo lo especial)
const valor = 'precio & calidad';
encodeURIComponent(valor);
// "precio%20%26%20calidad"
// ✓ el & queda como %26

// Forma correcta de construir una URL con parámetros
const base = 'https://ejemplo.com/buscar';
const termino = 'café & té';
const urlCompleta = base + '?q=' + encodeURIComponent(termino);
// "https://ejemplo.com/buscar?q=caf%C3%A9%20%26%20t%C3%A9"

Para decodificar, las funciones inversas son decodeURI() y decodeURIComponent().

Codificación en otros lenguajes

Python:

from urllib.parse import quote, urlencode
quote('precio & calidad')       # 'precio%20%26%20calidad'
urlencode({'q': 'café', 'p': 1}) # 'q=caf%C3%A9&p=1'

PHP:

urlencode('precio & calidad');    // 'precio+%26+calidad'
rawurlencode('precio & calidad'); // 'precio%20%26%20calidad'

Relación con Base64 y JWT

La codificación de URL no es lo mismo que Base64. Base64 transforma datos binarios en caracteres ASCII para transmisión; percent-encoding transforma caracteres especiales para usarlos en URLs. Sin embargo, hay una variante de Base64 llamada Base64url (usada en JWT) que reemplaza + por - y / por _ precisamente para que el token pueda incluirse en una URL sin necesidad de percent-encoding adicional.

Errores comunes

• Codificar la URL completa con encodeURIComponent: esto codifica también las barras y los dos puntos del protocolo, rompiendo la URL. Usa encodeURI para la URL entera y encodeURIComponent solo para los valores de los parámetros.
• Codificar doble: si recibes una cadena ya codificada y la vuelves a codificar, los % se convierten en %25 y el resultado es incorrecto. Decodifica primero con decodeURIComponent si hay duda.
• Ignorar la codificación de parámetros en el servidor: aunque el frontend codifique bien la URL, el backend debe decodificar los valores antes de usarlos en consultas a base de datos o comparaciones.
• Confundir + y %20: en los formularios HTML (POST con application/x-www-form-urlencoded), el espacio se codifica como +. En URLs (querystrings construidas a mano), la codificación estándar es %20. La mayoría de servidores aceptan ambas, pero no asumas que son siempre equivalentes en todos los contextos.