Saber testar API com cURL e com o Postman é uma habilidade básica para qualquer desenvolvedor, seja quem constrói APIs ou quem integra serviços de terceiros. É assim que você descobre se o problema está no seu código ou no servidor, confere o formato exato de uma resposta antes de programar e reproduz um erro para o suporte.
Neste guia você vai aprender os dois caminhos: o cURL, que roda no terminal e está disponível em praticamente qualquer sistema, e o Postman, uma interface gráfica para montar, salvar e compartilhar requisições. Os exemplos usam a API de tarefas que criamos em Minha primeira API em Node.js com Express, e todos os prints mostram respostas reais.
Antes de começar: o que compõe uma requisição HTTP
Toda chamada a uma API REST tem as mesmas peças. Entender cada uma torna qualquer ferramenta de teste óbvia:
| Parte | Exemplo | Para que serve |
|---|---|---|
| Método | GET, POST, PUT, PATCH, DELETE | A intenção: ler, criar, atualizar, remover |
| URL | http://localhost:3000/tarefas/1 |
O endereço do recurso |
| Cabeçalhos (headers) | Content-Type, Authorization |
Metadados: formato do corpo, credenciais |
| Corpo (body) | {"titulo": "Estudar"} |
Os dados enviados (em POST, PUT e PATCH) |
| Status | 200, 201, 400, 401, 404, 500 | O resultado da operação, na resposta |
Se algum desses conceitos for novo, o artigo Como funciona uma API? Entenda na prática explica o básico.
Parte 1: testando APIs com cURL
O cURL é uma ferramenta de linha de comando para transferir dados via URL. Ele já vem instalado no Linux, no macOS e no Windows 10/11. No Windows, use curl.exe no PowerShell, porque curl sozinho pode ser um apelido para outro comando.
GET simples e cabeçalhos da resposta
O teste mais simples é um GET. Adicionando -i, o cURL mostra também o status e os cabeçalhos da resposta:
curl -i http://localhost:3000/tarefas/1
Repare no Content-Type: application/json: é o servidor avisando que o corpo é JSON. Cabeçalhos como Cache-Control, Retry-After e os de limite de requisições também aparecem aqui e costumam explicar comportamentos estranhos.
Modo verboso: vendo a conversa completa
Quando algo não funciona e você não sabe por quê, use -v. Ele mostra a requisição que saiu (linhas com >) e a resposta que chegou (linhas com <):
É com o -v que você descobre, por exemplo, que o cabeçalho de autenticação não está sendo enviado, que houve um redirecionamento inesperado ou que o certificado HTTPS tem problema.
POST com JSON, arquivos e códigos de status
Para enviar dados, informe o método com -X, o tipo do conteúdo com -H e o corpo com -d:
curl -X POST http://localhost:3000/tarefas \
-H "Content-Type: application/json" \
-d '{"titulo":"Testar com cURL"}'
Em corpos maiores, escrever o JSON dentro das aspas fica confuso. Salve em um arquivo e use -d @arquivo.json. E, para ver o status HTTP separado do corpo, use a opção -w (write-out):
Essas opções são perfeitas para scripts de verificação: o %{http_code} permite testar em um if se a API respondeu 200, e o %{time_total} mede quanto tempo a chamada levou.
Formatando e filtrando JSON com jq
Respostas JSON longas vêm em uma linha só. O jq formata, colore e filtra o conteúdo:
curl -s http://localhost:3000/tarefas | jq
curl -s http://localhost:3000/tarefas | jq '.[] | select(.concluida == false) | .titulo'
O -s (silent) esconde a barra de progresso do cURL, que atrapalharia o jq. Instale com sudo apt install jq, brew install jq ou winget install jqlang.jq.
PUT, PATCH e DELETE
Os demais métodos seguem a mesma lógica:
# Atualizar
curl -X PUT http://localhost:3000/tarefas/1 \
-H "Content-Type: application/json" \
-d '{"concluida": true}'
# Remover (e mostrar o status)
curl -i -X DELETE http://localhost:3000/tarefas/2
Autenticação: Bearer token e API keys
APIs reais exigem credenciais, normalmente em cabeçalhos. O padrão mais comum é o Bearer token:
curl https://api.exemplo.com/recurso \
-H "Authorization: Bearer SEU_TOKEN"
Na APIBrasil, por exemplo, os serviços por crédito usam só o Bearer, e os serviços device-based (como CEP, SMS e WhatsApp) usam o Bearer mais o cabeçalho DeviceToken. Um script de teste organizado fica assim:
A primeira chamada, ao endpoint /balance, é um ótimo teste de credencial: se ela responde, o token é válido; se volta 401, nada mais vai funcionar. Repare também que os tokens vêm de variáveis de ambiente, e não escritos no script — assim ele pode ir para o Git sem expor segredos.
Tabela de opções do cURL mais usadas
| Opção | O que faz |
|---|---|
-X MÉTODO |
Define o método HTTP (GET é o padrão) |
-H "Nome: valor" |
Adiciona um cabeçalho |
-d 'dados' / -d @arquivo |
Envia um corpo (e muda o método padrão para POST) |
-i |
Mostra status e cabeçalhos da resposta |
-v |
Modo verboso, com requisição e resposta completas |
-s / -sS |
Silencioso (o -S ainda mostra erros) |
-o arquivo |
Salva o corpo em um arquivo |
-w '%{http_code}' |
Imprime informações como status e tempo |
-L |
Segue redirecionamentos |
--fail-with-body |
Retorna erro no shell para status 4xx/5xx, mantendo o corpo |
Parte 2: testando APIs com Postman
O Postman é uma aplicação gráfica para testar APIs. Ele brilha quando você precisa salvar, organizar e compartilhar requisições com a equipe. Os conceitos são exatamente os mesmos do cURL, só que em campos de formulário.
Fazendo sua primeira requisição no Postman
- Instale o Postman (ou use a versão web) e crie uma conta gratuita.
- Clique em New → HTTP (ou no botão + das abas).
- Escolha o método no seletor à esquerda (GET) e cole a URL:
http://localhost:3000/tarefas. - Clique em Send. A resposta aparece embaixo, com o corpo formatado, o status, o tempo e o tamanho.
Enviando JSON em um POST
- Troque o método para POST.
- Na aba Body, selecione raw e, no seletor à direita, JSON.
- Digite o corpo:
{"titulo": "Testar com Postman"}. - Clique em Send e confira o status 201 Created.
Ao escolher JSON no Body, o Postman já adiciona o cabeçalho Content-Type: application/json automaticamente — um erro clássico no cURL que o Postman evita.
Autenticação no Postman
Na aba Authorization, escolha Bearer Token e cole o token. Para cabeçalhos personalizados, como o DeviceToken da APIBrasil, use a aba Headers e adicione a chave e o valor.
Coleções e variáveis de ambiente
O grande ganho do Postman está aqui:
- Collections agrupam as requisições de uma API. Você pode exportar e enviar para a equipe ou versionar no Git.
- Environments guardam variáveis como
{{base_url}}e{{token}}. Assim você troca de desenvolvimento para produção com um clique, sem editar cada requisição. - Tests (na aba Scripts) permitem escrever verificações em JavaScript, como
pm.response.to.have.status(201), e rodar a coleção inteira como uma suíte de testes.
A própria APIBrasil publica a documentação do Gateway V2 no Postman, que você pode importar para o seu workspace e testar os endpoints sem escrever código.
Dica: no Postman, o botão Code (ícone
</>) converte qualquer requisição em cURL, PHP, Node.js, Python e outras linguagens. É uma ótima ponte entre testar e implementar.
cURL ou Postman: qual usar?
| Situação | Melhor escolha |
|---|---|
| Teste rápido de um endpoint | cURL |
| Servidor sem interface gráfica (SSH) | cURL |
| Scripts, CI/CD e automações | cURL |
| Compartilhar requisições com a equipe | Postman |
| Explorar uma API nova com muitos endpoints | Postman |
| Alternar entre ambientes (dev, homologação, produção) | Postman |
| Reproduzir um erro para o suporte | cURL (cole o comando no chamado) |
Na prática, os dois se complementam. Muitas equipes usam o Postman no dia a dia e o cURL para documentação e automação.
Status HTTP que você vai encontrar ao testar APIs
- 200 OK — sucesso.
- 201 Created — recurso criado.
- 204 No Content — sucesso sem corpo (comum em DELETE).
- 400 Bad Request / 422 Unprocessable Entity — dados inválidos. Leia a mensagem de erro no corpo.
- 401 Unauthorized — credencial ausente ou inválida.
- 402 Payment Required — sem saldo ou créditos (comum em APIs pagas por consulta).
- 403 Forbidden — autenticado, mas sem permissão para aquele recurso.
- 404 Not Found — recurso ou rota inexistente.
- 429 Too Many Requests — limite de requisições atingido. Respeite o cabeçalho
Retry-After. - 500/502/503 — erro no servidor. Tente de novo mais tarde e, se persistir, avise o provedor.
Erros comuns ao testar APIs
JSON inválido no corpo — aspas simples, vírgula sobrando no final ou aspas não escapadas. Valide o JSON antes de enviar.
Esquecer o Content-Type: application/json — muitos servidores ignoram o corpo sem esse cabeçalho.
Aspas no Windows — o PowerShell trata aspas de forma diferente. Use curl.exe, arquivos com -d @arquivo.json ou o Git Bash.
Testar só o caminho feliz — sempre teste também dados inválidos, IDs inexistentes e credenciais erradas.
Colar tokens em lugares públicos — prints, issues do GitHub e grupos de mensagens. Mascare o token antes de compartilhar.
Perguntas frequentes
O cURL funciona no Windows?
Sim. Windows 10 e 11 já trazem o curl.exe. No PowerShell, digite curl.exe para garantir que o cURL real está sendo usado.
O Postman é gratuito?
Sim, o plano gratuito atende muito bem uso individual e equipes pequenas. Planos pagos adicionam recursos de colaboração e limites maiores.
Existem alternativas ao Postman?
Sim: Insomnia, Bruno, Hoppscotch e a extensão Thunder Client do VS Code são opções populares. O Bruno, por exemplo, salva as coleções como arquivos de texto no próprio repositório.
Como converter um comando cURL para código?
No Postman, use Import → Raw text e cole o cURL; depois clique em Code para gerar o código na linguagem desejada. As SDKs oficiais, como a da APIBrasil, também simplificam essa passagem.
Conclusão
Agora você sabe testar API com cURL e com o Postman: montar requisições com qualquer método, enviar JSON, autenticar com Bearer token, ler cabeçalhos e status, medir tempo de resposta e organizar testes em coleções. São ferramentas que você vai usar em todos os projetos, do primeiro endpoint à investigação de um problema em produção.
Próximos passos: aprenda a guardar tokens com segurança em Variáveis de ambiente e arquivo .env e coloque o que aprendeu em prática consumindo uma API real no tutorial Consultar CEP com JavaScript, usando a APIBrasil.
