Codificación de URL Explicada: La Codificación Porcentual en Solicitudes HTTP

Las URLs parecen simples desde fuera — una cadena de texto que apunta a un recurso. Pero bajo la dentro siguen una gramática estricta que solo permite un conjunto específico de caracteres. En el momento en que intentas pasar un espacio, un ampersand o un carácter no ASCII en una URL sin codificarlo, las cosas se rompen de formas difíciles de depurar. La codificación porcentual (comúnmente llamada codificación de URL) es el mecanismo que permite incrustar datos arbitrarios de forma segura en una URL.

Puedes codificar y decodificar URLs al instante con el Codificador/Decodificador de URL de BrowseryTools — gratuito, sin registro, todo se procesa en tu navegador.

Por qué los caracteres especiales rompen las URLs

La especificación de URL (RFC 3986) reserva ciertos caracteres para propósitos estructurales. El ? separa la ruta de la cadena de consulta. El & separa los parámetros de consulta entre sí. El # marca un identificador de fragmento. El / separa los segmentos de ruta. Si tus datos contienen alguno de estos caracteres, un analizador de URL no puede distinguir entre tus datos y la estructura de la URL.

Considera una búsqueda de rock & roll. Si construyes la URL ingenuamente obtienes:

/search?q=rock & roll
          ^     ^
          |     └── looks like a new parameter begins here
          └── this & splits q from a phantom second parameter

El analizador lee q=rock (con un espacio al final) como primer parámetro, y luego encuentra lo que parece ser el inicio de un segundo parámetro llamado roll. Ambos valores son incorrectos. La URL correcta es /search?q=rock%20%26%20roll — el espacio se convierte en %20 y el ampersand en %26.

Qué hace realmente la codificación porcentual

La codificación porcentual convierte un byte en una secuencia de tres caracteres: un signo de porcentaje literal seguido de dos dígitos hexadecimales en mayúsculas que representan el valor del byte. El carácter espacio (byte ASCII 32, hex 0x20) se convierte en %20. El símbolo arroba (@, ASCII 64, hex 0x40) se convierte en %40. La regla es:

percent-encode(byte) = "%" + byte.toString(16).toUpperCase().padStart(2, "0")

Examples:
  space  (0x20) → %20
  @      (0x40) → %40
  [      (0x5B) → %5B
  €      (UTF-8: 0xE2 0x82 0xAC) → %E2%82%AC

Para caracteres Unicode multibyte (cualquier cosa fuera de ASCII), el carácter se codifica primero como bytes UTF-8, y luego cada byte se codifica porcentualmente. El signo del euro € ocupa tres bytes UTF-8, por lo que se convierte en tres secuencias codificadas porcentualmente: %E2%82%AC.

Caracteres seguros vs caracteres reservados

No todos los caracteres necesitan codificación. El RFC 3986 define dos conjuntos que son seguros tal como están:

• Caracteres no reservados — A–Z, a–z, 0–9, guion, guion bajo, punto, tilde. No tienen ningún significado especial y nunca necesitan codificación.
• Caracteres reservados — : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Son seguros en sus posiciones estructurales, pero deben codificarse cuando aparecen como valores de datos.

Todo lo demás — espacios, Unicode, caracteres de control, la mayoría de la puntuación — siempre debe codificarse.

encodeURI vs encodeURIComponent: la diferencia crítica

JavaScript incluye dos funciones de codificación integradas, y confundirlas es uno de los errores de codificación de URL más comunes en las aplicaciones web.

encodeURI() está diseñada para codificar una URL completa. Deja intactos todos los caracteres reservados porque son estructuralmente significativos en una URL completa. La usarías si tienes una URL completa que podría contener espacios o Unicode pero tiene una estructura válida:

encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
//   ✓ space encoded, but & and ? left intact

encodeURIComponent() está diseñada para codificar un valor individual — el valor de un parámetro de consulta, un segmento de ruta, cualquier cosa que deba tratarse como datos puros. Codifica también los caracteres reservados, incluidos &, =, ? y /:

encodeURIComponent("rock & roll")
// → "rock%20%26%20roll"
//   ✓ & encoded — safe to use as a query parameter value

encodeURIComponent("https://example.com/page")
// → "https%3A%2F%2Fexample.com%2Fpage"
//   ✓ colons and slashes encoded — safe as a redirect_uri value

La regla práctica: al construir una URL, usa encodeURIComponent() en cada valor de parámetro individual, nunca en la URL completa. Usa encodeURI() solo en una URL completa que quieras normalizar. En código moderno, prefiere las APIs URL y URLSearchParams frente a la codificación manual — gestionan la codificación de forma automática y correcta.

Problemas frecuentes en la codificación de cadenas de consulta

Varios errores sutiles aparecen repetidamente al codificar cadenas de consulta. El signo + merece mención especial: en el formato application/x-www-form-urlencoded (el formato que usan los formularios HTML al enviar datos), un espacio se codifica como + en lugar de %20. Es una convención heredada anterior al RFC 3986. Si tu backend decodifica URL con reglas de codificación de formulario y el frontend envía %20, funciona bien. Pero si el frontend envía + y tu backend decodifica con reglas RFC 3986, el + queda como un signo más literal — no como un espacio.

// URLSearchParams uses application/x-www-form-urlencoded (+ for spaces)
new URLSearchParams({ q: "rock & roll" }).toString()
// → "q=rock+%26+roll"

// encodeURIComponent uses RFC 3986 (%20 for spaces)
"q=" + encodeURIComponent("rock & roll")
// → "q=rock%20%26%20roll"

// Both are valid — just be consistent on both ends

Cómo se codifican los datos de formulario en la URL

Cuando un formulario HTML se envía con method="GET", el navegador serializa los campos del formulario en una cadena de consulta usando application/x-www-form-urlencoded. Cada nombre y valor de campo se codifica (espacios como +, caracteres especiales como %XX), y los campos se unen con &. Para formularios con method="POST" sin atributo enctype, se usa la misma codificación pero los datos van en el cuerpo de la petición en lugar de en la URL.

Este es también el formato que usa fetch() cuando pasas un objeto URLSearchParams como cuerpo, y es lo que la mayoría de los frameworks del lado del servidor decodifican automáticamente al leer envíos de formularios.

Base64 en URLs

El Base64 estándar usa + y / — ambos con significados especiales en las URLs. Cuando los datos codificados en Base64 necesitan aparecer en una URL (patrón común para tokens, datos de imagen o firmas criptográficas), usa la variante Base64URL en su lugar. Reemplaza + por - y / por _, produciendo una cadena segura en cualquier posición de la URL sin codificación adicional. Los JWTs utilizan este formato para sus segmentos de encabezado y carga útil.

Errores reales de codificación

Algunos patrones de error que aparecen en aplicaciones en producción:

• Doble codificación — codificar una URL ya codificada. %20 se convierte en %2520 porque el propio % se codifica como %25. Comprueba siempre si un valor ya está codificado antes de volver a codificarlo.
• Falta encodeURIComponent en redirect_uri — los flujos OAuth pasan un redirect_uri como parámetro de consulta. Si contiene un ? o un & y no está codificado, el servidor de autenticación analiza esos caracteres como parte de la estructura de la URL exterior, rompiendo la redirección.
• Codificación distinta de UTF-8 — sistemas antiguos o servidores mal configurados a veces codifican porcentualmente cadenas usando ISO-8859-1 en lugar de UTF-8. La secuencia de bytes para é difiere entre ambos. Aplica UTF-8 de forma consistente en ambos lados.
• Registro de URLs sin procesar — registrar una URL que contiene datos de usuario codificados puede producir registros engañosos si tu visor de logs decodifica automáticamente las secuencias porcentuales, ocultando lo que se envió realmente por la red.

Codifica y decodifica URLs al instante

Ya sea que estés depurando una redirección OAuth, construyendo una cadena de consulta a mano, inspeccionando una petición de API malformada o simplemente intentando entender qué contiene una URL codificada porcentualmente — el Codificador/Decodificador de URL de BrowseryTools lo gestiona al instante. Pega tu cadena, elige codificar o decodificar, y ve el resultado de inmediato. Sin llamadas al servidor, sin registro.