Guia de pedidos POST com curl

Saiba mais sobre o pedido POST com cURL, o que é, como enviar um pedido POST com cURL e muito mais.
12 min read
curl post request guide

curl é uma ferramenta de linha de comandos para transferir dados utilizando vários protocolos de rede. Disponível em todos os principais sistemas operativos, curl tornou-se a ferramenta padrão para enviar pedidos HTTP a partir da linha de comandos.

O serviço multiplataforma de curl suporta protocolos como HTTP, HTTPS, FTP e IMAP, facilitando o envio de pedidos para APIs e a raspagem de sítios web utilizando curl. Com sua ampla disponibilidade e suporte a vários protocolos, você encontrará frequentemente curl referenciado na documentação da API REST como uma maneira rápida de testar chamadas de API diretamente da linha de comando:

aprenda a enviar pedidos POST utilizando curl a partir da linha de comando

Neste artigo, você aprenderá como enviar pedidos POST usando curl a partir da linha de comando.

O que é um pedido POST

Um pedido POST é um dos métodos HTTP mais comuns e serve para enviar dados para um servidor.

Quando se envia um pedido POST, os dados transmitidos são incluídos no corpo do pedido. Isto permite-lhe enviar dados de forma mais discreta do que se os enviasse no URL (como faria com um pedido GET). Também pode enviar significativamente mais dados num pedido POST, contornando as restrições de comprimento de URL impostas pelos navegadores para pedidos GET.

É frequente encontrar pedidos POST utilizados para submeter formulários, carregar ficheiros ou enviar dados JSON para uma API. Em comparação com GET, os pedidos POST não são normalmente armazenados em cache e os dados não são mostrados no histórico do navegador, uma vez que os dados do pedido estão no corpo do pedido.

Como enviar um pedido POST com curl

Antes de começar este tutorial, é necessário instalar curl no seu computador. Execute o seguinte comando para verificar se curl está instalado:

curl --version

Se receber um erro a indicar que o comando não foi encontrado, tem de instalar o utilitário.

Instalar curl

Seguem-se as instruções sobre como instalar curl em todos os principais sistemas operativos:

Windows

No Windows, pode utilizar WinGet, o gestor de pacotes predefinido no Windows 11, para instalar curl:

winget install curl.curl

Chocolatey é outro gerenciador de pacotes para Windows que permite instalar curl usando o seguinte comando:

choco install curl

Linux

curl está disponível na maioria dos gerenciadores de pacotes de Linux. Em Ubuntu/Debian, use o seguinte comando para instalar curl:

apt-get install curl

Red Hat Enterprise Linux (RHEL), CentOS e Fedora permitem instalar curl usando o Yellowdog Updater Modified (YUM), assim:

yum install curl

Se estiver a correr OpenSUSE, pode instalar curl usando o seguinte comando no terminal:

zypper install curl

Finalmente, Arch Linux permite-lhe usar o pacman para instalar curl com este comando:

pacman -Sy curl

macOS

Homebrew é a maneira mais fácil de instalar curl no macOS. Certifique-se de que tem Homebrew instalado e, em seguida, execute o seguinte comando:

brew install curl

Agora que instalou curl no seu sistema operativo, está pronto para aprender a fazer pedidos POST.

Fazer um pedido POST

curl permite-lhe especificar várias opções quando envia pedidos POST. As secções seguintes mostrarão algumas características comuns de curl com que se poderá deparar ao fazer pedidos POST utilizando o utilitário.

Especificar o método POST

Ao efetuar pedidos HTTP utilizando curl, é necessário especificar o método HTTP que pretende executar. Os métodos HTTP incluem GET, POST, PUT e DELETE. curl permite-lhe especificar o método HTTP que pretende utilizar utilizando o sinalizador de linha de comando -X.

Por exemplo, para enviar um pedido POST para https://httpbin.org/anything, pode executar o seguinte comando curl no seu terminal:

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

httpbin.org faz eco do corpo do pedido e dos cabeçalhos na resposta. A sua resposta deve ser semelhante a esta:

{
  "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"
}

O sinalizador -X POST é o equivalente à utilização do sinalizador --request POST, pelo que também pode executar o seguinte comando e obter o mesmo resultado:

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

A resposta tem o mesmo aspeto que a anterior.

Pode ler mais sobre os sinalizadores -X e --request na documentação oficial.

Definir o Content-Type

Ao enviar um pedido POST, é importante especificar o tipo de conteúdo que está a enviar no corpo do pedido para que o servidor possa interpretar corretamente o corpo do pedido. É possível utilizar tipos MIME no cabeçalho Content-Type num pedido HTTP para especificar o formato do corpo do pedido.

Por exemplo, se estiver a enviar JSON no corpo do pedido, tem de dizer ao servidor web para esperar conteúdo JSON, definindo o cabeçalho Content-Type como application/json. Se estivesse a enviar XML, o cabeçalho Content-Type deveria ser application/xml. Para obter mais informações, consulte a documentação oficial sobre Content-Type.

curl permite-lhe especificar cabeçalhos para um pedido HTTP utilizando o sinalizador -H. Por exemplo, se estiver a enviar JSON num pedido POST, o seguinte comando curl mostra como pode definir o cabeçalho Content-Type para o pedido:

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

Na resposta, pode ver o cabeçalho Content-Type definido como 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"
}

O sinalizador -H também pode ser especificado utilizando o sinalizador --header mais longo. Neste caso, o seu comando curl seria parecido com isto:

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

A sua resposta seria igual à anterior.

Enviar dados

Deve ter reparado que os comandos anteriores tinham um sinalizador -d. Este sinalizador permite-lhe especificar os dados a enviar no corpo do pedido. Pode utilizar o sinalizador para passar qualquer cadeia de valores rodeada de aspas, da seguinte forma:

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

Verá que httpbin.org mostra os dados do corpo que enviou na propriedade data da resposta.

Se tiver um ficheiro com dados que pretende que curl envie no corpo, especifique o nome do ficheiro prefixado com o carácter @. O seguinte comando lê o conteúdo de body.json e envia-o através do corpo do pedido:

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

Neste caso, o ficheiro body.json contém o seguinte:

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

Ao enviar isso, httpbin.org deve retornar a seguinte resposta:

{
  "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"
}

O sinalizador --data comporta-se da mesma forma que -d, portanto pode utilizá-los de forma intercambiável.

Enviar dados JSON

Na secção anterior, viu como podia enviar dados JSON definindo o cabeçalho Content-Type como application/json e, em seguida, passando os dados JSON utilizando o sinalizador -d. Ao enviar um pedido, também é importante informar o servidor web sobre o formato dos dados que espera como resposta. Pode utilizar o cabeçalho Accept com o valor application/json para informar o servidor web de que gostaria de receber uma resposta JSON.

O comando a seguir envia um pedido JSON para o servidor e permite que o servidor saiba que você gostaria de receber JSON em resposta:

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

Verá que as propriedades data e json no corpo da resposta contêm os dados JSON que enviou no pedido:

{
  "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 e receber dados JSON é comum ao enviar pedidos HTTP, por isso curl oferece um sinalizador --json que define os cabeçalhos Content-Type e Accept por você e envia os dados JSON no corpo do pedido. Utilizando este sinalizador, pode encurtar o seu comando para enviar JSON num pedido POST:

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

Isto dá a mesma resposta que anteriormente:

{
  "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"
}

O sinalizador --json foi lançado na versão 7.82 de curl em março de 2022, por isso certifique-se que tem a última versão de curl instalada antes de a utilizar.

Enviar dados XML

curl também permite enviar dados noutros formatos, como XML. Para enviar dados XML, é necessário definir o cabeçalho Content-Type como application/xml e passar os dados XML no corpo do pedido utilizando o sinalizador -d. Também pode dizer ao servidor web que espera que a resposta seja XML, definindo o cabeçalho Accept como application/xml.

O comando seguinte mostra como pode enviar um objeto XML num pedido 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á os dados do pedido XML na propriedade dada devolvida 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

Pode utilizar FormData para enviar pares de dados de valor-chave para um servidor web. Como o nome indica, este formato de dados é utilizado quando se submete um formulário numa página web. Os pares de valores chave têm um nome de campo e um valor.

curl permite-lhe especificar FormData utilizando o sinalizador -F ou --form. Ao usar o sinalizador, especifique o nome e o valor do campo no seguinte formato: -F <name=content> ou --form <name=content>.

O trecho seguinte mostra um comando curl que envia um pedido POST usando FormData com os campos FirstName e LastName:

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

Encontrará os nomes e valores dos campos do formulário na propriedade form do objeto de resposta 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"
}

Utiliza-se o sinalizador -F para cada campo que se pretende enviar para o servidor.

Carregar ficheiros

Pode utilizar FormData para carregar ficheiros num pedido POST, anexando o ficheiro a um campo. Para que curl saiba que um campo FormData contém um ficheiro, introduza a rota para o ficheiro no valor do campo prefixado com o carácter @.

O seguinte comando curl carrega um ficheiro chamado Contract.pdf no seu diretório de trabalho. O comando utiliza um campo chamado File para carregar o ficheiro:

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

A resposta contém o ficheiro completo, pelo que é longa, mas deve ter o seguinte aspeto:

{
  "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 credenciais

Muitos ponto finais HTTP requerem autenticação para enviar pedidos. O servidor web decide qual o método de autenticação a utilizar. Um desses métodos de autenticação é o esquema de autenticação básica, que permite enviar credenciais constituídas por um nome de usuário e uma palavra-passe no pedido. O servidor verifica então as credenciais e, se estiverem corretas, processa o pedido.

curl simplifica o envio de credenciais de autenticação básicas utilizando o sinalizador -u ou --user. Em seguida, especifica o nome de usuário e a palavra-passe e separa-os com : (dois pontos), desta forma: -u <username:password>.

O seguinte trecho usa curl para enviar um pedido POST com credenciais de usuário e um corpo JSON:

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

Repare como curl codifica o nome de usuário e a palavra-passe e envia-os no cabeçalho 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"
}

Conclusão

Este artigo mostrou-lhe como enviar pedidos POST utilizando o utilitário de linha de comandos curl. Aprendeu a utilizar o sinalizador -X para especificar que pretende enviar um pedido POST. Também definiu os cabeçalhos Content-Type e Accept utilizando os sinalizadores -H e --header para que o servidor web saiba em que formato estão os dados. Para enviar dados no corpo do pedido, utilizou o sinalizador -d juntamente com os dados que pretendia enviar.

Também viu alguns exemplos de como enviar vários tipos de dados, incluindo JSON, XML e FormData, e aprendeu a enviar credenciais de autenticação básicas no seu pedido utilizando os sinalizadores -u e --user.

Embora este artigo tenha demonstrado os sinalizadores básicos incluídos em curl e como usá-los, curl oferece mais recursos que você pode querer explorar, incluindo o uso de variáveis, o envio de cookies com pedidos e o envio de pedidos usando um proxy. Muitas linguagens de programação também fornecem bibliotecas que permitem trabalhar com curl a partir dessa linguagem de programação, incluindo Python, Node.js e Rust.

Procura uma solução de raspagem? Fale com um dos nossos especialistas em dados e veja qual dos nossos produtos se adapta melhor às suas necessidades.

Não é necessário cartão de crédito