Codificador/Decodificador URL

¿Qué es la Codificación Porcentual?

La codificación porcentual (comúnmente llamada codificación URL) es un mecanismo definido en el RFC 3986 para codificar caracteres que no están permitidos o tienen un significado especial en un URI (Uniform Resource Identifier). Cada carácter inseguro se reemplaza con un signo de porcentaje (%) seguido de su código ASCII hexadecimal de dos dígitos.

Por ejemplo, un carácter de espacio (ASCII 32, hex 20) se convierte en %20. El signo arroba @ (ASCII 64, hex 40) se convierte en %40. Esto asegura que cada carácter en una URL sea un carácter ASCII seguro o una secuencia codificada porcentualmente explícita sin ambigüedad.

Las URLs solo pueden contener un subconjunto limitado de caracteres ASCII. Cuando una URL necesita incluir caracteres fuera de este conjunto — espacios, caracteres no ASCII o caracteres que tienen significado reservado en la sintaxis de URL — se requiere la codificación porcentual. Sin ella, la URL estaría malformada, sería ambigua o podría ser interpretada incorrectamente por navegadores y servidores.

Caracteres Reservados vs No Reservados

El RFC 3986 divide los caracteres ASCII en tres categorías para propósitos de URL:

Caracteres No Reservados (nunca necesitan codificación)

Estos caracteres pueden aparecer en cualquier parte de una URL sin codificación:

Categoría	Caracteres
Letras mayúsculas	A B C ... Z
Letras minúsculas	a b c ... z
Dígitos	0 1 2 ... 9
Especiales	- _ . ~

Caracteres Reservados (dependen del contexto)

Los caracteres reservados tienen un significado estructural especial en las URLs. Deben ser codificados porcentualmente cuando se usan como datos (por ejemplo, dentro del valor de un parámetro de consulta) pero no deben codificarse cuando se usan como delimitadores:

Carácter	Propósito en URL	Forma Codificada
:	Separador de esquema (https:)	%3A
/	Separador de ruta	%2F
?	Inicio de cadena de consulta	%3F
#	Inicio de fragmento	%23
&	Separador de parámetros de consulta	%26
=	Separador clave-valor	%3D
@	Separador de autoridad	%40
+	Espacio (solo en codificación de formularios)	%2B

Caracteres Inseguros (siempre necesitan codificación)

Los caracteres como espacios, comillas, corchetes angulares y todos los caracteres no ASCII (incluidos los caracteres multibyte UTF-8 como letras acentuadas, caracteres CJK y emoji) siempre deben ser codificados porcentualmente. Los caracteres no ASCII primero se codifican en bytes UTF-8, luego cada byte se codifica porcentualmente.

Por ejemplo, el carácter e con acento agudo son los bytes UTF-8 C3 A9, que se convierten en %C3%A9 en la URL.

encodeURI vs encodeURIComponent

JavaScript proporciona dos funciones integradas para la codificación porcentual, y elegir la incorrecta es una de las fuentes más comunes de errores en URLs.

encodeURI()

Codifica una URL completa. Deja intactos los caracteres estructurales de URL (/ ? # : @ & = + $) y solo codifica caracteres que son ilegales en cualquier parte de una URL (espacios, no ASCII, etc.).

encodeURI("https://example.com/path name?q=hello world")
// "https://example.com/path%20name?q=hello%20world"

Use encodeURI() cuando tenga una cadena de URL completa y quiera hacerla segura sin romper su estructura.

encodeURIComponent()

Codifica un componente de URL (un valor de parámetro individual, un segmento de ruta). Codifica todo excepto A-Z a-z 0-9 - _ . ~ — incluyendo caracteres reservados como / ? & =.

encodeURIComponent("hello world&goodbye")
// "hello%20world%26goodbye"

Use encodeURIComponent() cuando esté construyendo una URL pieza por pieza y necesite codificar el valor de un parámetro. Esto evita que el valor sea malinterpretado como estructura de URL.

La Regla de Oro

Al construir URLs a partir de valores dinámicos, siempre codifique los valores, nunca la estructura:

// Correcto
const url = `https://api.example.com/search?q=${encodeURIComponent(userInput)}`;

// Incorrecto — puede fallar si userInput contiene & o =
const url = `https://api.example.com/search?q=${userInput}`;

// Incorrecto — encodeURI no codificará & en el valor
const url = encodeURI(`https://api.example.com/search?q=${userInput}`);

Casos de Uso Comunes

• Parámetros de consulta: Al pasar entrada del usuario como parámetros de consulta URL (términos de búsqueda, filtros, datos de formulario), cada valor de parámetro debe ser codificado porcentualmente para evitar romper la estructura de la URL
• Llamadas a API REST: Los endpoints de API que aceptan parámetros de ruta o parámetros de consulta con caracteres especiales requieren codificación adecuada. Olvidar codificar una barra en un nombre de archivo, por ejemplo, crearía una ruta incorrecta
• URLs de redirección: Los flujos OAuth y sistemas de inicio de sesión único frecuentemente pasan URLs de callback como parámetros de consulta. Toda la URL de callback debe ser codificada para que sus caracteres ?, & y = no sean interpretados como parte de la URL externa
• Nombres de dominio internacionalizados (IDN): Mientras que los nombres de dominio usan Punycode (no codificación porcentual), las porciones de ruta y consulta de las URLs usan codificación porcentual para caracteres no ASCII
• Atributos de enlace HTML: Al incrustar URLs en atributos HTML href, caracteres como & deben ser tanto codificados porcentualmente (para corrección de URL) como codificados como entidad HTML (para corrección de HTML), por ejemplo, & en el código fuente HTML