Uma equipe pode implementar exatamente o que está na especificação e ainda assim entregar o produto errado. Também pode construir o produto certo em cima de um código cheio de defeitos. A primeira falha é de validação; a segunda é de verificação. Confundir as duas deixa o processo de qualidade ocupado, mas pouco eficaz.
Este guia define os dois conceitos, mostra as diferenças práticas e explica como aplicá-los em testes de API com Apidog.
O que é verificação?
A verificação pergunta:
Estamos construindo corretamente?
Ela confirma se uma parte do software está em conformidade com a especificação, o design e os padrões definidos. Em outras palavras, compara a implementação com uma intenção documentada.
A verificação não responde se a intenção estava correta. Ela apenas confirma se o código corresponde ao que foi especificado.
Atividades comuns de verificação:
- Revisão de código
- Walkthroughs técnicos
- Análise estática
- Linting
- Revisões de design e arquitetura
- Verificações de esquema e contrato
- Testes unitários
- Asserções de status, cabeçalhos e payloads
Exemplo simples:
POST /users
Se a especificação diz que esse endpoint deve retornar:
201 Created
Location: /users/{id}
A verificação confirma se a implementação realmente retorna 201 e o cabeçalho Location.
Ela é principalmente interna: compara artefato com artefato.
Exemplos:
- Código vs. design
- Resposta da API vs. esquema
- Implementação vs. contrato
- Endpoint vs. especificação OpenAPI
O que é validação?
A validação pergunta:
Estamos construindo a coisa certa?
Ela verifica se o software realmente atende à necessidade do usuário e resolve o problema real, independentemente do que estava escrito na especificação.
A validação compara o produto com o uso real.
Atividades comuns de validação:
- Testes de aceitação do usuário
- Testes beta
- Testes de usabilidade
- Testes ponta a ponta
- Demonstrações para stakeholders
- Aprovação de fluxos reais de negócio
Exemplo:
Uma API pode seguir perfeitamente a especificação OpenAPI e ainda assim falhar na validação se:
- O modelo de paginação for difícil de usar
- O fluxo de autenticação não funcionar bem para clientes reais
- A resposta não trouxer os dados que os consumidores precisam
- O processo exigir workarounds complicados
Nesse caso, o problema não está necessariamente no código. Pode estar na própria especificação.
Validação vs. verificação: diferenças práticas
| Dimensão | Verificação | Validação |
|---|---|---|
| Pergunta central | Estamos construindo corretamente? | Estamos construindo a coisa certa? |
| Compara com | Especificação, design, padrões | Necessidades do usuário e uso real |
| Momento | Contínuo, durante o desenvolvimento | Quando já existe algo utilizável |
| Métodos típicos | Revisão, linting, testes unitários, schema checks, contrato | Aceitação, beta, ponta a ponta, demonstrações |
| Direção | Interna: artefato vs. artefato | Externa: produto vs. realidade |
| Detecta | Bugs, desvios da especificação, quebra de contrato | Requisitos errados, problemas de usabilidade, produto inadequado |
| Risco ao ignorar | Código instável ou inconsistente | Produto correto tecnicamente, mas inútil |
As duas práticas não são intercambiáveis.
- Verificação forte com validação fraca gera um produto tecnicamente correto que talvez ninguém queira.
- Validação forte com verificação fraca gera a ideia certa implementada em código instável.
Um mnemônico útil:
Verificação testa contra o documento.
Validação testa contra o propósito.
Como aplicar isso em testes de API
APIs tornam essa diferença mais concreta porque normalmente têm um contrato explícito: OpenAPI, JSON Schema ou outra definição de interface.
Esse contrato é a base da verificação.
Verificação em APIs
Verificar uma API significa confirmar se a implementação cumpre o contrato.
Checklist de verificação:
- O endpoint retorna os status codes documentados?
- A resposta segue o schema esperado?
- Os campos têm os nomes e tipos corretos?
- Os parâmetros obrigatórios são realmente obrigatórios?
- O formato de erro segue o padrão documentado?
- Headers importantes estão presentes?
- O contrato continua compatível com consumidores existentes?
Exemplo de contrato esperado:
{
"id": "usr_123",
"email": "dev@example.com",
"created_at": "2026-01-10T12:00:00Z"
}
Asserções de verificação poderiam validar:
status === 201
body.id is string
body.email is string
body.created_at is ISO datetime
header.Location exists
Também é aqui que entra o teste de contrato de API. Ele confirma que o produtor da API continua honrando o acordo usado pelos consumidores.
Para consistência de status codes, veja também quais códigos de status HTTP as APIs REST devem usar.
As asserções de API são a unidade prática da verificação: status, schema, headers e conteúdo.
Validação em APIs
Validar uma API significa confirmar se ela atende ao consumidor em um fluxo real.
Checklist de validação:
- Um cliente consegue completar o fluxo principal sem workaround?
- O fluxo de autenticação funciona para integrações reais?
- Os dados retornados respondem às perguntas do consumidor?
- A API permite criar, atualizar, consultar e excluir recursos de forma coerente?
- Os exemplos da documentação refletem o uso real?
- O contrato faz sentido para o domínio do problema?
Exemplo de cenário de validação:
- Registrar um usuário
- Fazer login
- Criar um recurso
- Consultar o recurso criado
- Atualizar o recurso
- Confirmar que a alteração foi persistida
- Excluir o recurso
- Confirmar que ele não está mais disponível
Esse tipo de cenário valida um fluxo de uso, não apenas um endpoint isolado.
Um teste de schema de GET /users/{id} é verificação. Um fluxo completo de onboarding de usuário é validação.
Para separar melhor esses níveis, veja cenários de teste vs. casos de teste.
Onde o Apidog se encaixa
O Apidog ajuda a aplicar os dois lados porque centraliza design, teste e documentação de API em um mesmo workspace.
Usando Apidog para verificação
Para verificação, o design da API funciona como a fonte da verdade.
Fluxo prático:
- Defina ou importe a especificação da API.
- Crie testes para os endpoints.
- Adicione asserções de status, schema, headers e payload.
- Compare as respostas reais com o contrato.
- Execute os testes continuamente.
Exemplo de verificações para POST /payments:
Status esperado: 201
Campo obrigatório: payment_id
Tipo de payment_id: string
Header esperado: Location
Formato de erro para moeda inválida: conforme especificação
Como o teste usa o mesmo contrato que define a API, você reduz o risco de manter duas versões divergentes da verdade.
Para manter isso no fluxo de entrega, execute os testes em CI/CD. Veja como automatizar testes de API em CI/CD.
Usando Apidog para validação
Para validação, use cenários que encadeiam múltiplas requisições.
Exemplo de cenário:
1. Criar usuário
2. Fazer login
3. Criar recurso
4. Consultar recurso
5. Atualizar recurso
6. Confirmar atualização
7. Excluir recurso
Esse teste se aproxima do comportamento de um cliente real. Ele ajuda a responder se a API resolve o problema completo, e não apenas se cada endpoint individual está tecnicamente correto.
Os relatórios por etapa ajudam a separar os tipos de falha:
- Incompatibilidade de schema: falha de verificação
- Fluxo multi-etapas quebrado: falha de validação
- Status code incorreto: falha de verificação
- Fluxo impossível para o consumidor: falha de validação
Baixe o Apidog para configurar verificações de contrato e validações de fluxo na sua própria API.
Exemplo real: API de pagamentos
Imagine uma equipe criando uma API de pagamentos.
A especificação diz:
POST /payments
Entrada:
{
"amount": 19.99,
"currency": "BRL"
}
Resposta esperada:
201 Created
{
"payment_id": "pay_123"
}
Moedas inválidas devem retornar:
400 Bad Request
Verificação
A equipe verifica a API:
- O handler segue o design.
- O endpoint retorna
201. - O campo
payment_idexiste. - O tipo de
payment_idé string. - O erro
400segue o formato documentado. - Os testes de contrato passam.
Resultado: a API está construída corretamente segundo a especificação.
Falha de validação
Então um cliente real integra a API.
Ele percebe que amount é um número de ponto flutuante. Em alguns casos, operações como 0.1 + 0.2 geram arredondamentos incompatíveis com a fatura.
A especificação dizia:
amount:
type: number
A implementação obedeceu perfeitamente.
O problema é que a especificação estava errada. Dinheiro não deveria ser representado como float. Uma abordagem mais segura seria usar unidades menores inteiras, por exemplo:
{
"amount_cents": 1999,
"currency": "BRL"
}
Esse não é um bug simples de implementação. É uma falha de validação.
A correção não é “ajustar o código para seguir a especificação”. A correção é mudar a especificação.
Checklist prático para releases de API
Antes de publicar uma API, execute as duas listas.
Verificação: contra a especificação
Confirme que:
- Todos os endpoints retornam os status codes documentados
- Todas as respostas seguem os schemas definidos
- Campos obrigatórios são realmente obrigatórios
- Parâmetros inválidos geram os erros esperados
- Headers documentados são retornados
- O formato de erro é consistente
- Testes de contrato passam para endpoints consumidos externamente
- A suíte roda no pipeline de CI/CD
Validação: contra o propósito
Confirme que:
- Um novo consumidor consegue completar o fluxo principal
- A API resolve o caso de uso real
- O fluxo de autenticação é viável para integrações existentes
- Os dados retornados são suficientes para o cliente
- A documentação mostra exemplos realistas
- Stakeholders aprovam o comportamento final
- Não há workarounds obrigatórios para tarefas comuns
Se apenas a verificação passa, você pode ter uma implementação correta de um design errado.
Se apenas a validação passa, você pode ter a ideia certa em uma implementação frágil.
Para entregar com confiança, você precisa das duas.
Perguntas frequentes
A verificação ou a validação vem primeiro?
A verificação começa primeiro e continua durante todo o desenvolvimento. Assim que existe código, ele pode ser comparado com a especificação.
A validação acontece quando há algo utilizável para exercitar contra necessidades reais.
Teste é o mesmo que validação?
Não.
Teste é um termo mais amplo. Ele pode incluir verificação e validação.
Exemplos:
- Teste unitário: verificação
- Schema check: verificação
- Teste de contrato: verificação
- Teste de aceitação: validação
- Teste ponta a ponta: validação
Um software pode passar na verificação e falhar na validação?
Sim.
Isso acontece quando a implementação segue perfeitamente a especificação, mas a especificação resolve o problema errado.
Nesse caso, o produto está verificado, mas não validado.
Como isso se aplica a teste de contrato de API?
Teste de contrato é verificação.
Ele confirma que a API continua honrando o acordo documentado com os consumidores. Mas não confirma se esse acordo é o melhor para o uso real.
Essa segunda parte é validação.
Qual encontra mais bugs?
A verificação costuma encontrar mais defeitos em quantidade, porque roda continuamente e captura desvios pequenos cedo.
A validação tende a encontrar menos problemas, mas mais caros. Uma falha de validação geralmente indica requisito errado, design inadequado ou problema de produto.
Automação cobre os dois?
A automação cobre muito bem a verificação:
- Schema checks
- Testes de contrato
- Asserções de status
- Validação de headers
- Testes em CI/CD
A validação é mais difícil de automatizar completamente porque depende de julgamento sobre uso real. Ainda assim, testes ponta a ponta automatizados cobrem uma parte importante dos fluxos principais.
Top comments (0)