---
title: "Petición POST con curl: JSON, cabeceras y formularios"
description: "Para enviar una petición POST con curl, usa -d para formularios, --json para JSON y -H para cabeceras. Ejemplos probados: archivos, subidas, auth y Windows."
url: https://proxynet.io/es/blog/curl-post-request
date: 2026-11-19
author: "Acar Diveroli"
category: "Tutoriales"
lang: es
---

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

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.

> **Nota: Respuesta breve**
>
> curl envía un POST en cuanto le das un cuerpo. `curl -d "name=Ada" https://api.example.com/form` envía datos de formulario como `application/x-www-form-urlencoded`; `curl --json '{"sku":"A-100"}' https://api.example.com/orders` envía JSON con `Content-Type: application/json` y `Accept: application/json` (desde curl 7.82.0; en versiones anteriores usa `-H "Content-Type: application/json" -d '...'`). Añade cabeceras con `-H`, lee un cuerpo desde un archivo con `--json @file.json`, sube archivos con `-F "file=@report.pdf"` y consulta el estado con `-i` o `-w "%{http_code}"`. `-X POST` no hace falta. En Windows PowerShell 5.1, escribe `curl.exe` y escapa las comillas dobles internas como `\"`, o guarda el JSON en un archivo.

## ¿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](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.3) 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?](/es/blog/what-is-an-api).

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ón | Content-Type enviado | Tratamiento del cuerpo | Úsala para |
|---|---|---|---|
| `-d` / `--data` | `application/x-www-form-urlencoded` | Tal cual; `@file` pierde los saltos de línea | Formularios al estilo HTML |
| `--data-urlencode` | `application/x-www-form-urlencoded` | Valor con codificación porcentual | Valores con espacios o `&` |
| `--data-binary` | `application/x-www-form-urlencoded` | Byte a byte | Archivos que deben llegar exactos |
| `--json` | `application/json` | Byte a byte, añade `Accept` | API JSON (desde 7.82.0) |
| `-F` / `--form` | `multipart/form-data` | Dividido en partes con nombre | Subida de archivos |

Todas aparecen en el [manual de curl](https://curl.se/docs/manpage.html), 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](https://curl.se/windows/microsoft.html).

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:

| Shell | Forma 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](https://learn.microsoft.com/es-es/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5) 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](/es/blog/curl-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](https://proxynet.io/es/https-proxy) 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](https://proxynet.io/es/residential-proxy) 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

| Necesidad | Recomendació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 Windows | `curl.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](/es/blog/python-requests-post-json).

## 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.
