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:
- Você adiciona uma opção de corpo.
-d,--data-binary,--data-urlencode,--jsonou-Ftransformam a requisição em POST. - O curl escolhe um
Content-Type. A família-denviaapplication/x-www-form-urlencoded,--jsonenviaapplication/jsone-Fenviamultipart/form-datacom um delimitador (boundary). - O curl prepara o corpo. Ele junta várias partes
-dcom&, remove as quebras de linha de arquivos lidos com-d @e mantém os arquivos intactos com--data-binarye--json. - Ele envia a requisição.
POST /orders HTTP/1.1, os cabeçalhos, incluindoContent-Length,Content-Typee os seus valores de-H, e depois o corpo. - 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. - O curl mostra o corpo da resposta. O status e os cabeçalhos ficam ocultos, a menos que você peça com
-i,-vou-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ção | Content-Type enviado | Tratamento do corpo | Use para |
|---|---|---|---|
-d / --data | application/x-www-form-urlencoded | Como digitado; @file perde as quebras de linha | Formulários no estilo HTML |
--data-urlencode | application/x-www-form-urlencoded | Valor com codificação percentual | Valores com espaços ou & |
--data-binary | application/x-www-form-urlencoded | Byte a byte | Arquivos que precisam chegar exatos |
--json | application/json | Byte a byte, adiciona Accept | APIs JSON (a partir da 7.82.0) |
-F / --form | multipart/form-data | Dividido em partes nomeadas | Upload 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:
curl -d "name=Ada&city=Paris" https://api.example.com/signupO 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ê:
curl --data-urlencode "q=red shoes & bags" https://api.example.com/searchO 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":
# 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/ordersNa 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:
curl --json @order.json https://api.example.com/orders
curl -H "Content-Type: application/json" --data-binary @order.json https://api.example.com/ordersCom 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:
curl --json @order.json \
-H "Idempotency-Key: 7f3c9a10" \
-H "X-Request-Source: nightly-sync" \
https://api.example.com/ordersUm 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:
curl -F "title=Q3 report" -F "file=@report.pdf" https://api.example.com/uploadsCada -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:
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:
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/ordersO 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:
| Shell | Forma que funcionou | O 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:
curl -x http://user:pass@pr.proxynet.io:8000 \
--json @order.json https://api.example.com/ordersCom 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
-de marcação de formulário. Use--jsonou-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
-vou 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 POSTcom-L; tire o-X. - 401 ou 403. Token ausente ou errado, ou
$API_TOKENvazio neste shell. Mostre a variável primeiro. A positional parameter cannot be found.curlno PowerShell 5.1 chamou oInvoke-WebRequest; digitecurl.exe.- Parte de um cabeçalho é tratada como um segundo endereço.
-H Content-Type: application/jsonsem aspas se divide no espaço. Coloque cada valor de-Hentre aspas. --jsoné recusado como desconhecido. curl anterior à 7.82.0; use-Hmais--data-binary.
Guia de decisão
| Necessidade | Recomendaçã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 Windows | curl.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á.




