Configuração do Postman e leitura de respostas JSON

Objetivo da configuração inicial

Configurar o Postman corretamente antes de começar a testar APIs reduz erros de ambiente, evita confusões entre URLs e credenciais e melhora a leitura e validação das respostas. Nesta etapa, o foco é preparar o aplicativo para trabalhar com coleções, ambientes e autenticação de forma previsível, e aprender a interpretar respostas JSON com rapidez, identificando campos, tipos e estruturas aninhadas.

Configurações essenciais do Postman (Settings)

Acessando as configurações

No Postman, abra o menu de configurações (ícone de engrenagem). As opções podem variar por versão, mas os pontos principais são consistentes. O objetivo aqui não é “marcar tudo”, e sim ajustar o que impacta diretamente o dia a dia de QA: certificados, proxy, atualização de variáveis, e comportamento de requisições.

SSL certificate verification e cenários comuns

Em ambientes corporativos e de homologação, é comum existir um gateway com certificados internos. Se a API estiver atrás de um certificado não reconhecido pelo sistema, o Postman pode falhar com erros de handshake. A opção de verificação SSL (SSL certificate verification) controla se o Postman valida o certificado do servidor. Em geral, mantenha a verificação ativada para simular o comportamento real de clientes. Desative apenas quando você tiver certeza de que o ambiente usa certificados internos e você precisa prosseguir para testar o contrato da API. Se desativar, registre isso como uma exceção do ambiente, porque pode mascarar problemas reais de segurança.

Proxy: quando configurar

Se sua rede exige proxy para sair para a internet ou para acessar determinados domínios, configure o proxy no Postman para evitar falhas de conexão. Em empresas, isso é frequente em APIs externas (por exemplo, serviços de pagamento). Ao configurar proxy, valide com um endpoint simples (como um health check) para confirmar que o tráfego está passando corretamente. Se o proxy exigir autenticação, use as credenciais adequadas e evite salvá-las em locais não seguros; prefira variáveis de ambiente para dados sensíveis quando possível.

Request timeout e comportamento de rede

APIs podem ter latência variável em homologação. Ajustar o timeout evita que o Postman interrompa requisições longas em cenários de carga ou processamento assíncrono. Ao mesmo tempo, um timeout alto demais pode esconder problemas de performance. Uma prática útil é manter um timeout padrão moderado e, quando necessário, aumentar apenas para endpoints específicos durante investigações.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Headers automáticos e boas práticas

O Postman pode adicionar automaticamente alguns headers. Em testes, isso é útil, mas pode confundir quando você precisa reproduzir exatamente o comportamento de um cliente. Verifique se headers como User-Agent e Accept estão coerentes com o que você quer validar. Para APIs JSON, é comum trabalhar com Accept: application/json e Content-Type: application/json (para requisições com body). O ponto importante é: o Content-Type descreve o que você está enviando; o Accept descreve o que você espera receber.

Organização prática: Workspace, Collections e Requests

Criando uma coleção para o projeto

Crie uma Collection para agrupar requisições do mesmo sistema ou módulo. Isso facilita rodar testes em sequência e compartilhar com o time. Dentro da coleção, organize por pastas (por exemplo: Auth, Users, Orders). Uma organização consistente reduz o tempo para encontrar endpoints e torna o histórico de testes mais rastreável.

Padronizando nomes e descrições

Nomeie requisições com verbo e recurso, por exemplo: “GET Users - list”, “POST Orders - create”. Use a descrição da requisição para registrar pré-condições, exemplos de payload e observações de comportamento esperado. Isso ajuda quando outra pessoa precisa executar o mesmo teste sem depender de contexto externo.

Configuração de ambientes para alternar base URL e credenciais

Por que usar Environment no Postman

Ambientes permitem alternar rapidamente entre dev, homologação e produção (quando aplicável) sem editar cada requisição manualmente. O ganho principal é reduzir erros humanos: trocar uma URL em um endpoint e esquecer outro é um problema comum quando não há variáveis.

Passo a passo: criando um ambiente e variáveis

Crie um Environment e adicione variáveis como baseUrl, token e userId. Em seguida, substitua valores fixos nas requisições por variáveis usando a sintaxe de chaves duplas. Exemplo: em vez de https://api.hml.suaempresa.com, use {{baseUrl}}. Para o token, use {{token}} no header Authorization.

// Exemplo de variáveis do Environment (conceitual) baseUrl = https://api.hml.suaempresa.com token = (vazio inicialmente) userId = 123

Ao usar variáveis, você pode duplicar o ambiente para criar uma versão “dev” e outra “hml”, alterando apenas baseUrl e credenciais. Isso torna o mesmo conjunto de requisições reutilizável.

Variáveis de Collection e de Environment

Quando uma variável é específica de uma coleção (por exemplo, um caminho base para endpoints daquele domínio), faz sentido usar variável de Collection. Quando depende do ambiente (por exemplo, baseUrl e credenciais), use Environment. Essa separação evita que você misture dados de ambiente com dados de organização do projeto.

Montando uma requisição JSON corretamente

Definindo método, URL e query params

Para endpoints de listagem, é comum usar query params como page, limit, sort. No Postman, use a aba Params para adicionar pares chave-valor; isso evita erros de encoding e deixa a URL legível. Exemplo: GET {{baseUrl}}/users?page=1&limit=10.

Enviando body JSON no formato certo

Em requisições POST e PUT, selecione Body, escolha raw e defina o tipo como JSON. Isso ajuda o Postman a formatar e validar o JSON. Garanta que o header Content-Type esteja como application/json. Um erro comum é enviar JSON com aspas incorretas ou vírgulas faltando; o modo JSON do Postman costuma indicar problemas de formatação.

{ "name": "Ana", "email": "ana@example.com", "role": "admin" }

Headers mínimos para APIs JSON

• Accept: application/json
• Content-Type: application/json (quando houver body)
• Authorization: Bearer {{token}} (quando a API exigir autenticação)

Se a API usa outro esquema (por exemplo, Basic, API Key), o Postman oferece abas de Authorization que montam o header automaticamente. Mesmo assim, é importante entender o header final enviado, porque isso facilita depuração quando algo falha.

Leitura de respostas JSON: estrutura, tipos e navegação

Entendendo o que é JSON na prática

JSON é um formato de dados baseado em pares chave-valor e listas. Na resposta de uma API, você verá objetos (entre chaves) e arrays (entre colchetes). Cada campo tem um tipo: string, number, boolean, null, object ou array. Ler JSON bem significa identificar rapidamente onde está o dado relevante e como ele se relaciona com o resto da estrutura.

Visualização no Postman: Pretty, Raw e Preview

Na área de resposta, o Postman oferece modos de visualização. Pretty formata e colore o JSON, facilitando leitura. Raw mostra o texto “cru”, útil para copiar e comparar exatamente o que veio do servidor. Preview tenta renderizar conteúdo (mais útil para HTML). Para QA, Pretty e Raw são os mais usados: Pretty para entender, Raw para evidência e comparação.

Identificando metadados e payload

Muitas APIs retornam um envelope com metadados e o conteúdo principal. Por exemplo, pode existir um objeto com campos como data, pagination, links, ou status. Um padrão comum é: { "data": [...], "meta": {...} }. Ao validar, separe mentalmente o que é metadado (paginação, contagem, links) do que é payload (os itens reais). Isso evita confundir “status interno” do payload com o status HTTP.

{ "data": [ { "id": 10, "name": "Ana" }, { "id": 11, "name": "Bruno" } ], "meta": { "page": 1, "limit": 2, "total": 50 } }

Status HTTP, headers e tempo de resposta

Antes mesmo de ler o JSON, verifique o status HTTP (200, 201, 400, 401, 404, 500). Em seguida, confira headers relevantes como Content-Type, Cache-Control e, quando aplicável, Location (em criações). O tempo de resposta também é um sinal: uma resposta 200 com latência muito alta pode indicar gargalos. Essa leitura rápida ajuda a separar erro de contrato (JSON inesperado) de erro de infraestrutura (timeout, 502, 503).

Como encontrar campos rapidamente em JSON grande

Expandir e recolher nós

No modo Pretty, você pode expandir e recolher objetos e arrays. Em respostas grandes, comece recolhendo tudo e abrindo apenas o caminho necessário. Isso reduz ruído e ajuda a focar no que você precisa validar.

Busca por chave e padrões

Use a busca do Postman (quando disponível) ou copie o JSON para um editor para localizar chaves como id, status, error, message. Em APIs com erros padronizados, buscar por “error” ou “errors” costuma levar direto ao ponto. Em respostas de listagem, buscar por um id específico ajuda a confirmar se o item retornou.

Interpretando erros comuns em respostas JSON

Erros de validação (400/422)

Quando o servidor rejeita o body, é comum receber um JSON com detalhes de campos inválidos. Exemplos típicos incluem mensagens por campo, lista de erros e códigos internos. Ao analisar, procure: qual campo falhou, qual regra foi violada (obrigatório, formato, tamanho), e se o erro é consistente com o que foi enviado.

{ "message": "Validation failed", "errors": { "email": ["Invalid format"], "name": ["Required"] } }

Não autorizado (401) e proibido (403)

Em 401, normalmente o token está ausente, expirado ou inválido. Em 403, o token pode ser válido, mas sem permissão. Leia o JSON de erro e confira o header Authorization enviado. Um detalhe importante: se você alternar de ambiente e esquecer de atualizar o token, pode parecer “bug” da API, mas é apenas contexto incorreto.

Não encontrado (404) e inconsistência de rota

Um 404 pode significar rota inexistente, recurso inexistente, ou até baseUrl errada. Verifique se a URL final está correta (incluindo barras e versão, como /v1). Em APIs que retornam JSON de erro, valide se existe um campo de código e mensagem que permita diferenciar “rota não existe” de “id não encontrado”.

Erros internos (500) e respostas não-JSON

Às vezes, o servidor retorna HTML ou texto puro em falhas. Se o Postman não conseguir “prettify” como JSON, confira o Content-Type da resposta. Isso é útil para reportar: “o contrato esperado era JSON, mas a API retornou text/html”. Esse tipo de evidência ajuda o time a padronizar erros.

Passo a passo prático: requisição e leitura de resposta JSON

Passo 1: criar uma requisição GET de listagem

Crie uma requisição GET em uma coleção, aponte para um endpoint de listagem e use a variável {{baseUrl}}. Adicione query params pela aba Params. Envie a requisição e observe status, tempo e tamanho da resposta.

GET {{baseUrl}}/users?page=1&limit=5 Accept: application/json

Passo 2: validar rapidamente o “formato” da resposta

No modo Pretty, confirme se a resposta é um array direto ou um objeto com data e meta. Identifique o caminho até o item: por exemplo, response.data[0].id e response.data[0].name. Essa identificação é a base para validações posteriores e para criação de testes automatizados.

Passo 3: criar uma requisição POST e conferir o retorno

Crie uma requisição POST para criar um recurso. No Body, use raw JSON. Envie e verifique se o status é 201 (ou 200, dependendo do contrato). Confira se o JSON retornou o id criado e se os campos persistidos batem com o enviado.

POST {{baseUrl}}/users Content-Type: application/json Accept: application/json { "name": "Ana", "email": "ana@example.com" }

Passo 4: comparar o que foi enviado com o que foi recebido

Uma leitura eficiente compara campos críticos: id (gerado), name e email (ecoado ou persistido), e campos de auditoria como createdAt. Se createdAt vier como string, confirme o padrão (por exemplo, ISO 8601). Se vier null, pode indicar que o backend não está preenchendo corretamente ou que o recurso ainda não foi persistido.

{ "id": 101, "name": "Ana", "email": "ana@example.com", "createdAt": "2026-01-07T10:20:30Z" }

Trabalhando com JSON aninhado e arrays

Objetos dentro de objetos

Respostas frequentemente trazem subobjetos, como endereço dentro de usuário. Ao ler, identifique o caminho completo: user.address.city. Isso ajuda a validar se o backend está retornando a estrutura correta e se campos opcionais aparecem como null ou são omitidos, conforme o contrato.

{ "id": 10, "name": "Ana", "address": { "street": "Rua A", "city": "São Paulo", "zip": "01000-000" } }

Arrays de objetos e consistência de schema

Em arrays, valide consistência: todos os itens têm os mesmos campos essenciais? Há itens com tipos diferentes (por exemplo, id como string em um item e number em outro)? Inconsistências assim são fonte comum de bugs em front-end e integrações. Uma leitura cuidadosa do JSON detecta esses problemas cedo.

Extraindo valor de uma resposta para reutilizar em outra requisição

Conceito: capturar id/token para encadear chamadas

Em rotinas de QA, você cria um recurso e depois consulta, atualiza ou deleta. Para isso, você precisa capturar um valor da resposta (como id) e reutilizar na próxima requisição. No Postman, isso é feito com scripts na aba Tests, salvando em variáveis de ambiente ou de coleção.

Passo a passo: salvar um id em variável de ambiente

Após um POST de criação, vá em Tests e adicione um script para ler o JSON e salvar o id. Depois, use {{userId}} em uma requisição GET /users/{{userId}}. Esse encadeamento reduz trabalho manual e evita erros de copiar e colar.

// Tests (após criar usuário) const json = pm.response.json(); pm.environment.set("userId", json.id);

// Requisição seguinte GET {{baseUrl}}/users/{{userId}} Accept: application/json

Salvando token de login

Em fluxos autenticados, o login retorna um token. Capture esse token e armazene em {{token}} para que as demais requisições usem Authorization: Bearer {{token}}. Ao ler a resposta, confirme se o token está no campo esperado (por exemplo, access_token, token, jwt) e se há informações de expiração.

// Tests (após login) const json = pm.response.json(); pm.environment.set("token", json.access_token);

Checagens rápidas de qualidade ao ler JSON

Tipos corretos e campos obrigatórios

Ao validar uma resposta, observe se campos numéricos vêm como number e não como string, se booleanos vêm como true/false e não como “true”, e se campos obrigatórios não estão ausentes. Mesmo sem automatizar ainda, essa leitura manual é uma forma eficiente de detectar quebra de contrato.

Campos sensíveis e vazamento de dados

Verifique se a API não está retornando dados sensíveis indevidos, como senha, hash, tokens internos, ou informações pessoais além do necessário. Em QA, isso é um ponto de atenção: às vezes o endpoint funciona, mas expõe campos que não deveriam estar no payload.

Consistência de mensagens de erro

Quando ocorrer erro, avalie se o JSON de erro segue um padrão consistente: campos como message, code, details, traceId. A consistência facilita troubleshooting e automação de testes, porque você consegue validar o contrato de erro também, não apenas o de sucesso.