---
title: "Requisição POST com curl: JSON, cabeçalhos e formulários"
description: "Para enviar uma requisição POST com curl, use -d para formulários, --json para JSON e -H para cabeçalhos. Exemplos testados: arquivos, uploads, auth e Windows."
url: https://proxynet.io/pt-br/blog/curl-post-request
date: 2026-11-19
author: "Acar Diveroli"
category: "Tutoriais"
lang: pt-BR
---

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

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.

> **Nota: Resposta rápida**
>
> O curl envia um POST assim que você passa um corpo. `curl -d "name=Ada" https://api.example.com/form` envia dados de formulário como `application/x-www-form-urlencoded`; `curl --json '{"sku":"A-100"}' https://api.example.com/orders` envia JSON com `Content-Type: application/json` e `Accept: application/json` (a partir do curl 7.82.0; em versões anteriores, use `-H "Content-Type: application/json" -d '...'`). Adicione cabeçalhos com `-H`, leia um corpo de um arquivo com `--json @file.json`, envie arquivos com `-F "file=@report.pdf"` e veja o status com `-i` ou `-w "%{http_code}"`. `-X POST` não é necessário. No Windows PowerShell 5.1, digite `curl.exe` e escape as aspas duplas internas como `\"`, ou guarde o JSON em um arquivo.

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

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çã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](https://curl.se/docs/manpage.html), 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](https://curl.se/windows/microsoft.html).

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

| 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](/pt-br/blog/python-requests-post-json).

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