Requisição POST com curl: JSON, cabeçalhos e formulários

Publicado:

16 min de leitura

Acar Diveroli
Autor: Acar Diveroli
Janela de terminal com um comando POST do curl, a parte --json em azul, e atrás um cartão de resposta 201 Created

A documentação de uma API mostra um comando curl de uma linha para criar um pedido. Você cola, adiciona a sua chave, aperta Enter e o servidor responde 415 Unsupported Media Type, ou 400 com invalid JSON, embora o JSON pareça correto. No notebook Linux de um colega, a mesma linha funciona. Não há nada de errado com a API: o comando enviou um corpo diferente ou um Content-Type diferente do que você imagina, e no Windows o shell tirou as aspas do seu JSON antes que o curl chegasse a vê-lo.

Este guia mostra dados de formulário com -d, JSON com --json ou com -H mais -d, corpos lidos de arquivos, uploads com -F, cabeçalhos e autenticação, quando -X POST é necessário, como ler a resposta e o uso de aspas no cmd e no PowerShell. Rodamos cada comando com o curl 8.22.0 no Windows 11, no cmd e no Windows PowerShell 5.1, contra um pequeno servidor de eco (echo) na nossa própria máquina, que mostrava o método, o cabeçalho Content-Type e o corpo recebido.

O que é uma requisição POST?

Uma requisição POST é uma requisição HTTP que leva dados no corpo e pede ao servidor que faça algo com eles: criar um pedido, salvar um formulário, iniciar uma tarefa. A RFC 9110, o padrão do HTTP, define POST como uma requisição para que o recurso de destino processe a representação incluída na requisição segundo as próprias regras.

O GET só pede algo e não leva corpo. Além disso, o POST não é idempotente: o mesmo POST enviado duas vezes pode criar dois pedidos. Se requisições, endpoints e códigos de status são novidade para você, comece por O que é uma API e como ela funciona?.

Duas partes de um POST são as que mais importam. O corpo são os dados. O cabeçalho Content-Type diz ao servidor como lê-los: como campos de formulário, como JSON ou como um upload multipart. A maioria dos problemas com POST no curl é um desencontro entre os dois.

Como o curl envia uma requisição POST?

O curl muda para POST sozinho quando você passa uma opção de corpo; você descreve os dados e o curl deduz o método:

  1. Você adiciona uma opção de corpo. -d, --data-binary, --data-urlencode, --json ou -F transformam a requisição em POST.
  2. O curl escolhe um Content-Type. A família -d envia application/x-www-form-urlencoded, --json envia application/json e -F envia multipart/form-data com um delimitador (boundary).
  3. O curl prepara o corpo. Ele junta várias partes -d com &, remove as quebras de linha de arquivos lidos com -d @ e mantém os arquivos intactos com --data-binary e --json.
  4. Ele envia a requisição. POST /orders HTTP/1.1, os cabeçalhos, incluindo Content-Length, Content-Type e os seus valores de -H, e depois o corpo.
  5. O servidor lê primeiro o Content-Type. Uma API JSON que recebe dados marcados como formulário os recusa com 415 ou não consegue interpretá-los e responde 400.
  6. O curl mostra o corpo da resposta. O status e os cabeçalhos ficam ocultos, a menos que você peça com -i, -v ou -w.

Qual opção do curl usar para o corpo da requisição?

Escolha a opção que corresponde ao que o servidor espera. Foi isto que o nosso servidor de eco recebeu com cada uma:

OpçãoContent-Type enviadoTratamento do corpoUse para
-d / --dataapplication/x-www-form-urlencodedComo digitado; @file perde as quebras de linhaFormulários no estilo HTML
--data-urlencodeapplication/x-www-form-urlencodedValor com codificação percentualValores com espaços ou &
--data-binaryapplication/x-www-form-urlencodedByte a byteArquivos que precisam chegar exatos
--jsonapplication/jsonByte a byte, adiciona AcceptAPIs JSON (a partir da 7.82.0)
-F / --formmultipart/form-dataDividido em partes nomeadasUpload de arquivos

Todas estão descritas no manual do curl, a referência de cada opção deste guia.

Como enviar dados de formulário com -d?

O -d envia uma string como corpo e a marca como dados de formulário, o formato que um navegador usa para um formulário HTML simples:

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

O nosso servidor recebeu POST, Content-Type: application/x-www-form-urlencoded e name=Ada&city=Paris. Várias opções -d são unidas com &, então -d "a=1" -d "b=2" chegou como a=1&b=2.

O -d envia o texto como você digita, por isso um valor com espaço, & ou = se divide nos campos errados. O --data-urlencode codifica o valor para você:

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

O servidor recebeu q=red+shoes+%26+bags, um único campo com o "e comercial" intacto. Se um endpoint quiser os campos no endereço, adicione -G: -G -d "q=shoes" -d "page=2" virou GET /search?q=shoes&page=2, sem corpo.

Como enviar JSON por POST com o curl?

Use --json a partir do curl 7.82.0, ou defina o cabeçalho você mesmo nas versões anteriores. O -d sozinho nunca diz "isto é JSON":

bash
# Errado para a maioria das APIs JSON: corpo JSON com marcação de formulário
curl -d '{"sku":"A-100","qty":2}' https://api.example.com/orders

# Funciona em qualquer versão do curl
curl -H "Content-Type: application/json" -d '{"sku":"A-100","qty":2}' https://api.example.com/orders

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

Na nossa máquina de teste, o primeiro comando chegou como application/x-www-form-urlencoded, e o nosso endpoint de teste, que só aceita JSON, o recusou com 415. O segundo chegou como application/json com Accept: */*; o terceiro também com Accept: application/json, e o endpoint respondeu 201 Created.

O --json equivale a --data-binary mais esses dois cabeçalhos, e um cabeçalho definido com -H substitui o que o curl adicionaria. Confira a sua versão com curl --version: o Ubuntu 22.04, por exemplo, traz o curl 7.81.0, uma versão antes do --json, então scripts para servidores mais antigos devem manter a forma com -H.

Como enviar JSON a partir de um arquivo?

Passe o arquivo com @: --json @order.json nas versões novas e --data-binary @order.json com um cabeçalho Content-Type nas antigas. Evite -d @order.json quando os bytes precisarem chegar exatos:

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

Com um order.json de quatro linhas, o -d @order.json entregou 29 bytes em uma única linha, porque o curl remove retornos de carro e quebras de linha de arquivos lidos dessa forma. O --data-binary e o --json entregaram todos os 33 bytes. Um parser de JSON não se importa, mas uma requisição assinada ou um arquivo CSV se importam.

Um arquivo também acaba com a maioria dos problemas de aspas, porque o shell nunca mexe no JSON. O @- lê o corpo da entrada padrão, então um script pode gerá-lo: python make_order.py | curl --json @- https://api.example.com/orders.

Como adicionar cabeçalhos a uma requisição POST do curl?

Dê a cada cabeçalho o seu próprio -H "Name: value" e repita a opção quantas vezes precisar:

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

Um cabeçalho que você define substitui o cabeçalho do próprio curl com o mesmo nome; é assim que se muda Accept ou User-Agent. Um valor vazio o remove: com -H "Content-Type:", o nosso servidor não recebeu nenhum Content-Type.

Os cabeçalhos de -H são enviados de novo depois de um redirecionamento. O curl retém Authorization e Cookie quando o redirecionamento leva a outro host, mas uma chave em um cabeçalho como X-API-Key vai junto, então tome cuidado ao adicionar -L.

Como fazer upload de um arquivo com curl -F?

Use -F com @ antes do nome do arquivo. O curl envia então multipart/form-data, o formato de um formulário HTML com um campo de arquivo:

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

Cada -F vira uma parte nomeada. Enviamos um arquivo de texto, report.txt, e o nosso servidor viu uma parte de texto title e uma parte de arquivo file com filename="report.txt" e Content-Type: text/plain, que o curl deduziu pela extensão. Defina o tipo quando o palpite estiver errado: -F "file=@scan.bin;type=application/pdf".

Usar < em vez de @ coloca o conteúdo de um arquivo em um campo de texto comum, como em -F "notes=<notes.txt". -F e -d não podem ser combinados: o nosso curl parou com You can only select one HTTP request method! antes de enviar qualquer coisa. O nome do campo precisa corresponder à documentação da API.

Como autenticar uma requisição POST com o curl?

Envie o que a API pede: -u user:pass para autenticação Basic ou um cabeçalho Authorization para um token. Com -u user:pass, o nosso servidor recebeu Authorization: Basic dXNlcjpwYXNz, que é só a forma Base64 de user:pass, então use isso apenas sobre HTTPS.

Para um token bearer, leia-o de uma variável de ambiente para que ele fique fora do histórico do shell:

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

--oauth2-bearer "$API_TOKEN" monta o mesmo cabeçalho. Algumas APIs querem a chave em um cabeçalho próprio, como X-API-Key.

Quando o -X POST é necessário?

Quase nunca com uma opção de corpo. Com -v, o nosso curl mostrou Note: Unnecessary use of -X or --request, POST is already inferred. para -X POST -d "x=1"; o manual diz que -X só muda a palavra na linha da requisição. Ele é útil para outros métodos com corpo: curl -X PUT --json '{"qty":3}' ... chegou como um PUT com o JSON.

O -X passa a atrapalhar junto com -L (seguir redirecionamentos). Enviamos um POST para um endereço que respondia 302 Found:

  • Com -L -d "x=1", o curl seguiu com um GET sem corpo, como o manual descreve para 301, 302 e 303.
  • Com -L -X POST -d "x=1", a requisição seguinte foi um POST com corpo vazio: o método foi forçado, os dados não.
  • Com -L --post302 -d "x=1", a requisição seguinte foi um POST com o corpo original.

Por isso, quando um POST precisa sobreviver a um redirecionamento, use --post301, --post302 ou --post303, ou envie direto para o endereço final.

Como ver o status e os cabeçalhos da resposta?

Adicione -i para a linha de status e os cabeçalhos da resposta, -v para a requisição e a resposta, ou -w só para os valores escolhidos:

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

O primeiro mostrou HTTP/1.1 201 Created antes do JSON. O segundo mostrou apenas 201: -s esconde o indicador de progresso e -o /dev/null descarta o corpo (-o NUL no Windows). "%{http_code} %{content_type} %{time_total}s\n" nos devolveu 201 application/json 0.001347s.

Em scripts, adicione --fail-with-body: o curl termina com erro em status 400 ou acima, mas ainda mostra a mensagem do servidor. Para uma requisição que se comporta de forma estranha, use -v; as linhas que começam com > são exatamente o que o curl enviou.

Como escrever comandos POST do curl no Windows?

O Windows 10 e o 11 trazem o curl de verdade como curl.exe, mas no Windows PowerShell 5.1 a palavra curl é um alias do cmdlet Invoke-WebRequest. Na nossa máquina, curl -d "x=1" ... digitado no PowerShell 5.1 falhou com A positional parameter cannot be found that accepts argument 'x=1'. Digite curl.exe, como também recomenda a página do curl sobre a versão para Windows.

O problema maior são as aspas. Um JSON entre aspas simples, a forma usada em todo exemplo de Linux, se comporta de modo diferente em cada shell:

ShellForma que funcionouO que a forma ingênua enviou
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"}'Não testado aqui
Qualquer shell--json "@order.json"O arquivo, sem alterações

No cmd, aspas simples não delimitam nada, então elas viraram parte do corpo e as aspas duplas internas sumiram. No PowerShell 5.1, '{"sku":"A-100","qty":2}' chegou ao nosso servidor como {sku:A-100,qty:2} e o endpoint JSON respondeu 400. Escapar cada aspa interna como \" resolveu os dois casos.

A referência about_Parsing da Microsoft explica o motivo: o PowerShell 7.3 mudou a forma como argumentos com aspas embutidas chegam a programas como o curl.exe, uma mudança incompatível em relação ao 5.1. O PowerShell 7 não estava instalado na nossa máquina de teste, então essa linha segue a documentação. No PowerShell, coloque entre aspas tudo o que começa com @, como "@order.json"; em um arquivo em lote .cmd, escreva %%{http_code} para -w. O hábito mais seguro no Windows é o arquivo: assim não sobra nada para o shell quebrar.

Como enviar uma requisição POST do curl por um proxy?

Adicione -x com o endereço do proxy; as opções de corpo continuam as mesmas:

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

Com um destino HTTPS, o curl primeiro pede ao proxy um túnel CONNECT e depois envia o POST dentro da conexão criptografada, então o proxy vê o nome do host, mas não o seu JSON. SOCKS5, variáveis de ambiente e .curlrc estão em cURL com proxy.

Um proxy ajuda quando a requisição precisa sair de um endereço ou de um país específico, por exemplo para ver como o seu próprio checkout responde a um comprador de outra região. Os Proxies HTTPS aceitam exatamente essas opções, com usuário e senha ou com o IP do seu servidor na whitelist de IP.

Quando o teste precisa de conexões residenciais em um país ou uma cidade escolhidos, os Proxies residenciais usam a mesma linha -x, com o país e a sessão no nome de usuário.

Onde as requisições POST do curl são usadas?

Desenvolvedores testam uma API com um POST do curl antes de escrever código, porque o comando não esconde nada. Equipes de suporte pedem o comando curl que falha, já que ele reproduz o problema em qualquer máquina. Receptores de webhooks são testados enviando um evento de exemplo para o seu próprio endpoint. Scripts de deploy chamam APIs internas para iniciar tarefas ou publicar versões, e tarefas de monitoramento enviam um pedido de teste para um ambiente de staging e disparam um alerta quando a resposta deixa de ser 201.

Erros comuns de POST no curl e como corrigir

  • 415 Unsupported Media Type. JSON enviado com -d e marcação de formulário. Use --json ou -H "Content-Type: application/json".
  • 400 Bad Request com erro ao interpretar o JSON. Aspas removidas pelo shell ou um erro de digitação no JSON. Confira com -v ou passe o JSON para um arquivo.
  • O POST chega como GET. Um redirecionamento 301, 302 ou 303 com -L. Envie para a URL final ou use as opções --post30x.
  • Corpo vazio depois de um redirecionamento. -X POST com -L; tire o -X.
  • 401 ou 403. Token ausente ou errado, ou $API_TOKEN vazio neste shell. Mostre a variável primeiro.
  • A positional parameter cannot be found. curl no PowerShell 5.1 chamou o Invoke-WebRequest; digite curl.exe.
  • Parte de um cabeçalho é tratada como um segundo endereço. -H Content-Type: application/json sem aspas se divide no espaço. Coloque cada valor de -H entre aspas.
  • --json é recusado como desconhecido. curl anterior à 7.82.0; use -H mais --data-binary.

Guia de decisão

NecessidadeRecomendação
Enviar campos de formulário-d "a=1" -d "b=2"
Valor de formulário com espaços ou &--data-urlencode
Enviar JSON, curl 7.82.0 ou mais novo--json @file.json
Enviar JSON, curl mais antigo-H "Content-Type: application/json" --data-binary @file.json
Enviar um arquivo-F "file=@name.ext"
Autenticação por token-H "Authorization: Bearer $API_TOKEN"
PUT ou PATCH com corpo-X PUT --json ...
POST que precisa sobreviver a um redirecionamento-L --post302 (ou 301/303)
Só o código de status-s -o /dev/null -w "%{http_code}\n"
JSON no Windowscurl.exe com um arquivo e @

Perguntas frequentes

Como enviar uma requisição POST com o curl?

Passe um corpo ao curl e ele envia um POST: curl -d "name=Ada" https://api.example.com/form para dados de formulário, ou curl --json '{"name":"Ada"}' https://api.example.com/users para JSON. -X POST não é necessário.

Qual é a diferença entre -d e --json no curl?

A marcação muda. O -d envia Content-Type: application/x-www-form-urlencoded e remove quebras de linha de arquivos; o --json envia Content-Type: application/json mais Accept: application/json e mantém os arquivos intactos. O --json exige o curl 7.82.0 ou mais novo.

Como enviar um arquivo JSON por POST com o curl?

Use curl --json @data.json https://api.example.com/items. Com um curl anterior à 7.82.0, use -H "Content-Type: application/json" --data-binary @data.json. Evite -d @data.json quando os bytes exatos importarem.

Como ver os cabeçalhos de resposta de uma requisição POST do curl?

Adicione -i para mostrar a linha de status e os cabeçalhos antes do corpo, ou -v para ver juntos os cabeçalhos da requisição e da resposta. Para ter só o código de status, use -s -o /dev/null -w "%{http_code}".

Por que o meu POST do curl funciona no Linux, mas falha no PowerShell?

No Windows PowerShell 5.1, curl significa Invoke-WebRequest, e a versão 5.1 remove as aspas duplas de dentro de um JSON entre aspas simples antes que o curl.exe o receba. Digite curl.exe, escape as aspas internas como \" ou passe o JSON a partir de um arquivo.

Como converter um comando POST do curl para Python?

Associe cada parte: --json vira json=, -d vira data=, -H vira headers= e -F vira files=. O mapeamento completo, com exemplos testados, está em POST com JSON no Python Requests.

Em resumo

O curl envia um POST assim que tem um corpo: -d para dados de formulário, --json para JSON a partir da 7.82.0, -H "Content-Type: application/json" com --data-binary nas versões anteriores e -F para uploads. A maioria das falhas vem da marcação, não dos dados: JSON enviado como formulário retorna 415, -d @ perde as quebras de linha e -X POST com -L envia um POST vazio depois de um redirecionamento. Confira o que saiu com -v. No Windows, digite curl.exe e guarde o JSON em um arquivo; quando a requisição precisar sair de um endereço ou de um país específico, adicione -x e deixe o resto como está.