Guía cURL POST Request

curl es una herramienta de línea de comandos para transferir datos utilizando varios protocolos de red. Disponible en los principales sistemas operativos, curl se ha convertido en la herramienta estándar para enviar peticiones HTTP desde la línea de comandos.

La utilidad multiplataforma de curl es compatible con protocolos como HTTP, HTTPS, FTP e IMAP, lo que facilita el envío de peticiones a API y el raspado de sitios web mediante curl. Gracias a su amplia disponibilidad y a su compatibilidad con múltiples protocolos, a menudo encontrará referencias a curl en la documentación de las API REST como una forma rápida de probar las llamadas a las API directamente desde la línea de comandos:

En este artículo, mostraremos cómo enviar peticiones POST utilizando curl desde la línea de comandos.

¿Qué es una petición POST?

Una petición POST es un método HTTP para enviar datos a un servidor y es uno de los métodos HTTP más comunes.

Cuando se envía una petición POST, los datos transmitidos se incluyen en el cuerpo de la petición. Esto permite enviar datos de forma más discreta que enviándolos en la URL (como lo haría con una petición GET). También se puede enviar muchos más datos en una petición POST, eludiendo las restricciones de longitud de URL impuestas por los navegadores para las peticiones GET.

Las peticiones POST se utilizan a menudo para enviar formularios, cargar archivos o enviar datos JSON a una API. En comparación con las peticiones GET, las peticiones POST normalmente no se almacenan en caché y los datos no se muestran en el historial del navegador ya que los datos de la petición están en el cuerpo de la petición.

Cómo enviar una petición POST con curl

Antes de comenzar este tutorial, necesita instalar curl en su ordenador. Ejecute el siguiente comando para comprobar si curl está instalado:

curl --version

Si obtiene un error diciendo que no se puede encontrar el comando, necesita instalar la utilidad.

Instalar curl

A continuación incluimos las instrucciones para instalar curl en los principales sistemas operativos:

Windows

En Windows, se puede utilizar WinGet, el gestor de paquetes predeterminado en Windows 11, para instalar curl:

winget install curl.curl

Chocolatey es otro gestor de paquetes para Windows que permite instalar curl utilizando el siguiente comando:

choco install curl

Linux

curl está disponible en la mayoría de los gestores de paquetes de Linux. Utilice el siguiente comando en Ubuntu/Debian para instalar curl:

apt-get install curl

Red Hat Enterprise Linux (RHEL), CentOS y Fedora permiten instalar curl utilizando el Yellowdog Updater Modified (YUM), de esta forma:

yum install curl

Si está ejecutando OpenSUSE, puede instalar curl utilizando el siguiente comando de terminal:

zypper install curl

Por último, Arch Linux permite usar pacman para instalar curl con este comando:

pacman -Sy curl

macOS

Homebrew es la forma más sencilla de instalar curl en macOS. Asegúrese de tener Homebrew instalado y ejecute el siguiente comando:

brew install curl

Ahora que ha instalado curl en su sistema operativo, puede proceder a aprender a hacer peticiones POST.

Realizar una petición POST

curl permite especificar varias opciones cuando se envían peticiones POST. Las siguientes secciones mostrarán algunas características comunes de curl que puede encontrar al hacer peticiones POST usando la utilidad.

Especificar el método POST

Al realizar peticiones HTTP con curl, debe especificar el método HTTP que desea ejecutar. Los métodos HTTP incluyen GET, POST, PUT y DELETE. curl le permite especificar el método HTTP que desea utilizar utilizando el indicador -X de la línea de comandos.

Por ejemplo, para enviar una solicitud POST a https://httpbin.org/anything, puede ejecutar el siguiente comando curl en su terminal:

curl -X POST https://httpbin.org/anything

httpbin.org se hace eco del cuerpo de la petición y de las cabeceras en la respuesta. La respuesta debería tener este aspecto:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": null,
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

La opción -X POST es equivalente a utilizar la opción --request POST, por lo que también puede ejecutar el siguiente comando y obtener el mismo resultado:

curl --request POST https://httpbin.org/anything

La respuesta tiene el mismo aspecto que la anterior.

Puede obtener más información sobre las opciones -X y and --request en la documentación oficial.

Establecer el tipo de contenido

Cuando envíe una petición POST, es importante especificar el tipo de contenido que está enviando en el cuerpo de la petición para que el servidor pueda interpretar el cuerpo de la petición correctamente. Puede utilizar tipos MIME en la cabecera Content-Type de una petición HTTP para especificar el formato del cuerpo de la petición.

Por ejemplo, si está enviando JSON en el cuerpo de la solicitud, necesita decirle al servidor web que espere contenido JSON estableciendo el encabezado Content-Type como application/json. Si está enviando XML, su cabecera Content-Type debería ser application/xml. Para más información, consulta la documentación oficial sobre Content-Type.

curl permite especificar cabeceras para una petición HTTP utilizando la bandera -H. Por ejemplo, si está enviando JSON en una petición POST, el siguiente comando curl muestra cómo puede establecer la cabecera Content-Type para la petición:

curl -X POST -H 'Content-Type: application/json' -d '{}' https://httpbin.org/anything

En la respuesta, puede ver que la cabecera Content-Type está establecida en application/json:

{
  "args": {},
  "data": "{}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "2",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=-11111111-111111111111111111111111"
  },
  "json": {},
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

La opción -H también puede especificarse utilizando la opción --header. En este caso, su comando curl se vería así:

curl -X POST --header 'Content-Type: application/json' -d '{}' https://httpbin.org/anything

Su respuesta tendría el mismo aspecto que la anterior.

Enviar datos

Puede que haya notado que los comandos anteriores tenían una bandera -d. Esta opción le permite especificar los datos a enviar en el cuerpo de la petición. Puede usar la bandera para pasar cualquier cadena de valores rodeada por comillas, como esto:

curl -X POST -H 'Content-Type: application/json' -d '{
    "FirstName": "Joe", 
    "LastName": "Soap" 
}' https://httpbin.org/anything

Observará que httpbin.org muestra los datos del cuerpo que ha enviado en la propiedad data de la respuesta.

Si tiene un archivo con datos que desea que curl envíe en el cuerpo, especifique el nombre del archivo prefijado con el caracter @. El siguiente comando lee el contenido de body.json y lo envía a través del cuerpo de la petición:

curl -X POST -H 'Content-Type: application/json' -d @body.json https://httpbin.org/anything

En este caso, el archivo body.json contiene lo siguiente:

{
    "FirstName": "Joe",
    "LastName": "Soap"
}

Al enviar esto, httpbin.org debería devolver la siguiente respuesta:

{
  "args": {},
  "data": "{\t\"FirstName\": \"Joe\",\t\"LastName\": \"Soap\"}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "41",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": {
    "FirstName": "Joe",
    "LastName": "Soap"
  },
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

La bandera --data se comporta igual que -d, por lo que puede utilizarlas indistintamente.

Envío de datos JSON

En la sección anterior, vio cómo podía enviar datos JSON configurando el encabezado Content-Type como application/json y, a continuación, pasando los datos JSON mediante la bandera -d. Al enviar una solicitud, también es importante que el servidor web sepa qué formato de datos espera como respuesta. Puede usar la cabecera Accept con el valor application/json para hacer saber al servidor web que quiere recibir una respuesta JSON.

El siguiente comando envía una petición JSON al servidor y le indica que desea recibir JSON como respuesta:

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
    "FirstName": "Joe",
    "LastName": "Soap"
}' https://httpbin.org/anything

Verá que las propiedades data y json del cuerpo de la respuesta contienen los datos JSON que envió en la solicitud:

{
  "args": {},
  "data": "{\n    \"FirstName\": \"Joe\",\n    \"LastName\": \"Soap\"\n}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "application/json",
    "Content-Length": "50",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": {
    "FirstName": "Joe",
    "LastName": "Soap"
  },
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

Enviar y recibir datos JSON es común cuando se envían peticiones HTTP, por lo que curl ofrece una opción --json que establece las cabeceras Content-Type y Accept y envía los datos JSON en el cuerpo de la petición. Usando esta opción, puede acortar su comando para enviar JSON en una petición POST:

curl -X POST --json '{
    "FirstName": "Joe",
    "LastName": "Soap"
}' https://httpbin.org/anything

Esto produce la misma respuesta que antes:

{
  "args": {},
  "data": "{\n    \"FirstName\": \"Joe\",\n    \"LastName\": \"Soap\"\n}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "application/json",
    "Content-Length": "50",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": {
    "FirstName": "Joe",
    "LastName": "Soap"
  },
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

La bandera --json fue lanzada en la versión 7.82 de curl en Marzo de 2022, así que asegúrate de tener instalada la última versión de curl antes de usarla.

Enviar datos XML

curl también le permite enviar datos en otros formatos, como XML. Para enviar datos XML, necesita establecer su cabecera Content-Type como application/xml y pasar los datos XML en el cuerpo de la petición utilizando la bandera -d. También puede indicar al servidor web que espera que la respuesta sea XML estableciendo la cabecera Accept en application/xml.

El siguiente comando muestra cómo puede enviar un objeto XML en una petición POST utilizando curl:

curl -X POST -H 'Content-Type: application/xml' -H 'Accept: application/xml' -d '<Person>
    <FirstName>Joe</FirstName>
    <LastName>Soap</LastName>
</Person>' https://httpbin.org/anything

Encontrará los datos de la petición XML en la propiedad data devuelta por httpbin.org:

{
  "args": {},
  "data": "<Person>\n    <FirstName>Joe</FirstName>\n    <LastName>Soap</LastName>\n</Person>",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "application/xml",
    "Content-Length": "79",
    "Content-Type": "application/xml",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": null,
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

Enviar FormData

Puede utilizar FormData para enviar pares clave-valor de datos a un servidor web. Como su nombre indica, este formato de datos se utiliza al enviar un formulario en una página web. Los pares clave-valor tienen un nombre de campo y un valor.

curl le permite especificar FormData utilizando la bandera -F o --form. Cuando utilice esta opción, especifique el nombre y el valor del campo con el siguiente formato: -F <name=content> o --form <name=content>.

El siguiente fragmento muestra un comando curl que envía una petición POST utilizando FormData con los campos FirstName y LastName:

curl -X POST -F FirstName=Joe -F LastName=Soap https://httpbin.org/anything

Encontrará los nombres y valores de los campos del formulario en la propiedad form del objeto de respuesta httpbin.org:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {
    "FirstName": "Joe",
    "LastName": "Soap"
  },
  "headers": {
    "Accept": "*/*",
    "Content-Length": "248",
    "Content-Type": "multipart/form-data; boundary=------------------------e2bb56049a60b8b8",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": null,
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

Utilice el indicador -F para cada campo que desee enviar al servidor.

Cargar archivos

Puede usar FormData para subir archivos en una petición POST adjuntando el archivo a un campo. Para que curl sepa que un campo FormData contiene un archivo, introduzca la ruta al archivo en el valor del campo precedido del carácter @.

El siguiente comando curl carga un archivo llamado Contract.pdf en su directorio de trabajo. El comando utiliza un campo llamado File para cargar el archivo:

curl -X POST -F [email protected] https://httpbin.org/anything

La respuesta contiene el archivo completo, por lo que es larga, pero debería tener este aspecto:

{
  "args": {},
  "data": "",
  "files": {
    "File": "..."
  },
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "246",
    "Content-Type": "multipart/form-data; boundary=------------------------19ed1fc3be4d30c7",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": null,
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

Enviar credenciales

Muchos endpoints HTTP requieren autenticación para enviar peticiones. El servidor web decide qué método de autenticación debe utilizar. Uno de estos métodos de autenticación es el esquema de autenticación básica, que permite enviar credenciales consistentes en un nombre de usuario y una contraseña en la solicitud. El servidor verifica las credenciales y, si son correctas, procesa la petición.

curl simplifica el envío de credenciales de autenticación básica utilizando la bandera -u o --user. A continuación, especifique el nombre de usuario y la contraseña y sepárelos con : (dos puntos), de esta forma: -u <username:password>.

El siguiente fragmento utiliza curl para enviar una petición POST con credenciales de usuario y un cuerpo JSON:

curl -X POST -u 'admin:password123' --json '{
    "FirstName": "Joe",
    "LastName": "Soap"
}' https://httpbin.org/anything

Observe cómo curl codifica el nombre de usuario y la contraseña y los envía en la cabecera Authorization:

{
  "args": {},
  "data": "{\n    \"FirstName\": \"Joe\",\n    \"LastName\": \"Soap\"\n}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "application/json",
    "Authorization": "Basic YWRtaW46cGFzc3dvcmQxMjM=",
    "Content-Length": "50",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
  },
  "json": {
    "FirstName": "Joe",
    "LastName": "Soap"
  },
  "method": "POST",
  "origin": "0.0.0.0",
  "url": "https://httpbin.org/anything"
}

Conclusión

Este artículo le ha mostrado cómo enviar peticiones POST utilizando la utilidad de línea de comandos curl. Ha aprendido a utilizar el indicador -X para especificar que desea enviar una solicitud POST. También ha establecido las cabeceras Content-Type y Accept utilizando las banderas -H y --header para que el servidor web sepa en qué formato están los datos. Para enviar datos en el cuerpo de la petición, usó la bandera -d junto con los datos que quería enviar.

También vió algunos ejemplos de cómo enviar varios tipos de datos, incluyendo JSON, XML y FormData, y aprendió cómo enviar credenciales básicas de autenticación en su petición usando las banderas -u y --user.

Mientras que este artículo demostró las banderas básicas incluidas en curl y cómo utilizarlas, curl ofrece más características que es posible que desee explorar, incluyendo el uso de variables, el envío de cookies con las solicitudes y el envío de solicitudes utilizando un proxy. Muchos lenguajes de programación también proporcionan librerías que permiten trabajar con curl desde ese lenguaje de programación, incluyendo Python, Node.js, y Rust.

¿Busca una solución de raspado de datos web? Hable con uno de nuestros expertos en datos y vea cuál de nuestros productos se adapta mejor a sus necesidades.