Gerador de curl form

Formulários no curl em profundidade: urlencoded, multipart, JSON e as flags ao redor

O curl ("Client URL") foi lançado em 1996 pelo desenvolvedor sueco Daniel Stenberg e se tornou o canivete suíço dos clientes de rede. Ele fala HTTP/1.1, HTTP/2, HTTP/3-over-QUIC, além de FTP, SFTP, SMTP, IMAP, POP3, LDAP, MQTT, WebSocket e uma longa lista de protocolos de nicho. O backbone libcurl move desde o Git até video games e satélites. Este gerador constrói as invocações mais comuns de formulário HTTP; as seções abaixo cobrem as codificações, as flags mais úteis e as armadilhas de quando você cola um comando do Postman no shell.

Quando você envia um formulário HTML, o navegador escolhe um de três content-types com base no <form enctype="...">. O curl espelha essa escolha com três flags distintas — se você errar a flag, ou o servidor rejeita ou o parser silenciosamente não lê nada.

As três codificações de formulário

• application/x-www-form-urlencoded — o padrão do HTML. Enviado com -d 'name=John&age=30'. Os valores são percent-encoded; & separa os pares. Bom para payloads pequenos e só de texto.
• multipart/form-data — enviado com -F 'caption=foo' -F '[email protected]'. Cada campo vira uma parte MIME, então dá para misturar texto com upload de arquivo. O @ faz o curl ler do disco; type= define o content-type da parte (-F '[email protected];type=text/csv').
• application/json — não é uma codificação de formulário em si, mas é o padrão moderno de APIs. Use -H 'Content-Type: application/json' -d '{"name":"John"}' ou a flag de conveniência --json '{"name":"John"}' (curl 7.82+) que também seta o Accept.

# POST urlencoded
curl -X POST -d 'name=John&age=30' https://api.example.com/users

# multipart com um arquivo e um campo de texto
curl -F 'caption=Férias' -F '[email protected]' https://api.example.com/photos

# corpo JSON, atalho moderno
curl --json '{"name":"John","age":30}' https://api.example.com/users

As flags que você mais vai usar

• -X MÉTODO — força o método. POST é implícito quando há -d ou -F; para PUT, PATCH e DELETE precisa explicitamente.
• -H 'Header: valor' — adiciona header. Passe múltiplos -H para adicionar mais. Para remover um header padrão, use -H 'Header:' (valor vazio).
• -d 'k=v' — body, seta o Content-Type como urlencoded por padrão. --data-urlencode 'msg=hello mundo' faz o percent-encoding do valor para você.
• -G — promove os valores de --data para a query string e transforma a requisição em GET.
• -u user:senha — autenticação Basic. Para tokens Bearer use -H "Authorization: Bearer $TOKEN".
• -b cookies.txt / -c cookies.txt — lê / grava a cookie jar. Combinados em chamadas seguidas mantêm sessão.
• -L — segue redirects (desligado por padrão; obrigatório em fluxos OAuth).
• -k / --insecure — pula a verificação TLS. Útil em dev com certificado autoassinado, perigoso em produção.
• -o arquivo / -O — salva o body em arquivo (com nome dado ou com o nome remoto); -w '%{http_code}\n' imprime informações templatadas; -s silencia o progress bar; -i inclui headers; -I manda HEAD.
• -v, --trace-ascii out.txt — verbose / trace completo para debug.
• --http2, --http3 — força a versão do protocolo.

Uploads, autenticação e dados binários

Para uploads brutos (PUT pre-signed do S3, WebDAV) use -T arquivo, que envia um PUT. Para enviar o stdin como body, --upload-file - ou --data-binary @-. A diferença entre -d @arquivo e --data-binary @arquivo é sutil mas crítica: -d remove carriage returns e newlines (convenção do urlencoded), --data-binary mantém o arquivo byte-a-byte. Para JSON ou binário, use sempre --data-binary ou --json.

# Chamada com Bearer token
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me

# PUT pre-signed do S3
curl -T big.zip "https://bucket.s3.amazonaws.com/big.zip?X-Amz-Signature=..."

# JSON a partir de arquivo, byte-exact
curl -X POST -H 'Content-Type: application/json' \
     --data-binary @payload.json https://api.example.com/ingest

Quoting do shell e armadilhas ao colar do Postman

• Aspas simples vs duplas. Aspas simples são literais: use ao redor de body JSON. Aspas duplas expandem variáveis ($TOKEN) — prático, mas você precisa escapar $ e crases para deixar literais.
• Ampersand em urlencoded. Um & solto na linha de comando significa "rodar em background". Coloque o valor inteiro entre aspas: -d 'name=John&age=30'.
• Newlines em JSON. Use o quoting ANSI-C $'...' se precisar de newlines literais, ou alimente o body com --data-binary @arquivo.
• Legibilidade multi-linha. Termine cada linha com barra invertida para quebrar um comando longo. Agrupe as flags por função — verbo, headers, body, URL.
• Comandos gerados. Postman, Insomnia, Bruno e até o DevTools do Chrome ("Copy as cURL") emitem comandos prontos para colar. Costumam incluir headers redundantes — remova User-Agent e Accept-Encoding se atrapalharem.

FAQ

Como debugar uma resposta 4xx? Comece com -v para ver headers de request e response. Para detalhes wire-level use --trace-ascii trace.txt. Adicione -w '\n%{http_code} %{time_total}s\n' para imprimir status e tempo sem ter que parsear o verbose inteiro.

O curl suporta WebSocket? Sim, desde o curl 7.86 (2022). Use o mecanismo --upgrade Upgrade ou URLs dedicadas ws:// / wss://. Para sessões interativas full-duplex, o websocat ainda é mais amigável.

Dá para gravar o tráfego como HAR? Nativamente não. Use --trace-ascii para um trace textual ou rode as requisições por um proxy como mitmproxy ou Charles, que produzem HAR de verdade com breakdown de timing.

Como mandar um arquivo binário como body inteiro? Use --data-binary @arquivo.bin para POST ou -T arquivo.bin para PUT. Evite -d @arquivo.bin — ele remove bytes CR/LF.

Como manter sessão entre chamadas? Use a cookie jar: curl -c cookies.txt -d 'user=x&pass=y' .../login, depois curl -b cookies.txt .../profile. Para APIs com token, guarde o token em uma variável e mande com -H "Authorization: Bearer $TOKEN" em cada chamada.