Para testar uma API REST com cURL, abra o terminal, faça primeiro uma requisição GET ao endpoint, confira o código HTTP e os cabeçalhos e só depois avance para POST, autenticação e depuração. Esse fluxo evita que um problema de interface ou de uma ferramenta gráfica seja confundido com erro da API. O cURL é especialmente útil porque pode ser usado no terminal, em scripts de automação e em ambientes de servidor sem interface gráfica.
Neste tutorial, você vai montar requisições reproduzíveis, enviar JSON, interpretar respostas e investigar falhas comuns. Os exemplos usam endpoints públicos de demonstração e não exigem uma conta. Em um sistema real, troque a URL e os dados pelos valores da documentação da API, sem copiar tokens ou senhas para um histórico compartilhado.
O que você precisa antes de começar
Você precisa de um computador com cURL disponível no terminal, conexão com a internet e a URL de uma API REST que possa ser consultada. Em instalações atuais do Windows, macOS e Linux, o comando costuma estar disponível, mas a confirmação é simples. Execute:
curl --versionSe o terminal mostrar a versão e os protocolos suportados, o primeiro pré-requisito está atendido. Se aparecer uma mensagem informando que o comando não foi encontrado, instale o cURL pelo gerenciador de pacotes da sua distribuição ou consulte a documentação do sistema operacional. No Windows, prefira confirmar qual executável está sendo chamado com where curl; isso ajuda a evitar confusão entre versões instaladas por ferramentas diferentes.
Também tenha em mãos quatro informações: o método HTTP, a URL completa, os cabeçalhos exigidos e o formato do corpo. Uma documentação confiável deve dizer, por exemplo, se o endpoint aceita GET ou POST, se espera Content-Type: application/json e se requer um token no cabeçalho Authorization. Sem esses dados, não é seguro deduzir a requisição apenas pelo nome do endpoint.
1. Faça uma primeira requisição GET
Comece com um endpoint público de teste que devolva JSON:
curl https://jsonplaceholder.typicode.com/todos/1O corpo da resposta deve ser um objeto JSON de exemplo. O ponto principal desta etapa não é o conteúdo específico, mas confirmar que o terminal alcança o domínio, que a URL está correta e que o servidor devolve uma resposta. Para uma API de produção, use o endpoint de leitura indicado pelo fornecedor e respeite limites de uso, termos de serviço e dados pessoais.
Quando você precisa enxergar o cabeçalho e o código HTTP, acrescente -i:
curl -i https://jsonplaceholder.typicode.com/todos/1O resultado começa com uma linha como HTTP/2 200 ou HTTP/1.1 200 OK, seguida dos cabeçalhos e do corpo. O número é mais importante que o texto: 200 indica que a requisição foi atendida, enquanto o significado exato depende do método e do endpoint.
2. Envie parâmetros e cabeçalhos
Algumas APIs recebem filtros na query string. Neste caso, inclua os parâmetros na URL e use aspas quando houver caracteres que o shell possa interpretar:
curl "https://api.exemplo.com/clientes?status=ativo&limite=10"Para informar um cabeçalho, use -H. O cabeçalho de aceitação comunica o formato que você prefere receber:
curl -H "Accept: application/json" \
https://jsonplaceholder.typicode.com/todos/1O caractere de continuação torna o comando mais legível no macOS, Linux e em shells compatíveis. No PowerShell, a continuação de linha tem regras próprias; se houver dúvida, execute o comando em uma única linha ou consulte a sintaxe do shell escolhido. O cURL não corrige uma URL, um cabeçalho ou uma quebra de linha incompatível com o ambiente.
3. Faça um POST com JSON
O método POST normalmente envia uma entidade ao recurso e pode causar uma mudança no servidor. Para enviar JSON, combine -X POST, o cabeçalho de tipo de conteúdo e -d com um corpo válido:
curl -i -X POST \
-H "Content-Type: application/json" \
-d '{"title":"Teste de API","completed":false,"userId":1}' \
https://jsonplaceholder.typicode.com/todosEm um endpoint de demonstração, a resposta pode simular a criação e retornar um código de sucesso, mas isso não significa que um registro tenha sido persistido em um banco real. Em uma API de produção, confirme na documentação qual código representa a criação, quais campos são obrigatórios e se o servidor exige um identificador de idempotência.
Para evitar erros de aspas, especialmente com corpos longos, salve o JSON em um arquivo e use:
curl -i -X POST \
-H "Content-Type: application/json" \
--data-binary @payload.json \
https://api.exemplo.com/eventosEsse formato facilita revisar o corpo antes do envio e registrar uma versão de teste sem misturá-la ao comando. Ainda assim, não coloque segredos no arquivo nem o envie para um repositório público.
4. Teste autenticação sem expor o segredo
APIs podem usar Bearer token, chave em cabeçalho, autenticação básica ou outro mecanismo. Para um Bearer token, a forma geral é:
curl -i \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
https://api.exemplo.com/perfilSubstitua o marcador apenas no seu ambiente seguro. Uma alternativa melhor para scripts é carregar o valor de uma variável de ambiente e evitar que ele fique gravado no arquivo:
curl -i \
-H "Authorization: Bearer $API_TOKEN" \
https://api.exemplo.com/perfilO comando -u usuario:senha pode ser usado quando a API documenta Basic Auth, mas o valor pode aparecer no histórico do shell ou na lista de processos, dependendo do ambiente. Use um gerenciador de segredos, variável protegida ou mecanismo recomendado pelo provedor. Nunca publique tokens reais nos exemplos, tickets ou logs.
5. Use o modo de depuração para descobrir o problema
Quando a resposta não explica o suficiente, use -v para ver detalhes da conexão, do envio de cabeçalhos e do recebimento da resposta:
curl -v https://api.exemplo.com/healthO modo verboso é útil para descobrir se a requisição foi redirecionada, qual método foi enviado e se o TLS ou o proxy interferiu. Ele também pode revelar cabeçalhos sensíveis. Por isso, trate a saída como material confidencial antes de compartilhá-la. Para registrar somente os cabeçalhos de resposta, use -i; para separar corpo e cabeçalhos em arquivos, use as opções de saída documentadas pelo cURL.
Também vale solicitar apenas os cabeçalhos com -I, quando o servidor oferecer suporte adequado a HEAD:
curl -I https://api.exemplo.com/healthEssa verificação é rápida, mas não substitui um GET quando o endpoint trata HEAD de forma diferente ou não o implementa. A resposta precisa ser interpretada conforme a documentação da API.
Como interpretar os códigos HTTP
Não trate uma resposta recebida como sinônimo de sucesso. Por padrão, o cURL pode concluir a transferência mesmo quando o servidor devolve um código HTTP de erro. Em scripts, --fail-with-body é útil porque faz o comando sinalizar falha em respostas de erro sem descartar automaticamente o corpo que ajuda no diagnóstico. Combine a opção com o comportamento esperado pelo seu shell e teste antes de colocá-la em produção.
| Código | Leitura prática | Primeiro passo |
|---|---|---|
| 2xx | A operação foi aceita ou concluída. | Valide o corpo e os campos retornados. |
| 400 | A requisição é inválida. | Revise JSON, parâmetros e campos obrigatórios. |
| 401 ou 403 | Falta autenticação ou permissão. | Confira token, escopo, expiração e ambiente. |
| 404 | Recurso ou rota não encontrado. | Compare URL, versão e identificador. |
| 429 | Limite de requisições atingido. | Respeite Retry-After e reduza a frequência. |
| 5xx | Falha no servidor ou dependência. | Guarde o horário, request ID e tente conforme a política. |
Teste de sucesso do tutorial
Considere o teste aprovado quando você conseguir executar o GET de demonstração, visualizar uma linha 200 com -i, enviar o POST com JSON e identificar no terminal o corpo devolvido. Para transformar isso em um teste automatizado, acrescente --fail-with-body e uma validação do conteúdo retornado com a ferramenta disponível no seu ambiente, como jq. O critério deve verificar o campo que realmente importa para a integração, não apenas a ausência de mensagem de erro.
Depois de dominar a chamada manual, o mesmo raciocínio serve para webhooks, integrações e automações. O guia do JSMS sobre como criar um webhook no n8n e responder dados em JSON é um próximo passo útil para quem quer transformar uma requisição em fluxo automatizado.
Erros comuns e como evitá-los
URL incompleta: verifique o esquema HTTPS, a versão da API, o caminho e os parâmetros. Método errado: não use POST só porque espera enviar dados; confirme o contrato do endpoint. JSON inválido: valide o arquivo antes, mantenha aspas duplas dentro do JSON e não misture comentários no corpo.
Header ausente: Content-Type e Authorization têm funções diferentes; um informa o formato e o outro identifica ou autoriza o cliente. Token expirado: gere uma credencial nova no ambiente correto e confirme seus escopos. Erro de shell: comandos de Bash, PowerShell e Prompt de Comando não têm exatamente a mesma continuação de linha ou expansão de variáveis.
Confundir rede com API: primeiro teste resolução de domínio, TLS e conexão; depois analise código, cabeçalhos e corpo. Repetir POST sem cuidado: uma nova tentativa pode criar duplicidade. Use idempotência ou confirme o resultado antes de reenviar. Compartilhar saída verbosa: remova tokens, cookies, parâmetros privados e identificadores sensíveis antes de enviar logs a outra pessoa.
Conclusão
Testar uma API REST com cURL fica mais previsível quando você separa as etapas: confirmar a ferramenta, fazer um GET simples, inspecionar cabeçalhos, enviar o JSON correto, autenticar com segurança e interpretar o código HTTP. A opção -v ajuda a localizar problemas de transporte, enquanto a documentação do endpoint define o método, os campos e as permissões válidas. Esse procedimento é pequeno o bastante para uma verificação manual e claro o bastante para virar um teste de automação.
Perguntas frequentes
O cURL serve apenas para APIs?
Não. Ele transfere dados por URLs e também pode ser usado para baixar arquivos, testar serviços HTTP e automatizar chamadas em scripts.
Qual é a diferença entre -i e -v?
-i inclui os cabeçalhos da resposta no resultado. -v mostra informações detalhadas da comunicação, incluindo partes da requisição e da conexão.
Por que um 404 pode não fazer o cURL terminar com erro?
Porque a transferência HTTP pode ter sido concluída mesmo com um código de erro. Use --fail-with-body quando precisar transformar respostas HTTP de erro em falha do comando e preservar o corpo para diagnóstico.
É seguro colocar o token diretamente no comando?
Não é a opção mais segura, pois o segredo pode parar no histórico ou em registros do ambiente. Prefira variável protegida ou o mecanismo de credenciais indicado pela API.