Cada URL que has escrito o hecho clic ha pasado por codificación de URLs. El espacio en “mi archivo.txt” se convierte en %20. El & en una cadena de consulta se convierte en %26. El / en una ruta permanece como / — pero solo porque el codificador sabe qué caracteres son seguros y cuáles no.
La codificación de URLs (oficialmente “codificación con porcentaje”) es la forma en que las URLs representan caracteres que no están en el conjunto de caracteres no reservados. Es una transformación simple, pero los casos extremos son donde viven la mayoría de errores de API.
Los caracteres no reservados
Estos caracteres son siempre seguros en URLs y nunca necesitan codificación:
A-Z a-z 0-9 - _ . ~Todo lo demás — espacios, barras, ampersands, signos iguales, caracteres no ASCII — necesita codificarse como un signo de porcentaje seguido de dos dígitos hexadecimales:
- Espacio →
%20 &→%26=→%3D/→%2F?→%3F#→%23
La codificación son los valores de bytes UTF-8 del carácter, cada uno representado como dos dígitos hexadecimales. Un carácter multibyte como é (UTF-8: 0xC3 0xA9) se convierte en %C3%A9.
Dónde importa la codificación
Parámetros de consulta. Aquí es donde la codificación de URLs causa más errores. Si un valor de consulta contiene & o =, el analizador de URLs divide en esos caracteres y rompe la estructura del parámetro:
/search?q=cats&dogs ← ambiguo: ¿"dogs" es un parámetro separado?
/search?q=cats%26dogs ← correcto: "cats&dogs" es un solo valorCada biblioteca HTTP tiene una función para codificar parámetros de consulta. Úsala. Nunca concatenes cadenas en una cadena de consulta a mano.
Rutas. Los espacios en nombres de archivo necesitan codificación:
/download/my file.pdf ← roto
/download/my%20file.pdf ← funcionaPero las barras dentro de un segmento de ruta también necesitan codificación:
/file/path/segment ← dos segmentos: "file/path" dividido en /
/file%2Fpath/segment ← un segmento: "file/path"Caracteres no ASCII. Las URLs son solo ASCII. Cualquier carácter no ASCII (letras acentuadas, caracteres CJK, emoji) debe codificarse con porcentaje:
café→caf%C3%A9日本語→%E6%97%A5%E6%9C%AC%E8%AA%9E🎉→%F0%9F%8E%89
La mayoría de navegadores muestran la versión decodificada en la barra de direcciones, pero los bytes reales que se envían por la red están codificados.
La trampa de la doble codificación
El error de codificación de URLs más común: codificar una cadena ya codificada.
Toma la ruta /hello%20world. Si la codificas de nuevo en URL, el % se convierte en %25:
/hello%20world ← original (correcto)
/hello%2520world ← doble codificado (roto)El servidor decodifica %25 a %, luego ve %20 y lo decodifica a un espacio. Terminas con /hello world — pero solo si el servidor hace una sola decodificación. Si hace dos decodificaciones (algunas lo hacen), obtienes el original de vuelta. El comportamiento es inconsistente e impredecible.
La regla: codifica una vez, decodifica una vez. Si recibes una cadena codifícala, decodifícala antes de recodificar. Verifica si el constructor de URLs de tu biblioteca HTTP espera valores sin procesar o pre-codificados — la diferencia entre path y rawPath en la mayoría de marcos de trabajo importa.
Codificación de cadena de consulta
Las cadenas de consulta tienen sus propias reglas de codificación. La diferencia clave con las rutas: + representa un espacio en cadenas de consulta (application/x-www-form-urlencoded), pero %20 también representa un espacio. Ambos son válidos, pero provienen de diferentes estándares:
application/x-www-form-urlencoded(envíos de formularios) —+para espacios- Codificación con porcentaje (URLs) —
%20para espacios
La mayoría de APIs modernas aceptan ambos. Pero si estás analizando una cadena de consulta de un envío de formulario, + → espacio. Si estás construyendo una URL, %20 → espacio. Mezclarlos causa errores sutiles donde los espacios se convierten en signos + o viceversa.
Usa la función de codificación de URLs de tu lenguaje. Ella maneja la distinción por ti.
Codificación vs escape
La codificación de URLs no es escape de HTML. Resuelven problemas diferentes:
- Codificación de URLs (
%20) — para caracteres en URLs. Previene que los caracteres se interpreten como sintaxis de URL. - Escape de HTML (
&,<) — para caracteres en HTML. Previene que los caracteres se interpreten como etiquetas o entidades HTML.
Una URL dentro de un href de HTML necesita ambos: codificar los valores de los parámetros con URL, luego codificar toda la URL con HTML:
<a href="/search?q=cats%26dogs&page=1">El %26 evita que & se interprete como separador de consulta. El & evita que & se interprete como inicio de entidad HTML.
Errores comunes
Espacios en diferentes contextos. %20 en una URL, + en el cuerpo de un formulario, %2520 si accidentalmente codificaste doblemente. Sabe en qué contexto estás.
Fragmentos hash. Todo después de # no se envía al servidor. Si codificas una URL con un fragmento y el fragmento contiene ? o &, el servidor nunca los ve. El fragmento es solo para el cliente.
Codificar el signo de porcentaje. % → %25. Si un % literal aparece en tus datos (como una contraseña con %), debe codificarse. Si no lo codificas, el analizador interpreta los dos caracteres después de él como una secuencia hexadecimales.
Normalización Unicode. Algunos sistemas normalizan Unicode antes de codificar. café (con acento combinado) y café (con é precompuesto) codifican a diferentes secuencias de porcentaje. Esto causa problemas con nombres de archivo y dominios internacionalizados.
Referencia rápida
| Carácter | Codificado con porcentaje | Contexto |
|---|---|---|
| Espacio | %20 |
URL |
| Espacio | + |
Cuerpo de formulario |
& |
%26 |
Cadena de consulta |
= |
%3D |
Cadena de consulta |
/ |
%2F |
Segmento de ruta |
? |
%3F |
Cadena de consulta |
# |
%23 |
Ruta/consulta |
% |
%25 |
En todas partes |
+ |
%2B |
Cadena de consulta |
Pruébalo
Si tienes una URL o cadena codificada que necesitas decodificar (o datos sin procesar que necesitas codificar), usa una herramienta local para que la conversión ocurra en tu navegador — sin enviar datos a ningún lugar.