cURL sin complicaciones: construye comandos complejos en segundos

Si llevas más de unos meses como desarrollador, has usado cURL. Probablemente también has buscado en Google "curl post request json" más veces de las que te gustaría admitir. No hay vergüenza en eso — cURL tiene muchas flags, y la sintaxis es lo suficientemente densa como para que incluso los desarrolladores experimentados no la recuerden toda.

Lo que la mayoría de los desarrolladores no se dan cuenta es que solo necesitas entender profundamente quizás una docena de flags para cubrir el 90% de tus necesidades diarias de prueba de API. El resto puedes buscarlo cuando lo necesites, o usar un generador para ensamblar el comando sin memorizar la sintaxis.

Esta guía se enfoca en las partes de cURL que realmente importan, con ejemplos reales que puedes ejecutar hoy.

Por que usar cURL?

Pregunta legítima. Tienes Postman, Insomnia, la extensión REST Client de VS Code, las DevTools del navegador — por qué usar cURL?

Algunas razones:

Siempre está disponible. cURL viene preinstalado en macOS y la mayoría de los sistemas Linux. En un servidor recién instalado, en un contenedor Docker, en la máquina de un colega — cURL está disponible. Postman no.

Es scriptable. Puedes poner un comando cURL en un script bash, un pipeline CI, un cronjob, un Makefile. Se convierte en parte de tu infraestructura. No puedes hacer eso con una herramienta GUI.

Es compartible. Pega un comando cURL en un mensaje de Slack o un issue de GitHub y cualquiera puede ejecutarlo inmediatamente. No se necesitan instrucciones de "aquí te explico cómo recrear esto en Postman".

Es el lenguaje común. La mayoría de la documentación de API muestra ejemplos de cURL. Cuando un colega dice "aquí está la solicitud que está fallando", a menudo enviará un comando cURL. Saber leer cURL es una habilidad que vale la pena tener.

Dicho esto, cURL no siempre es la herramienta correcta. Los flujos de trabajo complejos de múltiples pasos, la inspección visual de respuestas, o cualquier cosa que involucre muchos datos de formulario a menudo es más rápido de gestionar en Postman. Usa la herramienta correcta para el trabajo.

Las flags que realmente usarás

-X — Método HTTP

Por defecto, cURL envía una solicitud GET. Usa -X para cambiar el método:

curl -X POST https://api.example.com/users
curl -X PUT https://api.example.com/users/123
curl -X DELETE https://api.example.com/users/123
curl -X PATCH https://api.example.com/users/123

Una abreviación común: puedes omitir -X POST cuando usas -d para enviar un cuerpo, porque cURL inferirá POST. Pero ser explícito es más claro, especialmente cuando compartes el comando con otros.

-H — Agregar un header

Casi todas las solicitudes API que hagas necesitarán al menos un header. Content-Type para solicitudes POST/PUT, Authorization para endpoints autenticados:

# Establecer tipo de contenido
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json"

# Agregar token de auth
curl https://api.example.com/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# Múltiples headers
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Request-ID: abc123"

Puedes usar -H múltiples veces en el mismo comando, una flag por header.

-d — Cuerpo de la solicitud

Envía datos en el cuerpo de la solicitud. Usado con POST, PUT y PATCH:

# Cuerpo JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Datos de formulario (codificados en URL)
curl -X POST https://api.example.com/login \
  -d "username=alice&password=secret"

Una nota sobre el header Content-Type faltante: si envías -d con JSON pero olvidas -H "Content-Type: application/json", el servidor puede rechazar la solicitud o analizar mal el cuerpo. Este es uno de los errores más comunes de cURL. Siempre establece Content-Type cuando sabes lo que estás enviando.

-L — Seguir redirecciones

Por defecto, si un servidor devuelve una redirección 301 o 302, cURL se detiene y muestra la respuesta de redirección. Normalmente quieres seguirla:

curl -L https://example.com/old-url

Esto surge frecuentemente cuando trabajas con APIs que redirigen HTTP a HTTPS, o cuando un recurso ha sido movido. Sin -L, solo verás 301 Moved Permanently y te preguntarás por qué tu solicitud no devolvió datos.

-i — Incluir headers de respuesta

Por defecto, cURL solo muestra el cuerpo de la respuesta. -i incluye también los headers de respuesta:

curl -i https://api.example.com/users/1

La salida se ve así:

HTTP/2 200
content-type: application/json
x-rate-limit-remaining: 99
...

{"id": 1, "name": "Alice"}

Esto es útil cuando necesitas inspeccionar códigos de estado, Content-Type, headers de caché o información de límite de tasa. -i es la alternativa ligera al modo verbose cuando solo quieres los headers sin toda la salida de debug de conexión.

-v — Modo verbose

Esta es la flag de depuración. -v te muestra todo: los headers de solicitud completos que cURL envió, el handshake TLS y los headers de respuesta completos:

curl -v https://api.example.com/users

Salida de ejemplo (abreviada):

* Trying 93.184.216.34:443...
* Connected to api.example.com (93.184.216.34) port 443
* SSL connection using TLSv1.3
> GET /users HTTP/2
> Host: api.example.com
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/2 200
< content-type: application/json
<
{"users": [...]}

Las líneas que comienzan con > son lo que cURL envió. Las líneas con < son lo que el servidor devolvió. Las líneas con * son los propios mensajes de estado de cURL. Invaluable al depurar problemas de autenticación, headers inesperados o problemas de TLS.

-u — Autenticación básica

Para APIs que usan HTTP Basic Auth, podrías construir manualmente el header Authorization, pero -u lo hace automáticamente:

curl -u username:password https://api.example.com/protected

cURL codifica las credenciales como Base64 y envía el header Authorization: Basic ... apropiado. Una advertencia: si pegas esto en un terminal, tu contraseña aparecerá en el historial de tu shell. Limpia el historial después o usa una variable de entorno:

curl -u "alice:$API_PASSWORD" https://api.example.com/protected

-k — Omitir verificación SSL

Esta merece una palabra de precaución. -k (o --insecure) le dice a cURL que ignore los errores de certificado SSL:

curl -k https://localhost:8443/api/health

Esto es legítimo para el desarrollo local cuando usas un certificado autofirmado. No es legítimo para solicitudes de producción. Si usas -k contra un servicio externo real, estás eludiendo una seguridad que existe por buenas razones. Úsalo solo en desarrollo.

-o y -O — Guardar respuesta en archivo

En lugar de imprimir la respuesta en tu terminal, guárdala:

# Guardar con un nombre de archivo específico
curl -o output.json https://api.example.com/data

# Guardar usando el nombre de archivo remoto
curl -O https://example.com/files/report.pdf

-o te permite elegir el nombre de archivo, -O usa el último segmento de ruta de la URL.

-s — Modo silencioso

Suprime la barra de progreso y los mensajes de error. Útil en scripts donde solo quieres el cuerpo de la respuesta:

curl -s https://api.example.com/status | jq .

Canalizar a jq es un patrón común para imprimir respuestas JSON de forma elegante. -s mantiene la salida limpia para que jq solo reciba el JSON.

Errores comunes

Olvidar Content-Type en solicitudes POST

Esto atrapa a los desarrolladores cada vez. Estás enviando JSON, el servidor devuelve 400 Bad Request o 415 Unsupported Media Type, y pasas 20 minutos depurando antes de darte cuenta de que la solución es agregar un header:

# Header faltante - el servidor puede rechazar esto
curl -X POST https://api.example.com/users \
  -d '{"name": "Alice"}'

# Correcto
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Problemas de comillas en Windows

cURL en el Símbolo del sistema de Windows maneja las comillas de manera diferente a bash. Las comillas simples no funcionan en CMD. Necesitas usar comillas dobles y escapar las comillas internas:

# Windows CMD - usar comillas dobles, escapar las internas
curl -X POST https://api.example.com/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\": \"Alice\"}"

En PowerShell, las comillas simples funcionan pero las reglas de escape son igualmente diferentes. Esta es una de las mayores fuentes de confusión para los desarrolladores de Windows que usan comandos cURL de documentación escrita para sistemas Unix. Si estás en Windows y los comandos cURL de la documentación no funcionan, las comillas generalmente son el culpable.

Enviar un archivo como cuerpo sin usar @

Cuando quieres enviar el contenido de un archivo como cuerpo de la solicitud, usas @nombrearchivo:

# Enviar el contenido de data.json como cuerpo
curl -X POST https://api.example.com/import \
  -H "Content-Type: application/json" \
  -d @data.json

Sin @, cURL trata la cadena como un valor de cuerpo literal, no como un nombre de archivo. Estarías enviando el texto literal data.json en lugar del contenido del archivo.

Usar -d con solicitudes GET

-d envía un cuerpo. Las solicitudes GET no tienen cuerpo (y los servidores generalmente lo ignoran). Si quieres enviar parámetros de consulta con una solicitud GET, ponlos en la URL:

# Correcto para GET con parámetros
curl "https://api.example.com/users?page=1&limit=20"

Nota las comillas alrededor de la URL. Sin ellas, el & en la URL podría ser interpretado por tu shell como un operador de segundo plano.

Juntando todo: ejemplos del mundo real

Crear un usuario:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Bob", "email": "bob@example.com", "role": "editor"}'

Subir un archivo:

curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "description=Q4 Report"

(Nota: -F para datos de formulario multipart, no -d)

Verificar un webhook con carga útil personalizada:

curl -X POST https://your-app.com/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=abc123" \
  -d @sample-push-event.json

Descargar con progreso:

curl -L -o large-file.zip https://example.com/downloads/archive.zip

Usar un generador en lugar de memorizar

Para cualquier cosa más allá de una solicitud GET básica, ensamblar la combinación correcta de flags de memoria se vuelve tedioso. El Constructor de Comandos cURL de ToolPal te permite llenar el método, la URL, los headers y el cuerpo a través de un formulario y genera el comando cURL para ti — que luego puedes copiar directamente a tu terminal o adaptar según sea necesario.

Esto es particularmente útil para:

• Construir comandos con headers de autenticación que nunca has escrito antes
• Obtener la sintaxis correcta para cargas de formularios multipart
• Generar comandos compatibles con Windows cuando estás acostumbrado a bash
• Compartir comandos con compañeros de equipo que pueden no conocer la sintaxis de las flags

Los comandos generados son cURL estándar — sin bloqueo de proveedor, nada propietario. Usas el generador como atajo de productividad, luego llevas el comando resultante donde lo necesitas.

cURL vs otras herramientas

cURL vs Postman: Postman gana para la exploración iterativa de API, gestión de colecciones de solicitudes y colaboración en equipo. cURL gana para scripting, solicitudes rápidas únicas y compartibilidad. No son competidores — la mayoría de los desarrolladores usan ambos.

cURL vs HTTPie: HTTPie es un cliente HTTP de línea de comandos más nuevo con una interfaz más amigable y salida más elegante. Si estás dispuesto a instalarlo, vale la pena echarle un vistazo. cURL tiene la ventaja de estar disponible en todos lados sin instalación.

cURL vs DevTools del navegador: Para inspeccionar lo que tu navegador está enviando realmente (cookies, tokens de sesión, headers complejos), DevTools es insuperable. Incluso puedes hacer clic derecho en una solicitud en la pestaña Network y copiarla como comando cURL — una forma útil de reproducir solicitudes del navegador desde la línea de comandos.

---

cURL recompensa el tiempo que inviertes en aprenderlo. Incluso si nunca memorizas todas las flags, entender cómo funcionan las flags principales — -X, -H, -d, -L, -v — te da una herramienta que funciona en cualquier lugar, se puede escribir en scripts fácilmente y comunica claramente. Eso vale más que cualquier número de patrones de sintaxis memorizados.

En caso de duda, usa un generador. Cuando necesites entender qué salió mal, usa -v.