Petición POST con curl: JSON, cabeceras y formularios

Publicado:

16 min de lectura

Acar Diveroli
Autor: Acar Diveroli
Ventana de terminal con un comando POST de curl, la parte --json en azul, y detrás una tarjeta de respuesta 201 Created

La documentación de una API muestra un comando curl de una sola línea para crear un pedido. Lo pegas, añades tu clave, pulsas Intro y el servidor responde 415 Unsupported Media Type, o 400 con invalid JSON aunque el JSON parece correcto. En el portátil Linux de un compañero, la misma línea funciona. La API no tiene nada de malo: el comando envió un cuerpo distinto o un Content-Type distinto del que crees, y en Windows la shell quitó las comillas de tu JSON antes de que curl llegara a verlo.

Esta guía cubre los datos de formulario con -d, el JSON con --json o con -H más -d, los cuerpos desde archivos, las subidas con -F, las cabeceras y la autenticación, cuándo hace falta -X POST, cómo leer la respuesta y el uso de comillas en cmd y PowerShell. Ejecutamos cada comando con curl 8.22.0 en Windows 11, en cmd y en Windows PowerShell 5.1, contra un pequeño servidor de eco (echo) en nuestra propia máquina que mostraba el método, la cabecera Content-Type y el cuerpo recibido.

¿Qué es una petición POST?

Una petición POST es una petición HTTP que lleva datos en su cuerpo y pide al servidor que haga algo con ellos: crear un pedido, guardar un formulario, iniciar una tarea. RFC 9110, el estándar de HTTP, define POST como una petición para que el recurso de destino procese la representación incluida en la petición según sus propias reglas.

GET solo pide algo y no lleva cuerpo. Además, POST no es idempotente: el mismo POST enviado dos veces puede crear dos pedidos. Si las peticiones, los endpoints y los códigos de estado te resultan nuevos, empieza por ¿Qué es una API y cómo funciona?.

Dos partes de un POST son las que más importan. El cuerpo son los datos. La cabecera Content-Type le dice al servidor cómo leerlos: como campos de formulario, como JSON o como una subida multiparte (multipart). La mayoría de los problemas con POST en curl son un desajuste entre ambos.

¿Cómo envía curl una petición POST?

curl cambia a POST por sí solo cuando le das una opción de cuerpo; tú describes los datos y curl deduce el método:

  1. Añades una opción de cuerpo. -d, --data-binary, --data-urlencode, --json o -F convierten la petición en un POST.
  2. curl elige un Content-Type. La familia -d envía application/x-www-form-urlencoded, --json envía application/json y -F envía multipart/form-data con un delimitador (boundary).
  3. curl prepara el cuerpo. Une varias partes -d con &, quita los saltos de línea de los archivos leídos con -d @ y mantiene los archivos intactos con --data-binary y --json.
  4. Envía la petición. POST /orders HTTP/1.1, las cabeceras, incluidas Content-Length, Content-Type y tus valores de -H, y después el cuerpo.
  5. El servidor lee primero Content-Type. Una API JSON que recibe datos etiquetados como formulario los rechaza con 415 o no consigue analizarlos y responde 400.
  6. curl muestra el cuerpo de la respuesta. El estado y las cabeceras quedan ocultos salvo que los pidas con -i, -v o -w.

¿Qué opción de curl conviene para el cuerpo de la petición?

Elige la opción que coincida con lo que espera el servidor. Esto es lo que recibió nuestro servidor de eco con cada una:

OpciónContent-Type enviadoTratamiento del cuerpoÚsala para
-d / --dataapplication/x-www-form-urlencodedTal cual; @file pierde los saltos de líneaFormularios al estilo HTML
--data-urlencodeapplication/x-www-form-urlencodedValor con codificación porcentualValores con espacios o &
--data-binaryapplication/x-www-form-urlencodedByte a byteArchivos que deben llegar exactos
--jsonapplication/jsonByte a byte, añade AcceptAPI JSON (desde 7.82.0)
-F / --formmultipart/form-dataDividido en partes con nombreSubida de archivos

Todas aparecen en el manual de curl, la referencia de cada opción de esta guía.

¿Cómo se envían datos de formulario con -d?

-d envía una cadena como cuerpo y la etiqueta como datos de formulario, el formato que usa un navegador para un formulario HTML sencillo:

bash
curl -d "name=Ada&city=Paris" https://api.example.com/signup

Nuestro servidor recibió POST, Content-Type: application/x-www-form-urlencoded y name=Ada&city=Paris. Varias opciones -d se unen con &, así que -d "a=1" -d "b=2" llegó como a=1&b=2.

-d envía el texto tal como lo escribes, de modo que un valor con un espacio, & o = se parte en campos equivocados. --data-urlencode codifica el valor por ti:

bash
curl --data-urlencode "q=red shoes & bags" https://api.example.com/search

El servidor recibió q=red+shoes+%26+bags, un único campo con el ampersand intacto. Si un endpoint quiere los campos en la dirección, añade -G: -G -d "q=shoes" -d "page=2" se convirtió en GET /search?q=shoes&page=2 sin cuerpo.

¿Cómo se envía JSON por POST con curl?

Usa --json desde curl 7.82.0, o pon la cabecera tú mismo en versiones anteriores. -d por sí solo nunca dice «esto es JSON»:

bash
# Incorrecto para la mayoría de las API JSON: cuerpo JSON con etiqueta de formulario
curl -d '{"sku":"A-100","qty":2}' https://api.example.com/orders

# Funciona en cualquier versión de curl
curl -H "Content-Type: application/json" -d '{"sku":"A-100","qty":2}' https://api.example.com/orders

# Desde curl 7.82.0
curl --json '{"sku":"A-100","qty":2}' https://api.example.com/orders

En nuestra máquina de pruebas, el primer comando llegó como application/x-www-form-urlencoded y nuestro endpoint de prueba, que solo acepta JSON, lo rechazó con 415. El segundo llegó como application/json con Accept: */*; el tercero, además, con Accept: application/json, y el endpoint respondió 201 Created.

--json equivale a --data-binary más esas dos cabeceras, y una cabecera que pongas con -H sustituye a la que añadiría curl. Comprueba tu versión con curl --version: Ubuntu 22.04, por ejemplo, trae curl 7.81.0, una versión antes de --json, así que los scripts para servidores antiguos deberían mantener la forma con -H.

¿Cómo se envía JSON desde un archivo?

Pasa el archivo con @: --json @order.json en versiones nuevas y --data-binary @order.json con una cabecera Content-Type en las antiguas. Evita -d @order.json cuando los bytes deban llegar exactos:

bash
curl --json @order.json https://api.example.com/orders
curl -H "Content-Type: application/json" --data-binary @order.json https://api.example.com/orders

Con un order.json de cuatro líneas, -d @order.json entregó 29 bytes en una sola línea, porque curl quita los retornos de carro y los saltos de línea de los archivos leídos así. --data-binary y --json entregaron los 33 bytes. A un analizador de JSON le da igual, pero a una petición firmada o a un archivo CSV no.

Un archivo también acaba con la mayoría de los problemas de comillas, porque la shell nunca toca el JSON. @- lee el cuerpo desde la entrada estándar, así que un script puede generarlo: python make_order.py | curl --json @- https://api.example.com/orders.

¿Cómo se añaden cabeceras a una petición POST de curl?

Da a cada cabecera su propio -H "Name: value" y repite la opción tantas veces como necesites:

bash
curl --json @order.json \
  -H "Idempotency-Key: 7f3c9a10" \
  -H "X-Request-Source: nightly-sync" \
  https://api.example.com/orders

Una cabecera que defines sustituye a la cabecera propia de curl con el mismo nombre; así se cambian Accept o User-Agent. Un valor vacío la elimina: con -H "Content-Type:" nuestro servidor no recibió ningún Content-Type.

Las cabeceras de -H se vuelven a enviar tras una redirección. curl retiene Authorization y Cookie cuando la redirección lleva a otro host, pero una clave en una cabecera como X-API-Key viaja con ella, así que ten cuidado al añadir -L.

¿Cómo se sube un archivo con curl -F?

Usa -F con @ delante del nombre del archivo. curl envía entonces multipart/form-data, el formato de un formulario HTML con un campo de archivo:

bash
curl -F "title=Q3 report" -F "file=@report.pdf" https://api.example.com/uploads

Cada -F se convierte en una parte con nombre. Subimos un archivo de texto, report.txt, y nuestro servidor vio una parte de texto title y una parte de archivo file con filename="report.txt" y Content-Type: text/plain, que curl dedujo de la extensión. Indica el tipo cuando la deducción falle: -F "file=@scan.bin;type=application/pdf".

< en lugar de @ mete el contenido de un archivo en un campo de texto normal, como en -F "notes=<notes.txt". -F y -d no se pueden combinar: nuestro curl se detuvo con You can only select one HTTP request method! antes de enviar nada. El nombre del campo debe coincidir con la documentación de la API.

¿Cómo se autentica una petición POST con curl?

Envía lo que pida la API: -u user:pass para la autenticación Basic o una cabecera Authorization para un token. Con -u user:pass nuestro servidor recibió Authorization: Basic dXNlcjpwYXNz, que es solo la forma Base64 de user:pass, así que úsalo únicamente sobre HTTPS.

Para un token bearer, léelo desde una variable de entorno para que no quede en el historial de la shell:

bash
export API_TOKEN="tu-token"
curl --json @order.json -H "Authorization: Bearer $API_TOKEN" https://api.example.com/orders

--oauth2-bearer "$API_TOKEN" genera la misma cabecera. Algunas API quieren la clave en una cabecera propia, como X-API-Key.

¿Cuándo hace falta -X POST?

Casi nunca si hay una opción de cuerpo. Con -v, nuestro curl mostró Note: Unnecessary use of -X or --request, POST is already inferred. para -X POST -d "x=1"; el manual explica que -X solo cambia la palabra de la línea de petición. Sirve para otros métodos con cuerpo: curl -X PUT --json '{"qty":3}' ... llegó como un PUT con el JSON.

-X se vuelve dañino con -L (seguir redirecciones). Enviamos un POST a una dirección que respondía 302 Found:

  • Con -L -d "x=1", curl siguió con un GET sin cuerpo, como describe el manual para 301, 302 y 303.
  • Con -L -X POST -d "x=1", la siguiente petición fue un POST con el cuerpo vacío: el método quedó forzado, los datos no.
  • Con -L --post302 -d "x=1", la siguiente petición fue un POST con el cuerpo original.

Por eso, cuando un POST deba sobrevivir a una redirección, usa --post301, --post302 o --post303, o envíalo directamente a la dirección final.

¿Cómo se ven el estado y las cabeceras de la respuesta?

Añade -i para la línea de estado y las cabeceras de la respuesta, -v para la petición y la respuesta, o -w solo para los valores que elijas:

bash
curl -i --json @order.json https://api.example.com/orders
curl -s -o /dev/null -w "%{http_code}\n" --json @order.json https://api.example.com/orders

El primero mostró HTTP/1.1 201 Created antes del JSON. El segundo mostró solo 201: -s oculta el indicador de progreso y -o /dev/null descarta el cuerpo (-o NUL en Windows). "%{http_code} %{content_type} %{time_total}s\n" nos devolvió 201 application/json 0.001347s.

En los scripts, añade --fail-with-body: curl termina con error ante un estado 400 o superior, pero sigue mostrando el mensaje del servidor. Para una petición que se comporta de forma extraña, usa -v; las líneas que empiezan por > son exactamente lo que curl envió.

¿Cómo se escriben comandos POST de curl en Windows?

Windows 10 y 11 incluyen curl de verdad como curl.exe, pero en Windows PowerShell 5.1 la palabra curl es un alias del cmdlet Invoke-WebRequest. En nuestra máquina, curl -d "x=1" ... escrito en PowerShell 5.1 falló con A positional parameter cannot be found that accepts argument 'x=1'. Escribe curl.exe, como también recomienda la página de curl sobre la versión de Windows.

El problema mayor son las comillas. El JSON entre comillas simples, la forma que usan todos los ejemplos de Linux, se comporta de manera distinta en cada shell:

ShellForma que funcionóLo que envió la forma ingenua
cmd.exe-d "{\"sku\":\"A-100\"}"'{sku:A-100}'
PowerShell 5.1--json '{\"sku\":\"A-100\"}'{sku:A-100}
PowerShell 7.3+--json '{"sku":"A-100"}'Sin probar aquí
Cualquier shell--json "@order.json"El archivo, sin cambios

En cmd, las comillas simples no delimitan nada, así que pasaron a formar parte del cuerpo y las comillas dobles internas desaparecieron. En PowerShell 5.1, '{"sku":"A-100","qty":2}' llegó a nuestro servidor como {sku:A-100,qty:2} y el endpoint JSON respondió 400. Escapar cada comilla interna como \" resolvió los dos casos.

La referencia about_Parsing de Microsoft explica por qué: PowerShell 7.3 cambió la forma en que los argumentos con comillas incrustadas llegan a programas como curl.exe, un cambio incompatible respecto a 5.1. PowerShell 7 no estaba instalado en nuestra máquina de pruebas, así que esa fila sigue la documentación. En PowerShell, pon entre comillas todo lo que empiece por @, como "@order.json"; en un archivo por lotes .cmd, escribe %%{http_code} para -w. El hábito más seguro en Windows es el archivo: a la shell no le queda nada que romper.

¿Cómo se envía una petición POST de curl a través de un proxy?

Añade -x con la dirección del proxy; las opciones de cuerpo no cambian:

bash
curl -x http://user:pass@pr.proxynet.io:8000 \
  --json @order.json https://api.example.com/orders

Con un destino HTTPS, curl pide primero al proxy un túnel CONNECT y luego envía el POST dentro de la conexión cifrada, así que el proxy ve el nombre del host pero no tu JSON. SOCKS5, las variables de entorno y .curlrc se explican en cURL con proxy.

Un proxy ayuda cuando la petición tiene que salir de una dirección o de un país concretos, por ejemplo para ver cómo responde tu propio proceso de pago a un comprador de otra región. Los Proxies HTTPS aceptan exactamente estas opciones, con usuario y contraseña o con la IP de tu servidor en la lista de IP autorizadas.

Cuando la prueba necesita conexiones domésticas en un país o una ciudad elegidos, los Proxies residenciales usan la misma línea -x, con el país y la sesión en el nombre de usuario.

¿Dónde se usan las peticiones POST de curl?

Los desarrolladores prueban una API con un POST de curl antes de escribir código, porque el comando no oculta nada. Los equipos de soporte piden el comando curl que falla, ya que reproduce el problema en cualquier máquina. Los receptores de webhooks se prueban enviando un evento de ejemplo a tu propio endpoint. Los scripts de despliegue llaman a API internas para lanzar tareas o publicar versiones, y las tareas de monitorización envían un pedido de prueba a un sistema de staging y avisan cuando la respuesta deja de ser 201.

Errores comunes de POST en curl y cómo resolverlos

  • 415 Unsupported Media Type. JSON enviado con -d y etiqueta de formulario. Usa --json o -H "Content-Type: application/json".
  • 400 Bad Request con un error al analizar el JSON. Comillas eliminadas por la shell o una errata en el JSON. Compruébalo con -v o pasa el JSON a un archivo.
  • El POST llega como GET. Una redirección 301, 302 o 303 con -L. Envía a la URL final o usa las opciones --post30x.
  • Cuerpo vacío tras una redirección. -X POST con -L; quita -X.
  • 401 o 403. Token ausente o incorrecto, o $API_TOKEN vacío en esta shell. Muestra primero la variable.
  • A positional parameter cannot be found. curl en PowerShell 5.1 llamó a Invoke-WebRequest; escribe curl.exe.
  • Parte de una cabecera se trata como una segunda dirección. -H Content-Type: application/json sin comillas se parte en el espacio. Pon entre comillas cada valor de -H.
  • --json se rechaza como opción desconocida. curl anterior a 7.82.0; usa -H más --data-binary.

Guía de decisión

NecesidadRecomendación
Enviar campos de formulario-d "a=1" -d "b=2"
Valor de formulario con espacios o &--data-urlencode
Enviar JSON, curl 7.82.0 o posterior--json @file.json
Enviar JSON, curl más antiguo-H "Content-Type: application/json" --data-binary @file.json
Subir un archivo-F "file=@name.ext"
Autenticación con token-H "Authorization: Bearer $API_TOKEN"
PUT o PATCH con cuerpo-X PUT --json ...
POST que debe sobrevivir a una redirección-L --post302 (o 301/303)
Solo el código de estado-s -o /dev/null -w "%{http_code}\n"
JSON en Windowscurl.exe con un archivo y @

Preguntas frecuentes

¿Cómo envío una petición POST con curl?

Dale un cuerpo a curl y enviará un POST: curl -d "name=Ada" https://api.example.com/form para datos de formulario, o curl --json '{"name":"Ada"}' https://api.example.com/users para JSON. -X POST no hace falta.

¿Qué diferencia hay entre -d y --json en curl?

Cambia la etiqueta. -d envía Content-Type: application/x-www-form-urlencoded y quita los saltos de línea de los archivos; --json envía Content-Type: application/json más Accept: application/json y mantiene los archivos intactos. --json requiere curl 7.82.0 o posterior.

¿Cómo envío un archivo JSON por POST con curl?

Usa curl --json @data.json https://api.example.com/items. Con un curl anterior a 7.82.0, usa -H "Content-Type: application/json" --data-binary @data.json. Evita -d @data.json cuando importen los bytes exactos.

¿Cómo veo las cabeceras de respuesta de una petición POST de curl?

Añade -i para mostrar la línea de estado y las cabeceras antes del cuerpo, o -v para ver juntas las cabeceras de la petición y de la respuesta. Para obtener solo el código de estado, usa -s -o /dev/null -w "%{http_code}".

¿Por qué mi POST de curl funciona en Linux pero falla en PowerShell?

En Windows PowerShell 5.1, curl significa Invoke-WebRequest, y la versión 5.1 elimina las comillas dobles de dentro de un JSON entre comillas simples antes de que lo reciba curl.exe. Escribe curl.exe, escapa las comillas internas como \" o pasa el JSON desde un archivo.

¿Cómo convierto un comando POST de curl a Python?

Traduce cada parte: --json pasa a ser json=, -d pasa a ser data=, -H pasa a ser headers= y -F pasa a ser files=. Tienes la correspondencia completa con ejemplos probados en POST con JSON en Python Requests.

En resumen

curl envía un POST en cuanto tiene un cuerpo: -d para datos de formulario, --json para JSON desde la versión 7.82.0, -H "Content-Type: application/json" con --data-binary en versiones anteriores y -F para subidas. La mayoría de los fallos vienen de la etiqueta, no de los datos: el JSON enviado como formulario devuelve 415, -d @ pierde los saltos de línea y -X POST con -L envía un POST vacío tras una redirección. Comprueba lo que salió con -v. En Windows, escribe curl.exe y guarda el JSON en un archivo; cuando la petición tenga que salir de una dirección o de un país concretos, añade -x y deja el resto igual.