Codificación de URLs y cadenas de consulta: Guía práctica

Las URLs solo permiten un conjunto limitado de caracteres en la ruta y la consulta. Todo lo demás debe estar codificado con porcentaje (por ejemplo, espacio → %20, & → %26). Si esto no se hace correctamente, se producen errores 404, etiquetas de analítica rotas y bugs sutiles en las APIs.

¿Qué se codifica?

• Los valores de consulta que contienen espacios, &, =, # o texto no ASCII (emojis, acentos) deben codificarse.
• Los segmentos de ruta con barras u otros caracteres especiales también necesitan codificación; de lo contrario, el router interpreta mal dónde termina un segmento.

Los navegadores suelen mostrar una URL "legible" en la barra de direcciones mientras envían la forma codificada al servidor. Las APIs, en cambio, esperan que codifiques de forma explícita cuando construyes cadenas manualmente.

encodeURIComponent vs encodeURI

En JavaScript:

• encodeURIComponent — Úsalo para valores de parámetros de consulta (y generalmente también para las claves). Codifica prácticamente todo lo que podría romper una URL.
• encodeURI — Úsalo para una URL completa solo cuando necesites preservar delimitadores como ? y #. Es poco frecuente en el trabajo diario con APIs.

const q = "hello world & friends";
const params = new URLSearchParams({ q });
console.log(params.toString()); // q=hello+world+%26+friends

URLSearchParams gestiona la codificación para consultas con formato estándar application/x-www-form-urlencoded y es preferible a la concatenación manual de cadenas.

Construir URLs con muchos parámetros

Al agregar etiquetas UTM, filtros o claves de API, los errores se acumulan: ? duplicados, & sin codificar u orden ambiguo. Un pequeño helper —o un constructor visual— mantiene la cadena final válida.

Prueba nuestra herramienta URL Encode / Decode para inspeccionar cómo cambian las cadenas, y el URL & Query String Builder para armar un enlace completo con codificación UTF-8 segura.

cURL y fetch

Al copiar solicitudes desde las herramientas de desarrollo del navegador, presta atención a las cadenas de consulta ya codificadas. Al pegarlas en código a veces se produce una doble codificación de los valores. Nuestro conversor cURL to fetch() te ayuda a transformar un cURL funcional a JavaScript mientras verificas la URL por separado.

Si un enlace "funciona en Chrome" pero falla en tu script, compara la cadena de consulta sin procesar byte a byte.

Lista de verificación rápida

• Codifica los valores antes de concatenarlos en ?a=...&b=...
• Prefiere URL + URLSearchParams sobre la construcción manual de cadenas
• Para nombres de dominio internacionalizados (IDN), el navegador gestiona el punycode en el hostname; enfoca la codificación en la ruta y la consulta