¿Odias los anuncios? Ir Sin publicidad Hoy 

Codificación de URL ¿Qué se escapea y por qué tu API se rompe sin ello?

Publicado el 25 abr. 2026

Codificación URL: ¿Qué se escapea y por qué tu API se rompe sin ello 1

Tu llamada a la API parecía correcta. El punto final coincidía, los encabezados eran correctos y la respuesta devolvía 400 Solicitado incorrectamente. Después de veinte minutos de mirarla, descubres el problema: una dirección de correo en la cadena de consulta que contenía un + signo — que el servidor decodificó como un espacio. Eso es el codificación por porcentaje, y rompe cosas de maneras que son realmente difíciles de depurar.

Este guía explica qué hace realmente la codificación por porcentaje, qué caracteres deben codificarse en qué contextos, el truco de JavaScript que todos enfrentan, y cómo usar una herramienta como la Codificador/Decodificador de URL para verificar tu trabajo.

Qué hace realmente la codificación URL

Una URL solo puede contener un subconjunto de caracteres ASCII. Todo lo demás — espacios, caracteres internacionales, símbolos con significado especial en URLs — debe convertirse en un formato seguro antes de su transmisión.

La codificación por porcentaje lo hace reemplazando cada byte inseguro con un signo por ciento seguido de dos dígitos hexadecimales. Un espacio se convierte en %20, un hash se convierte en %23, un slash se convierte en %2F. El nombre proviene de ese signo por ciento inicial.

La especificación (RFC 3986) define "caracteres no reservados" que nunca necesitan codificación: letras (A-Z, a-z), dígitos (0-9) y cuatro símbolos: - _ . ~. Todo lo demás es un carácter reservado (utilizado para delimitar la estructura de la URL) o debe ser codificado.

Los caracteres que rompen APIs

Aquí están los que causan más daño en la práctica:

Carácter	Codificado	Contextos que requieren codificación	Notas
Espacio	%20	Todos los contextos	También codificado como `+` en datos de formulario — véase a continuación
&	%26	Valores en la cadena de consulta	Separa parámetros de consulta; debe codificarse dentro del valor
=		Valores en la cadena de consulta	Separa clave de valor; codifícalo dentro del valor mismo
+		Valores en la cadena de consulta	Decodificado como espacio en codificación de formulario — usa `%2B` para un más literal
#	%23	Ruta, cadena de consulta	Marca el fragmento; todo lo que sigue no se envía al servidor
?		Segmentos de ruta, valores de consulta	Inicia la cadena de consulta; codifícalo en la ruta o en los valores
/		Segmentos de ruta (cuando son literales)	Separa segmentos de ruta; codifícalo dentro del valor del segmento
@	%40	Valores en la cadena de consulta	Las direcciones de correo en parámetros de consulta deben tener esto codificado

Tres contextos, reglas diferentes

La parte de la URL que estás codificando cambia qué necesita escaparse.

URL completa — Cuando tienes una URL completa para pasarla, quieres preservar su estructura. Los guiones, signos de pregunta y signos de hash permanecen sin cambios. Solo los caracteres fuera del conjunto permitido se codifican.

Valor de cadena de consulta — Aquí es donde más errores en APIs suelen vivir. Cada valor en una cadena de consulta debe ser codificado para que los caracteres utilizados para estructurar la consulta (&, =, #, +) no aparezcan literalmente en el valor. Si el nombre del usuario es "John & Jane", la cadena de consulta debe leer name=John%20%26%20Jane, no name=John & Jane (que el servidor interpreta como dos parámetros separados).

Segmento de ruta — Un segmento de ruta es la parte entre barras. Si un segmento contiene una barra (por ejemplo, un nombre de archivo con una barra), debe ser codificado como %2F. Algunos servidores tratan %2F en una ruta como una preocupación de seguridad; conoce bien tu backend antes de usarlo.

encodeURI vs encodeURIComponent — El truco de JavaScript

JavaScript te ofrece dos funciones de codificación integradas, y usar la incorrecta es un error muy común.

// encodeURI — encodes a full URL
// Preserves: : / ? # [ ] @ ! $ & ' ( ) * + , ; =
encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
// Note: & and = are NOT encoded — the query structure is preserved

// encodeURIComponent — encodes a single value
// Encodes everything except: A-Z a-z 0-9 - _ . ! ~ * ' ( )
encodeURIComponent("hello world&lang=en")
// → "hello%20world%26lang%3Den"
// Note: & and = ARE encoded — safe to use as a query value

// The bug: using encodeURI on a value
encodeURI("hello world&lang=en")
// → "hello%20world&lang=en"  ← & survives! Server sees two parameters.

// The correct approach for building query strings
const name = "John & Jane"
const email = "john+jane@example.com"
const url = `https://api.example.com/users?name=${encodeURIComponent(name)}&email=${encodeURIComponent(email)}`
// → "https://api.example.com/users?name=John%20%26%20Jane&email=john%2Bjane%40example.com"

Regla general: usa encodeURIComponent en valores individuales antes de colocarlos en una URL. Usa encodeURI solo cuando tengas una URL completa y quieras limpiarla sin destruir su estructura.

El signo +: Codificación de formularios vs Codificación por porcentaje

Cuando un formulario HTML se envía con method="GET", los navegadores codifican los datos usando application/x-www-form-urlencoded. En este formato, los espacios se convierten en + en lugar de %20. Muchos frameworks de servidor (PHP, Django, Rails) decodifican automáticamente + como un espacio en cadenas de consulta.

Esto crea un problema cuando el valor contiene realmente un signo más — por ejemplo, un número de teléfono como +44 7700 900000. Si lo pasas como +44..., el servidor decodifica el signo más inicial como un espacio y obtiene 44.... La solución es codificar un signo más literal como %2B, que permanece intacto en ambos esquemas de decodificación.

Para el trabajo moderno con APIs, utiliza %20 para espacios (lo que produce encodeURIComponent ) en lugar de depender de +.

Codificación doble: cuando la codificación va mal

La codificación doble ocurre cuando se codifica algo que ya está codificado. El signo por ciento en %20 se convierte en %2520 — el servidor decodifica %25 a un signo por ciento literal, dándote la cadena %20 en lugar de un espacio.

Esto suele aparecer cuando:

Almacenas una URL en una base de datos y la codificas nuevamente antes de usarla
Un framework o biblioteca codifica valores que ya has codificado manualmente
Estás construyendo una URL que contiene otra URL como parámetro

Para evitarlo: codifica exactamente una vez, en el punto en que compones la URL. Si no estás seguro de si un valor ya está codificado, decodifícalo primero (con decodeURIComponent), luego recodifícalo correctamente.

Depuración de codificación URL en DevTools

Cuando una solicitud a una API se comporta inesperadamente, abre DevTools (F12), ve la pestaña de Redes y haz clic en la solicitud fallida. Bajo Encabezados, encuentra la URL de la solicitud — el navegador la muestra en su forma bruta después de codificarla. Bajo Carga, puedes ver los parámetros de consulta decodificados de vuelta a sus valores originales, lo que facilita identificar si un ampersand fue interpretado como un separador o pasó como literal.

Para pruebas manuales, una herramienta en línea de codificación y decodificación de URLs te permite pegar una cadena y ver exactamente qué forma codificada tiene — útil para verificar valores antes de incorporarlos en una solicitud. El IO Tools Codificador/Decodificador de URLs maneja ambas direcciones y te muestra el resultado inmediatamente.