cURL Explicado: Comandos, Banderas y Cómo Convertirlos a Código

Toda API tiene documentación. Casi universalmente, esa documentación incluye ejemplos de código en cURL —la herramienta HTTP de línea de comandos que viene con todos los sistemas tipo Unix y ha sido la lengua franca de la documentación de APIs durante décadas. El problema es que tú no estás escribiendo scripts de shell. Estás escribiendo JavaScript, Python, Go o Ruby, y necesitas traducir ese comando cURL a código funcional antes de poder usarlo.

Esa traducción es tediosa y propensa a errores. Los encabezados, los esquemas de autenticación, los cuerpos de solicitud y la codificación de URLs tienen que mapearse a las llamadas de método correctas en el lenguaje correcto. El Conversor cURL de BrowseryTools hace esto automáticamente —pega un comando cURL y obtén el código equivalente en JavaScript fetch, Python requests, Node.js axios y más. Gratis, sin registro, todo se queda en tu navegador.

¿Qué Es cURL?

cURL (Client URL) es una herramienta de línea de comandos para transferir datos usando URLs. Soporta HTTP, HTTPS, FTP, WebSockets y docenas de otros protocolos. Para los desarrolladores, se usa más comúnmente para hacer solicitudes HTTP desde la terminal —probar un endpoint de API, descargar un archivo o depurar la autenticación.

cURL viene instalado por defecto en macOS y la mayoría de las distribuciones de Linux. En Windows, ha estado incluido con el sistema operativo desde Windows 10. Esta ubicuidad es exactamente por qué los equipos de documentación de APIs recurren por defecto a cURL para los ejemplos —pueden estar seguros de que cualquier desarrollador que lea la documentación puede ejecutar el ejemplo de inmediato, sin instalar nada.

Anatomía de un Comando cURL

Un comando cURL está formado por una URL base y un conjunto de banderas. Aquí tienes un ejemplo completo que cubre las banderas más importantes:

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

Desglosando cada bandera:

• -X POST — establece el método HTTP. Los valores válidos son GET, POST, PUT, PATCH, DELETE, etc. Si se omite y está presente -d, cURL usa POST por defecto.
• -H "Encabezado: Valor" — añade un encabezado de solicitud. Puede repetirse varias veces para múltiples encabezados.
• -d '...' — el cuerpo de la solicitud. Para JSON, combínalo con -H "Content-Type: application/json". cURL codifica el cuerpo por URL por defecto a menos que uses --data-raw.
• --data-raw '...' — envía el cuerpo exactamente como está sin ninguna codificación de URL. Necesario cuando el cuerpo contiene caracteres como @ que -d interpretaría de forma especial.
• -u usuario:contraseña — atajo de autenticación básica. cURL lo codifica como un encabezado de Autorización en Base64 por ti.
• -s — modo silencioso; suprime la barra de progreso. Casi siempre se usa en scripts.
• -v — modo detallado; imprime los encabezados de solicitud y respuesta. Invaluable para depurar fallos de autenticación.
• -o nombre_archivo — escribe la salida en un archivo en lugar de a stdout.

Patrones cURL Comunes para APIs REST

Solicitud GET con Parámetros de Consulta

curl "https://api.example.com/users?page=2&limit=20" \
  -H "Authorization: Bearer TOKEN"

Los parámetros de consulta van directamente en la URL. Pon entre comillas la URL completa para evitar que el shell interprete el & como un operador de proceso en segundo plano.

POST con Cuerpo JSON

curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  --data-raw '{"product_id": 42, "quantity": 3}'

Carga de Archivos (multipart/form-data)

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

La bandera -F envía multipart/form-data. El prefijo @ significa «leer desde archivo». Este es el formato usado para cargas de imágenes, APIs de procesamiento de documentos y cualquier endpoint que acepte datos binarios.

Convertir cURL a JavaScript fetch

// Original cURL:
// curl -X POST https://api.example.com/v1/users \
//   -H "Content-Type: application/json" \
//   -H "Authorization: Bearer TOKEN" \
//   -d '{"name": "Alice", "email": "alice@example.com"}'

const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer TOKEN",
  },
  body: JSON.stringify({
    name: "Alice",
    email: "alice@example.com",
  }),
});

const data = await response.json();

Convertir cURL a Python requests

import requests

response = requests.post(
    "https://api.example.com/v1/users",
    headers={
        "Authorization": "Bearer TOKEN",
    },
    json={
        "name": "Alice",
        "email": "alice@example.com",
    },
)

data = response.json()

El parámetro json= de la biblioteca requests gestiona tanto la serialización como la configuración automática del encabezado Content-Type: application/json —no es necesario establecerlo manualmente.

Convertir cURL a Node.js con axios

const axios = require("axios");

const response = await axios.post(
  "https://api.example.com/v1/users",
  {
    name: "Alice",
    email: "alice@example.com",
  },
  {
    headers: {
      Authorization: "Bearer TOKEN",
    },
  }
);

const data = response.data;

Cómo Funciona «Copiar como cURL» en las DevTools del Navegador

Una de las funciones más útiles en las DevTools del navegador es «Copiar como cURL». En Chrome, Firefox o Safari: abre las DevTools, ve a la pestaña Red, haz una solicitud (inicia sesión, haz clic en un botón, carga una página), haz clic derecho en la solicitud en la lista de red y selecciona «Copiar como cURL».

El navegador genera un comando cURL completo que incluye cada encabezado que el navegador envió —incluyendo cookies, tokens de sesión, tokens CSRF y cualquier otro material de autenticación. Esto significa que puedes reproducir exactamente la solicitud que hizo el navegador, incluido todo su contexto de autenticación, desde la terminal o desde el código.

Esto es invaluable para la depuración: si la solicitud del navegador funciona pero la solicitud de tu código falla, pega ambas en una herramienta de diferencias y encuentra la diferencia de encabezado o cuerpo. También puedes pegar el cURL copiado directamente en el Conversor cURL de BrowseryTools para obtener el código equivalente en tu lenguaje preferido —el conversor maneja automáticamente todo el escapado, las comillas y la traducción de banderas.

Resumen

cURL es el lenguaje universal de HTTP. La documentación de las APIs lo usa porque todos pueden ejecutarlo. Las DevTools lo copian porque captura cada detalle de una solicitud. Aprender a leer cURL con fluidez —y a traducirlo con precisión al lenguaje en el que estás trabajando— es una habilidad práctica que rinde dividendos cada vez que integras una nueva API. Salta la tediosa traducción manual y usa el Conversor cURL de BrowseryTools para obtener código limpio y ejecutable en segundos.